En esta página, se describe el envío y la extracción de imágenes de contenedor con Docker. También se proporciona información sobre cómo extraer imágenes con la herramienta de crictl
si estás solucionando problemas en Google Kubernetes Engine.
Para obtener más 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
- Si el repositorio de destino no existe, crea un repositorio nuevo.
- Debes tener al menos el access de escritor de Artifact Registry al repositorio.
- Instala Docker si aún no lo has hecho.
Funciones obligatorias
A fin de obtener los permisos que necesitas para enviar y extraer imágenes, solicita a tu administrador que te otorgue los siguientes roles de IAM en el repositorio:
-
Extraer imágenes:
Lector de Artifact Registry (
roles/artifactregistry.reader
) -
Etiqueta y envía imágenes:
Escritor de Artifact Registry (
roles/artifactregistry.writer
)
Si quieres obtener más información para otorgar roles, consulta Administra el acceso.
Es posible que también puedas obtener los permisos necesarios a través de funciones personalizadas o, también, otras funciones predefinidas.
Autenticación 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 autenticarte de forma correcta. Si deseas obtener instrucciones detalladas, consulta Cómo configurar 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 hosts de Artifact Registry que usas deben estar en el 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 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 agregarlo. 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, 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 poco antes de etiquetar, enviar o extraer imágenes.
En el siguiente ejemplo, se genera un token de acceso mediante el suplantación de identidad de la cuenta de servicio y, luego, se autentica en Artifact Registry. Debes tener permisos en la función 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 permisos para actuar en nombre de una cuenta de servicio, puedes activarla en tu sesión de gcloud CLI y, luego, obtener un token. Si quieres obtener más detalles, consulta las instrucciones para configurar la autenticación de tokens de acceso.
Usa una clave de cuenta de servicio
Para una clave de cuenta de servicio, debes usarla como una 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
Si quieres obtener más detalles, consulta las instrucciones para configurar la autenticación con una clave de cuenta de servicio.
Envía una imagen
Modos de repositorio: Estándar
Para enviar una imagen local a un repositorio de Docker estándar, debes etiquetarla con el nombre del repositorio y, luego, enviarla.
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ías al repositorio. Para obtener más información sobre el resumen de imágenes, las etiquetas y la inmutabilidad de etiquetas, 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 excederá los 60 minutos, usa otro método de autenticación.
- 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 estar autenticado en el repositorio.
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 la región o multirregional ubicación del repositorio donde se almacena la imagen.
PROJECT-ID es el ID del 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
Para obtener detalles sobre el formato del nombre de la imagen,incluido el control 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 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 al repositorio si otra versión de la misma imagen ya usa la etiqueta en el repositorio. Para verificar si la configuración está habilitada 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 estar autenticado en el repositorio.
Si usaste
gcloud auth configure-docker
odocker-credential-gcr configure-docker
para configurar el cliente de Docker, verifica que el nombre de host de destino esté en el 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 de Google 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 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
Asegúrate de estar autenticado en el repositorio.
Si usaste
gcloud auth configure-docker
odocker-credential-gcr configure-docker
para configurar el cliente de Docker, verifica que el nombre de host de destino esté en el 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 región o multirregional ubicación del repositorio donde se almacena la imagen.
- PROJECT es el ID del 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 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 imágenes ú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, este la descarga y almacena en caché desde la fuente upstream si no existe una copia almacenada en caché.
Si solicitas una imagen de un repositorio virtual, Artifact Registry busca repositorios ascendentes para la imagen solicitada. Si solicitas una versión que está disponible en más de un repositorio upstream, Artifact Registry elige un repositorio upstream para usar según 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 en100
secondary-repo1
: Se estableció la prioridad en80
.secondary-repo2
: Se estableció la prioridad en80
.test-repo
: Se estableció la prioridad en20
.
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 una
imagen solicitada no está disponible en main-repo
, Artifact Registry
busca en estos repositorios a continuación. Como ambos tienen el mismo valor de prioridad,
Artifact Registry puede elegir 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 lo tiene.
Extrayendo 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 principalmente 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:
En la consola de Google Cloud, ve a la página Instancias de VM.
Establece una conexión SSH en el nodo del que estás solucionando problemas.
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 valoraccess_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?
- Obtén más información sobre cómo 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 repositorios privados de Artifact Registry - Más información para configurar
crictl
registros de imágenes