Se usó la API de Cloud Translation para traducir esta página.

Envía y extrae imágenes

En esta página, se describe cómo enviar y extraer imágenes de contenedores con Docker. También proporciona información para extraer imágenes con la herramienta crictl si tienes problemas para solucionar problemas en Google Kubernetes Engine.

Si necesitas información para implementar en entornos de ejecución de Google Cloud , consulta Cómo implementar en Google Cloud.

Para obtener instrucciones sobre cómo enumerar, etiquetar y borrar imágenes, consulta Administra imágenes.

Antes de comenzar

Si el repositorio de destino no existe, crea un repositorio nuevo.
Debes tener al menos el acceso de escritor de Artifact Registry al repositorio.
Instala Docker, si aún no se encuentra instalado.

Roles obligatorios

Para obtener los permisos que necesitas para enviar y extraer imágenes, pídele a tu administrador que te otorgue los siguientes roles de IAM en el repositorio:

Extrae imágenes: Lector de Artifact Registry (roles/artifactregistry.reader)
Etiquetar e insertar imágenes: Escritor de Artifact Registry (roles/artifactregistry.writer)

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.

Cómo autenticar en un repositorio

Debes autenticarte en los repositorios cada vez que uses Docker o cualquier otro cliente externo con un repositorio de Docker. En esta sección, se proporciona un resumen rápido de lo que necesitarás para realizar la autenticación correctamente. Para obtener instrucciones detalladas, consulta Configura la autenticación para Docker.

Usa un auxiliar de credenciales

Para el auxiliar de credenciales de gcloud CLI o el auxiliar de credenciales independiente, los servidores de Artifact Registry que uses deben estar en tu archivo de configuración de Docker.

Artifact Registry no agrega automáticamente todos los hosts de registro al archivo de configuración de Docker. El tiempo de respuesta de Docker es mucho más lento cuando hay una gran cantidad de registros configurados. Para minimizar la cantidad de registros en el archivo de configuración, agrega los hosts que necesitas al archivo.

Para confirmar qué hosts están configurados, ejecuta el siguiente comando para mostrar el contenido del archivo de configuración:

Linux: cat ~/.docker/config.json
Windows: cat %USERPROFILE%\.docker\config.json

En la sección credHelpers, se enumeran los hosts de Docker de Artifact Registry configurados. Los nombres de host terminan en -docker.pkg.dev. En el siguiente ejemplo, se muestran algunos hosts configurados para el asistente de credenciales de gcloud CLI.

"credHelpers": {
  "asia.gcr.io": "gcloud",
  "eu.gcr.io": "gcloud",
  "gcr.io": "gcloud",
  "marketplace.gcr.io": "gcloud",
  "northamerica-northeast1-docker.pkg.dev": "gcloud",
  "us-central1-docker.pkg.dev": "gcloud",
  "us-east1-docker.pkg.dev": "gcloud",
  "us.gcr.io": "gcloud"
}

Si un host que quieres usar no está en la lista, vuelve a ejecutar el asistente de credenciales para agregarlo. Por ejemplo, el siguiente comando agrega us-west1-docker.pkg.dev.

El asistente de credenciales de gcloud CLI:

gcloud auth configure-docker us-west1-docker.pkg.dev

Auxiliar de credenciales independiente

docker-credential-gcr configure-docker us-west1-docker.pkg.dev

Cómo usar un token de acceso

Para la autenticación de tokens de acceso, generas un token y lo usas como contraseña con el comando docker login. Los tokens son válidos durante 60 minutos, por lo que debes autenticarte poco antes de etiquetar, enviar o extraer imágenes.

En el siguiente ejemplo, se genera un token de acceso con la suplantación de identidad de la cuenta de servicio y, luego, se autentica en Artifact Registry. Debes tener permisos en el rol de creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) para generar un token de esta manera.

Linux

gcloud auth print-access-token \
  --impersonate-service-account  ACCOUNT | docker login \
  -u oauth2accesstoken \
  --password-stdin https://LOCATION-docker.pkg.dev

Windows

gcloud auth print-access-token \
--impersonate-service-account  ACCOUNT

ya29.8QEQIfY_...

docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
https://LOCATION-docker.pkg.dev

Si no tienes permisos para suplantar la identidad de una cuenta de servicio, puedes activarla en tu sesión de gcloud CLI y, luego, obtener un token. Para obtener más información, consulta las instrucciones para configurar la autenticación con tokens de acceso.

Usa una clave de cuenta de servicio

En el caso de una clave de cuenta de servicio, la usas como contraseña con el comando docker login.

Por ejemplo, el siguiente comando usa la clave de cuenta de servicio codificada en base64 en el archivo key.json para autenticarse en us-west1-docker.pkg.dev.

Linux

cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-west1-docker.pkg.dev

Windows

docker login -u _json_key_base64 --password-stdin https://us-west1-docker.pkg.dev < key.json

Para obtener más información, consulta las instrucciones para configurar la autenticación de clave de cuenta de servicio.

Envíe una imagen

Modos de repositorio: estándar

