Envía y extrae imágenes

En esta página, se describe cómo enviar y extraer imágenes de contenedor.

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 aún no se encuentra instalado.

Autentica en un repositorio

Debes autenticarte en 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 resumen rápido de lo que necesitarás para autenticar de forma correcta. Si deseas obtener instrucciones detalladas, consulta la sección sobre cómo configurar la autenticación para Docker.

Usa un asistente de credenciales

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

Artifact Registry no agrega de forma automática 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.

A fin de 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 configurados de Docker de Artifact Registry. Los nombres de host terminan en -docker.pkg.dev. En el siguiente ejemplo, se muestran algunos hosts configurados para el auxiliar de credenciales de gcloud.

"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 asistente de credenciales para agregar el host. Por ejemplo, el siguiente comando agrega us-east1-docker.pkg.dev.

  • auxiliar de credenciales de gcloud:

    gcloud auth configure-docker us-east1-docker.pkg.dev
    
  • Auxiliar de credenciales independiente

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

Usa un token de acceso

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

En el siguiente ejemplo, se genera un token de acceso mediante el robo de identidad de cuentas de servicio y, luego, se autentica en Artifact Registry. Debes tener permisos en la función 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 actuar como una cuenta de servicio, puedes activarla en tu sesión de gcloud y obtener un token. Si quieres obtener más información, consulta las instrucciones para configurar la autenticación del token de acceso.

Usa una clave de cuenta de servicio

Para una clave de cuenta de servicio, usa la clave como contraseña con el comando docker login.

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

Linux

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

Windows

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

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

Envía una imagen

Para enviar una imagen local a un repositorio de Artifact Registry, debes etiquetarla con el nombre del repositorio y, luego, enviarla.

Si vas a subir imágenes grandes, se aplican los siguientes límites:

Hora de carga
Si te autenticas en Artifact Registry mediante un token de acceso, este solo será válido durante 60 minutos. Si esperas que el tiempo de carga sea superior a 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 admite 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

  1. Asegúrate de haber autenticado el repositorio.

  2. Determina el nombre de la imagen. Este es el formato de un nombre de imagen completo:

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

    Reemplaza los siguientes valores:

    • LOCATION es la ubicación regional o multirregional del repositorio en el que se almacena la imagen, por ejemplo, us-east1 o us.

    • PROJECT es el ID de tu proyecto de Google Cloud Console. 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-east1
    • Nombre del repositorio: my-repo
    • ID del proyecto: my-project
    • Nombre de la imagen local: my-image
    • Nombre de imagen de destino: test-image

    El nombre de la imagen para este ejemplo es el siguiente:

    us-east1-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 mediante el siguiente comando:

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

    En el ejemplo anterior, SOURCE-IMAGE es el nombre de la imagen local o el ID de la imagen.

    Mediante este comando, se asigna a la imagen el nombre del repositorio y se aplica la etiqueta latest.

    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-east1-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-east1-docker.pkg.dev/my-project/my-repo/test-image:staging
    

Envía la imagen con etiqueta a Artifact Registry

  1. Asegúrate de haber autenticado 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 se encuentre 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 Cloud Console 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 truncadas, pero el comando siempre muestra el resumen completo de la imagen.

     IMAGE                                                 DIGEST         CREATE_TIME          UPDATE_TIME
      us-east1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:45  2019-04-10T15:08:45
      us-east1-docker.pkg.dev/my-project/my-repo/my-image  sha256:238...  2019-04-10T17:23:53  2019-04-10T17:23:53
      us-east1-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

  1. Asegúrate de haber autenticado 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 se encuentre 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 la ubicación regional o multirregional del repositorio en el que se almacena la imagen, por ejemplo, us-east1 o us.
    • PROJECT es el ID de tu proyecto de Google Cloud Console. 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 Google Cloud Console, 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-east1
    • 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-east1-docker.pkg.dev/my-project/my-repo/test-image:staging
    

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 nodos de Google Kubernetes Engine usan un entorno de ejecución containerd, puedes extraer imágenes de Artifact Registry mediante crictl.

Dado que crictl es una herramienta de solución de problemas, algunos comandos de Docker, como el envío o el etiquetado de imágenes, no están disponibles.

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

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

    Ir a Instancias de VM

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

  3. Obtén un token de acceso para autenticarte con el repositorio.

    curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" -H "Metadata-Flavor: Google"
  4. Extrae la imagen mediante 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?