Administra los metadatos del contenedor

En esta página, se describe cómo crear contenedores, subirlos a Artifact Registry y administrar los metadatos de una imagen de contenedor almacenada en Artifact Registry como un archivo adjunto.

Los archivos adjuntos son artefactos de OCI y solo se pueden almacenar en repositorios en formato Docker.

Antes de comenzar

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

Roles obligatorios

A fin de obtener los permisos que necesitas para administrar los archivos adjuntos, solicita a tu administrador que te otorgue el los siguientes roles de IAM en el repositorio:

• Ver y descargar archivos adjuntos: Lector de Artifact Registry (roles/artifactregistry.reader)
• Crea archivos adjuntos: Escritor de Artifact Registry (roles/artifactregistry.writer)
• Borra archivos adjuntos: Administrador del repositorio de Artifact Registry (roles/artifactregistry.repoAdmin)

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.

Configura Oras (opcional)

Además de usar gcloud CLI, de manera opcional puedes usar Oras para crear, enumerar y descargar archivos adjuntos.

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 authenticate. con Artifact Registry.

Crea adjuntos

Puedes crear un archivo adjunto con la CLI de gcloud o Oras.

gcloud

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

• ATTACHMENT: Es el nombre completamente calificado. del archivo adjunto. Por ejemplo, projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment. También puedes proporcionar solo el ID del adjunto y usar los valores --location y --repository.
• TARGET: Es el nombre de la versión completamente calificado. o el URI de Artifact Registry del artefacto al que hará referencia el adjunto. Puedes usar el resumen o la etiqueta. Por ejemplo, us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1.
• TYPE: Es el atributo type del archivo adjunto. Esto debe cumplir con las especificaciones de OCI para la propiedad artifactType.
• ATTACHMENT_NAMESPACE: Es una variable específica de los archivos adjuntos que identifica la fuente de datos de los archivos adjuntos. Por ejemplo, example.com
• FILES: Es una lista separada por comas de los archivos locales que se incluirán en el archivo adjunto.

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init o gcloud auth login y gcloud config set project.

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

Windows (PowerShell)

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init o gcloud auth login y gcloud config set project.

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

Windows (cmd.exe)

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init, o gcloud auth login y gcloud config set project.

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

Para obtener más información, consulta el comando gcloud artifacts attachments create.

Oras

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

Antes de ejecutar el comando, realiza los siguientes reemplazos:

• ARTIFACT_TYPE: Es el artifactType del archivo adjunto.

• IMAGE_URI: Es el URI. para el contenedor de imagen al que hace referencia el adjunto.

• FILE: Es un archivo local para incluir como metadatos en el archivo 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 archivo 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 del contenedor a la que se referirá el archivo adjunto.

• hello-world.txt es el archivo local que el archivo 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.

Cómo mostrar una lista de archivos adjuntos

Una imagen de contenedor puede tener cualquier cantidad de archivos adjuntos que hagan referencia a ella. Puedes enumerar los archivos adjuntos con la consola de Google Cloud, la CLI de gcloud o Oras.

Console

1. En la consola de Google Cloud, abre la página Repositorios.

   Abrir la página Repositorios

2. Haz clic en el nombre del repositorio para ver sus imágenes.

3. Para ver las versiones de una imagen, haz clic en su nombre.

4. Haz clic en la versión de la imagen adecuada.

5. Para ver los archivos adjuntos de esa versión, haz clic en la pestaña Archivos adjuntos.

gcloud

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

• TARGET: Es el nombre de la versión completamente calificado. o el URI de Artifact Registry del artefacto para el que quieres enumerar los archivos adjuntos. Puedes usar cualquiera el resumen o la etiqueta. Por ejemplo, us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1.

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init o gcloud auth login y gcloud config set project.

gcloud artifacts attachments list \
    --target=TARGET

Windows (PowerShell)

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init o gcloud auth login y gcloud config set project.