Para enviar una imagen local a un repositorio estándar de Docker, debes etiquetarla con el nombre del repositorio y, luego, enviarla.

Si el repositorio de Docker de Artifact Registry tiene habilitada la inmutabilidad de etiquetas, una etiqueta siempre debe hacer referencia al mismo resumen de imágenes en el repositorio. No puedes usar la etiqueta en otra versión de la misma imagen que envíes al repositorio. Para obtener más información sobre los resúmenes de imágenes, las etiquetas y la inmutabilidad de las etiquetas, consulta Versiones de imágenes de contenedor.

Para las imágenes grandes, se aplican los siguientes límites:

Hora de carga: Si te autenticas en Artifact Registry con un token de acceso, este solo es válido durante 60 minutos. Si crees que el tiempo de carga excederá los 60 minutos, usa un método de autenticación diferente.
Tamaño de la imagen: El tamaño máximo de los artefactos es de 5 TB.; Artifact Registry no es compatible con las cargas fragmentadas de Docker. Algunas herramientas admiten la carga de imágenes grandes con cargas fragmentadas o una sola carga monolítica. Debes usar cargas monolíticas para enviar imágenes a Artifact Registry.

Etiqueta la imagen local

Asegúrate de que se haya autenticado en el repositorio.
Determina el nombre de la imagen. El formato de un nombre de imagen completo es el siguiente:
```
LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
```
Reemplaza los siguientes valores:
- LOCATION es la ubicación regional o multirregional del repositorio en la que se almacena la imagen.
- PROJECT-ID es el ID de tu proyecto de la consola de Google Cloud . Si el ID de tu proyecto contiene dos puntos (:), consulta Proyectos con alcance de dominio.
- REPOSITORY es el nombre del repositorio en el que se almacena la imagen.
- IMAGE es el nombre de la imagen. Puede ser diferente del nombre local de la imagen.
Por ejemplo, considera una imagen con las siguientes características:
- Ubicación del repositorio: us-west1
- Nombre del repositorio: my-repo
- ID del proyecto: my-project
- Nombre de la imagen local: my-image
- Nombre de la imagen de destino: test-image
El nombre de la imagen para este ejemplo es el siguiente:
```
us-west1-docker.pkg.dev/my-project/my-repo/test-image
```
Nota: El nombre de la imagen que almacenarás en el repositorio puede ser diferente del nombre de la imagen en tu máquina local.

Para obtener detalles sobre el formato del nombre de la imagen, incluido el manejo de proyectos con alcance de dominio, consulta Nombres de imágenes y repositorios.
Etiqueta la imagen local con el nombre del repositorio.
```
docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
```
Reemplaza SOURCE-IMAGE por el nombre de la imagen local o el ID de la imagen y TAG por la etiqueta. Si no especificas una etiqueta, Docker aplica la etiqueta predeterminada latest.

Si está habilitado el parámetro de configuración de etiquetas de imagen inmutables, las etiquetas deben ser únicas para cada versión de la imagen, incluida la etiqueta latest. No puedes enviar una imagen al repositorio si otra versión de la misma imagen en el repositorio ya usa la etiqueta. Para verificar si el parámetro de configuración está habilitado para el repositorio, ejecuta el siguiente comando:
```
gcloud artifacts repositories describe REPOSITORY \
    --project=PROJECT-ID \
    --location=LOCATION
```
Para la imagen de ejemplo del paso anterior, usarías el siguiente comando si la imagen local my-image se encontrara en el directorio actual:
```
docker tag my-image us-west1-docker.pkg.dev/my-project/my-repo/test-image
```
Si deseas aplicar una etiqueta específica, usa el siguiente comando:
```
docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
```
Para usar la etiqueta staging con la imagen de ejemplo, debes agregar :staging al comando:
```
docker tag my-image us-west1-docker.pkg.dev/my-project/my-repo/test-image:staging
```

Envía la imagen con etiqueta a Artifact Registry

Asegúrate de que se haya autenticado en el repositorio.

Si usaste gcloud auth configure-docker o docker-credential-gcr configure-docker para configurar tu cliente de Docker, verifica que el nombre de host de destino esté en tu archivo de configuración de Docker.
Envía la imagen con etiquetas mediante el siguiente comando:
```
docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
```
Este comando envía la imagen con la etiqueta latest. Si deseas enviar una imagen con una etiqueta diferente, usa el siguiente comando:
```
docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
```

Cuando envías una imagen, se almacena en el repositorio especificado.

Después de enviar tu imagen, puedes hacer lo siguiente:

Ve a la consola deGoogle Cloud para ver la imagen.

Ejecuta el comando gcloud para ver el resumen generado automáticamente y las etiquetas de la imagen:

gcloud artifacts docker images list \
LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE [--include-tags]

En el siguiente resultado de ejemplo, se muestran resúmenes de imágenes truncados, pero el comando siempre muestra el resumen completo de la imagen.

 IMAGE                                                 DIGEST         CREATE_TIME          UPDATE_TIME
  us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:45  2019-04-10T15:08:45
  us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:238...  2019-04-10T17:23:53  2019-04-10T17:23:53
  us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:46  2019-04-10T15:08:46

