Almacenar 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 archivo adjunto.

Los metadatos almacenados en los archivos adjuntos pueden incluir información sobre vulnerabilidades de artefactos, procedencia de compilación, contenido de paquetes, certificación, evaluación de vulnerabilidades, lista de materiales de software (SBOM) y más. Los sistemas de políticas pueden usar la información almacenada en los archivos adjuntos de Artifact Registry, y los usuarios pueden inspeccionarla para asegurarse de que se cumple la normativa.

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

Antes de empezar

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

Roles obligatorios

Para obtener los permisos que necesitas para crear archivos adjuntos, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Escritor de Artifact Registry (roles/artifactregistry.writer) en el repositorio. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Crear un archivo adjunto

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

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

Para crear un archivo adjunto, sigue estos pasos:

gcloud (todos los formatos)

Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:

  • ATTACHMENT: el nombre completo del archivo adjunto, como projects/my-project/locations/u-france-east1/repositories/my-repo/attachments/my-attachment. También puedes proporcionar solo el ID del archivo adjunto y usar las marcas --location y --repository.
  • TARGET: el nombre de versión completo. En el caso de las imágenes Docker, también puede usar el URI de Artifact Registry del artefacto al que hace referencia el archivo adjunto. En el URI, puedes usar el digest o, en el caso de las imágenes Docker, la etiqueta. Por ejemplo: u-france-east1-docker.s3nsregistry.fr/my-project/my-repo/my-image:tag1.
  • TYPE: el atributo type del archivo adjunto. En el caso de las imágenes Docker, el type debe cumplir las especificaciones de OCI para la propiedad artifactType.
  • ATTACHMENT_NAMESPACE: una variable específica de los archivos adjuntos que identifica la fuente de datos del archivo adjunto, como example.com.
  • FILES: lista separada por comas de archivos locales que se incluirán en el archivo 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 archivo adjunto con Oras, Artifact Registry genera un UUID aleatorio que se usa como nombre del archivo 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, haz las siguientes sustituciones:

  • ARTIFACT_TYPE: el artifactType del archivo adjunto.

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

  • FILE: un archivo local que se incluirá como metadatos en el archivo 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 archivo adjunto, hello-world.txt, que hace referencia a una imagen de contenedor, my-image, identificada por su URI y su etiqueta:

  oras attach --artifact-type doc/example \
  u-france-east1-docker.s3nsregistry.fr/my-project/my-repo/my-image:tag1 \
  hello-world.txt:application/vnd.me.hi

Donde:

  • doc/example define la propiedad artifactType del archivo adjunto.

  • u-france-east1-docker.s3nsregistry.fr/my-project/my-repo/my-image:tag1 es el URI que incluye la etiqueta de la versión de la imagen del contenedor a la que hará referencia el archivo adjunto.

  • hello-world.txt es el archivo local que contendrá los datos del archivo adjunto.

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

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

Gestionar archivos adjuntos con políticas de limpieza

Los archivos adjuntos de los repositorios de Docker, incluida la procedencia de las compilaciones, se eliminan cuando se eliminan los artefactos a los que están adjuntos. Si usas políticas de limpieza para eliminar imágenes de tu repositorio, de forma predeterminada, los archivos adjuntos de esas imágenes también se eliminarán.

Para asegurarte de que una política de limpieza no elimine por error los archivos adjuntos que quieras conservar, puedes asignar una etiqueta a una imagen que tenga archivos adjuntos que quieras conservar. Después, 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