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 archivos 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 y los usuarios pueden inspeccionar la información almacenada en los archivos adjuntos de Artifact Registry para garantizar el cumplimiento.

Para obtener más información sobre cómo trabajar con archivos adjuntos, consulta Administra metadatos con archivos 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 Google Cloud CLI.

Roles obligatorios

Para obtener los permisos que necesitas para crear archivos adjuntos, pídele a tu administrador que te otorgue el rol de IAM de 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 mediante roles personalizados o cualquier otro rol predefinido.

Crea un adjunto

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

Puedes usar gcloud CLI o Oras para crear archivos adjuntos en repositorios con formato de Docker.

Para crear un adjunto, completa los siguientes pasos:

gcloud (todos los formatos)

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

  • ATTACHMENT: Es 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 marcas --location y --repository.
  • TARGET: Es 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: Es el atributo type del adjunto. En el caso de las imágenes de Docker, el type debe cumplir con las especificaciones de OCI para la propiedad artifactType.
  • ATTACHMENT_NAMESPACE: Es una variable específica de los adjuntos que identifica la fuente de datos del adjunto, como example.com.
  • FILES: Es 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 para Docker)

Cuando creas 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 autenticarte con Artifact Registry.

Antes de ejecutar el comando, realiza los siguientes reemplazos:

  • ARTIFACT_TYPE: Es el artifactType del adjunto.

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

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

  • MEDIA_TYPE: Es 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 documentación de oras attach.

Administra archivos adjuntos con políticas de limpieza

Los archivos adjuntos del repositorio de Docker, incluida la procedencia de la 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 archivos adjuntos de esas imágenes.

Para asegurarte de que una política de limpieza no borre accidentalmente los archivos adjuntos que quieres conservar, puedes asignar una etiqueta a una imagen que tenga archivos adjuntos que quieras 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?