Extrae imágenes con Docker

Modos de repositorio: estándar, remoto, virtual

Asegúrate de que se haya autenticado en el repositorio.

Si usaste gcloud auth configure-docker o docker-credential-gcr configure-docker para configurar tu cliente de Docker, verifica que el nombre de host de destino esté en tu archivo de configuración de Docker.
Para extraer imágenes de un repositorio, usa el siguiente comando:
```
docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
```
o
```
docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST
```
Reemplaza los siguientes valores:
- LOCATION es la ubicación regional o multirregional del repositorio en la que se almacena la imagen.
- PROJECT es el ID de tu proyecto de la consola de Google Cloud . Si el ID de tu proyecto contiene dos puntos (:), consulta Proyectos con alcance de dominio.
- PROJECT es el ID de tu proyecto de la consola de Google Cloud .
- REPOSITORY es el nombre del repositorio en el que se almacena la imagen.
- IMAGE es el nombre de la imagen en el repositorio.
- TAG es la etiqueta de la versión de la imagen que deseas extraer.
- IMAGE-DIGEST es el valor de hash sha256 del contenido de la imagen. Cada versión de una imagen tiene un resumen de imagen único. En la consola de Google Cloud , haz clic en la imagen específica para ver sus metadatos. El resumen se muestra como el resumen de la imagen.
Por ejemplo, considera una imagen con las siguientes características:
- Ubicación del repositorio: us-west1
- Nombre del repositorio: my-repo
- ID del proyecto: my-project
- Nombre de la imagen: test-image
- Etiqueta: staging
El comando para extraer la imagen es el siguiente:
```
docker pull us-west1-docker.pkg.dev/my-project/my-repo/test-image:staging
```

Docker descarga la imagen especificada.

Si solicitas una imagen desde un repositorio remoto, este la descarga y la almacena en caché desde la fuente upstream si no existe una copia almacenada en caché.

Si solicitas una imagen desde un repositorio virtual, Artifact Registry busca la imagen solicitada en los repositorios upstream. Si solicitas una versión que está disponible en más de un repositorio upstream, Artifact Registry elige un repositorio upstream para usar en función de la configuración de prioridad configurada para el repositorio virtual.

Por ejemplo, considera un repositorio virtual con la siguiente configuración de prioridad para los repositorios upstream:

main-repo: Prioridad establecida en 100
secondary-repo1: Prioridad establecida en 80.
secondary-repo2: Prioridad establecida en 80.
test-repo: Prioridad establecida en 20.

main-repo tiene el valor de prioridad más alto, por lo que el repositorio virtual siempre lo busca primero.

Tanto secondary-repo1 como secondary-repo2 tienen la prioridad establecida en 80. Si una imagen solicitada no está disponible en main-repo, Artifact Registry busca en estos repositorios a continuación. Dado que ambos tienen el mismo valor de prioridad, Artifact Registry puede elegir entregar una imagen de cualquiera de los repositorios si la versión está disponible en ambos.

test-repo tiene el valor de prioridad más bajo y publicará un artefacto almacenado si ninguno de los otros repositorios upstream lo tiene.

Extrae imágenes con `crictl`

crictl es una herramienta de línea de comandos útil para que los desarrolladores del entorno de ejecución de CRI depuren su entorno de ejecución sin necesidad de configurar componentes de Kubernetes. Si tus nudos de Google Kubernetes Engine usan un entorno de ejecución containerd, puedes extraer imágenes de Artifact Registry con crictl.

Dado que crictl es principalmente una herramienta de solución de problemas, algunos comandos de Docker, como enviar o etiquetar imágenes, no están disponibles.

Para extraer una imagen de Artifact Registry, haz lo siguiente:

En la consola de Google Cloud , ve a la página Instancias de VM.

Ir a Instancias de VM
Establece una conexión SSH al nodo del que estás solucionando el problema.

Obtén un token de acceso para la autenticación con el repositorio.

curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" -H "Metadata-Flavor: Google"

Extrae la imagen con crictl pull --creds y el valor access_token

crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST

El resultado luce de la siguiente manera:

Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5

¿Qué sigue?

Obtén información para administrar etiquetas y borrar imágenes.
Si deseas ejecutar contenedores en Compute Engine, obtén más información sobre contenedores en Compute Engine.
Usa crictl para depurar nodos de Kubernetes
Aprende a usar crictl para extraer imágenes de los repositorios privados de Artifact Registry
Más información para configurar registros de imágenes de crictl

Envía y extrae imágenes

Antes de comenzar

Roles obligatorios

Cómo autenticar en un repositorio

Usa un auxiliar de credenciales

Cómo usar un token de acceso

Linux

Windows

Usa una clave de cuenta de servicio

Linux

Windows

Envíe una imagen

Etiqueta la imagen local

Envía la imagen con etiqueta a Artifact Registry

Extrae imágenes con Docker

Extrae imágenes con crictl

¿Qué sigue?

Extrae imágenes con `crictl`