gcloud artifacts attachments list `
    --target=TARGET

Windows (cmd.exe)

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init, o gcloud auth login y gcloud config set project.

gcloud artifacts attachments list ^
    --target=TARGET

Para obtener más información, consulta el comando gcloud artifacts attachments list.

Oras

Antes de ejecutar el comando, realiza el siguiente reemplazo:

• IMAGE_URI: El URI de la imagen de destino a la que hace referencia cualquier archivo adjunto de la lista.

oras discover --distribution-spec v1.1-referrers-api IMAGE_URI

En el siguiente ejemplo, se enumeran los archivos adjuntos de una imagen de contenedor, my-image, que se identifica por su URI y etiqueta:

oras discover --distribution-spec v1.1-referrers-api \
us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1

Aquí:

• v1.1-referrers-api es la API de Referrer que se usa. Para obtener más información, consulta los detalles en las especificaciones de distribución.

• 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 del contenedor para la que se enumeran los archivos adjuntos.

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

Descargar archivos adjuntos

Puedes descargar archivos adjuntos con gcloud CLI o Oras.

gcloud

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

• ATTACHMENT: Es el nombre completamente calificado. del archivo adjunto. Por ejemplo, projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment. Como alternativa, proporciona solo el ID del adjunto y usa los valores --location y --repository.
• DESTINATION: Es la ruta de acceso en el archivo local. el sistema de archivos en el que se descargará el archivo adjunto.

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init o gcloud auth login y gcloud config set project.

gcloud artifacts attachments download ATTACHMENT \
    --destination=DESTINATION

Windows (PowerShell)

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init o gcloud auth login y gcloud config set project.

gcloud artifacts attachments download ATTACHMENT `
    --destination=DESTINATION

Windows (cmd.exe)

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init, o gcloud auth login y gcloud config set project.

gcloud artifacts attachments download ATTACHMENT ^
    --destination=DESTINATION

Como alternativa a proporcionar ATTACHMENT, puedes proporcionar la marca --oci-version-name seguida del nombre de la versión completa del archivo adjunto o el URI del registro de artefactos. Puedes usar el resumen o la etiqueta. Por ejemplo: projects/my-project/locations/us-west1/repositories/my-repo/packages/my-package/versions/sha256:abc123.

Para obtener más información, consulta la Comando gcloud artifacts attachments download.

Oras

Antes de ejecutar el comando, realiza los siguientes reemplazos:

• DESTINATION: Es el directorio de destino del archivo adjunto.

• ATTACHMENT_URI: el URI del archivo adjunto que se descargará. Este es el URI del contenedor de imágenes al que hace referencia el archivo adjunto, seguido del SHA único del archivo adjunto.

oras pull -o DESTINATION ATTACHMENT_URI

El siguiente ejemplo descarga un archivo adjunto identificado por su URI y resumen:

oras pull -o . us-west1-docker.pkg.dev/my-project/my-repo/my-image@sha256:xxxx

Aquí:

• -o . asigna el nombre del directorio actual como destino de descarga.

• us-west1-docker.pkg.dev/my-project/my-repo/my-image@sha256:xxxx es el URI de la imagen, incluido el resumen del archivo adjunto que se descargará.

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

Borrar archivos adjuntos

Puedes borrar archivos adjuntos directamente con la consola de Google Cloud o la CLI de gcloud. Puedes eliminar archivos adjuntos indirectamente borrando el imagen de contenedor a la que hace referencia.

Borrar archivos adjuntos directamente

Puedes borrar archivos adjuntos directamente con una de las siguientes opciones:

Console

1. En la consola de Google Cloud, abre la página Repositorios.

   Abrir la página Repositorios

2. Haz clic en el nombre del repositorio para ver las imágenes en él.

3. Haz clic en el nombre de la imagen para ver las versiones correspondientes.

4. Haz clic en la versión de la imagen cuyos archivos adjuntos quieras ver.

5. Haz clic en la pestaña Archivos adjuntos para ver los archivos adjuntos de esa versión.

6. Haz clic en el resumen del archivo adjunto para borrarlo.

7. Haz clic en BORRAR.

8. En el diálogo de confirmación, haz clic en BORRAR.

gcloud

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

• ATTACHMENT: Es el nombre completamente calificado. del archivo adjunto. Por ejemplo, projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment. Como alternativa, proporciona solo el ID del adjunto y usa los valores --location y --repository.

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init o gcloud auth login y gcloud config set project.

gcloud artifacts attachments delete ATTACHMENT

Windows (PowerShell)

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init o gcloud auth login y gcloud config set project.

gcloud artifacts attachments delete ATTACHMENT

Windows (cmd.exe)

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init, o gcloud auth login y gcloud config set project.

gcloud artifacts attachments delete ATTACHMENT

Para obtener más información, consulta el comando gcloud artifacts attachments list.

Borrar archivos adjuntos de forma indirecta

Si se borra una imagen de contenedor, también se borran todos los archivos adjuntos de referencia. Esto se aplica tanto a la eliminación manual de imágenes de contenedores como a las eliminaciones causadas por las políticas de limpieza.

Nota: Las políticas de limpieza no se aplican directamente a los archivos adjuntos. Sin embargo, si una política de limpieza borra una imagen de contenedor, se borran todos los archivos adjuntos que se refieren a esa imagen.