Envía y extrae imágenes

En esta página, se describe el envío y la extracción de imágenes de contenedor con Docker. También proporciona información sobre cómo extraer imágenes con la herramienta crictl si estás usando y la solución de problemas en Google Kubernetes Engine.

Para obtener información sobre la implementación en entornos de ejecución de Google Cloud, consulta Implementa en Google Cloud.

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

Antes de comenzar

  1. Si el repositorio de destino no existe, crea un repositorio nuevo.
  2. Debes tener al menos el acceso de escritor de Artifact Registry al repositorio.
  3. Instala Docker si todavía no está instalada.

Roles obligatorios

A fin de obtener los permisos que necesitas para enviar y extraer imágenes, solicita a tu administrador que te otorgue el los siguientes roles de IAM en el repositorio:

Si quieres obtener más información para otorgar roles, consulta Administra el acceso.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Autenticación en un repositorio

Debes autenticarte en los repositorios cada vez que uses Docker o algún otro cliente de terceros con un repositorio de Docker. En esta sección, se proporciona un breve resumen de lo que necesitarás para autenticarte correctamente. Para obtener información consulta Configura la autenticación para Docker.

Usa un auxiliar de credenciales

Para el auxiliar de credenciales de gcloud CLI o el asistente de credenciales independiente, Los hosts de Artifact Registry que usas 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 muchos registros configurados. Para minimizar la cantidad de registros en el archivo de configuración, debes agregar los hosts que necesites al .

Para confirmar qué hosts están configurados, ejecuta el siguiente comando para mostrarlos 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 para el auxiliar 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 el host que quieres usar no está en la lista, vuelve a ejecutar el auxiliar de credenciales. para agregar el host. Por ejemplo, el siguiente comando agrega us-west1-docker.pkg.dev.

  • Auxiliar 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

Usa un token de acceso

Para la autenticación de token de acceso, se genera un token y se usa como contraseña. con el comando docker login. Los tokens son válidos durante 60 minutos, por lo que deben autenticarse poco antes de que etiquetes, envíes o extraigas imágenes.

En el siguiente ejemplo, se genera un token de acceso con una cuenta de servicio robo de identidad y, luego, se autentica en Artifact Registry. Debes tener tener permisos en el rol de Creador de tokens de cuentas 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 permiso para usar la identidad de una cuenta de servicio, puedes activa la cuenta de servicio en tu sesión de gcloud CLI y, luego, obtén un token. Si quieres obtener detalles, consulta las instrucciones para configurar el token de acceso. la autenticación de varios factores.

Usa una clave de cuenta de servicio

Para una clave de cuenta de servicio, debes usarla como una contraseña con el docker login kubectl.

Por ejemplo, el siguiente comando usa la clave de la cuenta de servicio codificada en base64 en el archivo key.json para autenticarte 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

Si quieres obtener más detalles, consulta las instrucciones para configurar la autenticación con una clave de cuenta de servicio.

Envíe una imagen

Modos de repositorio: Estándar

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

Si tu 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 en un repositorio de confianza. Para obtener más información sobre resúmenes de imágenes, etiquetas y etiquetas inmutabilidad, consulta Versiones de imágenes de contenedor.

En el caso de 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 por 60 minutos. Si crees que el tiempo de carga superará los 60 minutos Usar 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 una sola carga monolítica. Debes usar cargas monolíticas para enviar imágenes a Artifact Registry.

Etiqueta la imagen local

  1. Asegúrate de estar autenticado en el repositorio.

  2. Determina el nombre de la imagen. El formato del nombre de imagen completo es el siguiente:

    LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE

    Reemplaza los siguientes valores:

    • LOCATION es el regional o multirregional location del repositorio en el que se encuentra cuando se almacena.

    • PROJECT-ID es tu consola de Google Cloud ID del proyecto: 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

    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.

  3. 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. TAG con la etiqueta Si no especificas una etiqueta, Docker aplica la etiqueta latest predeterminada.

    Si se habilita la 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 a en el repositorio si la etiqueta ya se usa en otra versión de la misma en el repositorio. Para verificar si el parámetro está habilitado 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

  1. Asegúrate de estar 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.

  2. 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 de Google Cloud para ver 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]

    El siguiente resultado de ejemplo muestra resúmenes de imágenes truncadas, 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

  1. Asegúrate de estar 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.

  2. 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 el regional o multirregional location del repositorio en el que se encuentra cuando se almacena.
    • PROJECT es tu consola de Google Cloud ID del proyecto: 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 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 de un repositorio remoto, descarga y almacena en caché la imagen de la fuente upstream si una copia almacenada en caché no se existen.

Si solicitas una imagen de un repositorio virtual, Artifact Registry busca repositorios ascendentes para la imagen solicitada. Si solicitas un que está disponible en más de un repositorio upstream, Artifact Registry elige un repositorio upstream para usar según el la configuración de prioridad establecida para el repositorio virtual.

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

  • main-repo: Se estableció la prioridad en 100
  • secondary-repo1: Se estableció la prioridad en 80.
  • secondary-repo2: Se estableció la prioridad en 80.
  • test-repo: Se estableció la prioridad en 20.

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

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

test-repo tiene el valor de prioridad más bajo y entregará un artefacto almacenado si ninguno de los otros repositorios ascendentes la tiene.

Extrayendo imágenes con crictl

crictl es una herramienta de línea de comandos útil para que depuren los desarrolladores de entornos de ejecución de CRI del entorno de ejecución sin configurar componentes de Kubernetes. Si el Los nodos 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:

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

    Ir a Instancias de VM

  2. Establece una conexión SSH el nodo del que estás solucionando problemas.

  3. 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"

  4. 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

    o

    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?