Almacena metadatos de artefactos en archivos adjuntos

En esta página, se describe cómo almacenar metadatos relacionados con un artefacto almacenado en Artifact Registry como un adjunto.

Los metadatos almacenados en los adjuntos pueden incluir información sobre las vulnerabilidades de los artefactos, la procedencia de la compilación, el contenido del paquete, la certificación, la evaluación de vulnerabilidades, la lista de materiales de software (SBOM) y mucho más. Los sistemas de políticas pueden usar la información almacenada en los adjuntos de Artifact Registry, y los usuarios pueden inspeccionarla para garantizar el cumplimiento.

Para obtener más información sobre cómo trabajar con adjuntos, consulta Administra metadatos con adjuntos.

Antes de comenzar

  1. Si aún no tienes uno, crea un repositorio en modo estándar.
  2. (Opcional) Configura valores predeterminados para los comandos de la Google Cloud CLI.

Roles obligatorios

Para obtener los permisos que necesitas para crear adjuntos, pídele a tu administrador que te otorgue el rol de IAM Escritor de Artifact Registry (roles/artifactregistry.writer) en el repositorio. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Crea un adjunto

En el caso de los repositorios de Docker, los adjuntos deben ser artefactos de OCI. Para todos los formatos que no sean Docker, los adjuntos pueden ser de cualquier tipo de archivo.

Para crear un adjunto, realiza los pasos que se indican a continuación.

gcloud (todos los formatos)

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

  • ATTACHMENT: el nombre completamente calificado del adjunto, como projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment. Como alternativa, proporciona solo el ID del adjunto y usa las --location y --repository marcas.
  • TARGET: el nombre de la versión completamente calificado. Solo para imágenes de Docker, también puedes usar el URI de Artifact Registry del artefacto al que hace referencia el adjunto. En el URI, puedes usar el resumen o, para las imágenes de Docker, la etiqueta, por ejemplo, us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1.
  • TYPE: el atributo type del adjunto. Para las imágenes de Docker, el type debe cumplir con las especificaciones de OCI para la propiedad artifactType.
  • ATTACHMENT_NAMESPACE: una variable específica de los adjuntos que identifica la fuente de datos del adjunto, como example.com.
  • FILES: una lista separada por comas de los archivos locales que se incluirán en el adjunto.

      • Ejecuta el siguiente comando:

      Linux, macOS o Cloud Shell

      gcloud artifacts attachments create ATTACHMENT \
    --target=TARGET \
    --attachment-type=TYPE \
    --attachment-namespace=ATTACHMENT_NAMESPACE \
    --files=FILES

      Windows (PowerShell)

      gcloud artifacts attachments create ATTACHMENT `
    --target=TARGET `
    --attachment-type=TYPE `
    --attachment-namespace=ATTACHMENT_NAMESPACE `
    --files=FILES

      Windows (cmd.exe)

      gcloud artifacts attachments create ATTACHMENT ^
    --target=TARGET ^
    --attachment-type=TYPE ^
    --attachment-namespace=ATTACHMENT_NAMESPACE ^
    --files=FILES
             Para obtener más información, consulta el comando gcloud artifacts attachments create.

Oras (solo Docker)

Cuando se crea un adjunto con Oras, Artifact Registry genera un UUID aleatorio para usarlo como nombre del adjunto.

Antes de usar Oras, completa los siguientes pasos:

  1. Instala Oras 1.2 o una versión posterior. Para verificar tu versión, ejecuta el comando oras version.

  2. Configura Oras para que se autentique con Artifact Registry.

Antes de ejecutar el comando, realiza los siguientes reemplazos:

  • ARTIFACT_TYPE: el artifactType del adjunto.

  • IMAGE_URI: el URI del contenedor de imágenes al que hace referencia el adjunto.

  • FILE: un archivo local que se incluirá como metadatos en el adjunto.

  • MEDIA_TYPE: el mediaType de la capa.

  oras attach --artifact-type ARTIFACT_TYPE IMAGE_URI FILE:MEDIA_TYPE

En el siguiente ejemplo, se crea un adjunto que consta de un archivo, hello-world.txt, que hace referencia a una imagen de contenedor, my-image, identificada por su URI y etiqueta:

  oras attach --artifact-type doc/example \
  us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1 \
  hello-world.txt:application/vnd.me.hi

Aquí:

  • doc/example define la propiedad artifactType del adjunto.

  • us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1 es el URI que incluye la etiqueta de la versión de la imagen de contenedor a la que hará referencia el adjunto.

  • hello-world.txt es el archivo local que el adjunto contendrá como sus datos.

  • application/vnd.me.hi define el mediaType de la capa.

Para obtener una guía completa y más ejemplos, consulta la oras attach documentación.

Administra adjuntos con políticas de limpieza

Los adjuntos del repositorio de Docker, incluida la procedencia de compilación, se borran cuando se borran los artefactos a los que están adjuntos. Si usas políticas de limpieza para borrar imágenes de tu repositorio, de forma predeterminada, también se borrarán los adjuntos de esas imágenes.

Para asegurarte de que una política de limpieza no borre accidentalmente los adjuntos que deseas conservar, puedes asignar una etiqueta a una imagen que tenga adjuntos que deseas conservar. Luego, puedes configurar una política de limpieza para conservar las imágenes con esas etiquetas. Por ejemplo, puedes asignar una etiqueta production-signed a las imágenes con procedencia de compilación adjunta.

¿Qué sigue?