En esta página, se describe cómo configurar Docker para autenticarte en los repositorios de Docker de Artifact Registry.
No es necesario que configures la autenticación para los entornos de ejecución de Cloud Build o Google Cloud, como Google Kubernetes Engine y Cloud Run, pero debes verificar que estén configurados los permisos necesarios.
Antes de comenzar
-
Instala Google Cloud CLI y, luego, inicializa la ejecución del siguiente comando:
gcloud init
- (Opcional) Configura los valores predeterminados para gcloud CLI de gcloud.
- Verifica que la cuenta que usas para la autenticación tenga permisos de acceso a Artifact Registry. Te recomendamos usar una cuenta de servicio en lugar de una cuenta de usuario.
- Instala Docker, si aún no se encuentra instalado. Docker está incluido en Cloud Shell.
Docker necesita acceso con privilegios para interactuar con los registros. En Linux o Windows, agrega el usuario que usas para ejecutar comandos de Docker al grupo de seguridad de Docker. Este paso no es necesario en macOS, ya que Docker Desktop se ejecuta en una máquina virtual como usuario raíz.
Linux
El grupo de seguridad de Docker se llama
docker
. Para agregar tu nombre de usuario, ejecuta el siguiente comando:sudo usermod -a -G docker ${USER}
Windows
El grupo de seguridad de Docker se llama
docker-users
. Para agregar un usuario desde el símbolo del sistema del administrador, ejecuta el siguiente comando:net localgroup docker-users DOMAIN\USERNAME /add
Donde
- DOMAIN es tu dominio de Windows.
- USERNAME es tu nombre de usuario.
Sal de tu cuenta y vuelve a acceder para que se apliquen los cambios de membresía de grupo. Si utilizas una máquina virtual, es posible que tengas que reiniciarla para que se apliquen los cambios de membresía.
Elige un método de autenticación
Los siguientes métodos de autenticación están disponibles:
- Auxiliar de credenciales de gcloud CLI
- Configura tus credenciales de Artifact Registry para usar con Docker directamente en gcloud CLI. Este es el método de autenticación más simple, pero puede ser más lento que el auxiliar de credenciales independiente.
- Auxiliar de credenciales de Docker independiente
- Esta opción sirve principalmente para configurar las credenciales a fin de usarlas con Docker cuando no se utilice Google Cloud CLI. Es mucho más rápido que el auxiliar de credenciales de gcloud CLI y usa las credenciales predeterminadas de la aplicación (ADC) para encontrar las credenciales en tu entorno de forma automática.
- Token de acceso
- Puedes generar un token de acceso de corta duración para una cuenta de servicio y, luego, usarlo en la autenticación con contraseña. Dado que el token solo es válido durante 60 minutos, es una opción más segura que la clave de una cuenta de servicio.
- Clave de cuenta de servicio
- Es un par de claves administrado por el usuario que puedes usar como credencial para una cuenta de servicio. Debido a que la credencial es de larga duración, es la opción menos segura de todos los métodos de autenticación disponibles.
Cuando sea posible, usa un token de acceso o un auxiliar de credenciales para reducir el riesgo de acceso no autorizado a las imágenes de tu contenedor. Si debes usar una clave de cuenta de servicio, asegúrate de seguir las recomendaciones para administrar credenciales.
Configuración de autenticación en el archivo de configuración de Docker
Docker guarda la configuración de autenticación en el archivo de configuración config.json.
- Linux:
~/.docker/config.json
- Windows:
%USERPROFILE%\.docker\config.json
En el archivo, hay secciones separadas para los distintos métodos de autenticación:
credHelpers
- Si usas el auxiliar de credenciales de Docker para la autenticación, Artifact Registry almacena la configuración del auxiliar de credenciales en la sección
credHelpers
del archivo. auths
- Si usas Docker para acceder con un token o una clave de cuenta de servicio como
contraseña, Docker almacena una versión de las credenciales codificada en base64 en la
sección
auths
del archivo. credStore
- Si configuraste un almacén de credenciales para administrarlas, los parámetros de configuración del almacén de credenciales estarán en la sección
credStore
del archivo.
Cuando Docker se conecta a un registro, primero busca un auxiliar de credenciales que esté asociado con el host. Por lo tanto, si tu config.json
incluye
la configuración de Artifact Registry en las secciones credHelpers
y auths
,
se ignora la configuración de la sección auths
.
Auxiliar de credenciales de gcloud CLI
El auxiliar de credenciales de gcloud CLI proporciona acceso seguro y de corta duración a los recursos de tu proyecto. Configura Docker para que se autentique en los hosts de Artifact Registry en cualquier entorno en el que esté instalado Google Cloud CLI. Cloud Shell incluye Google Cloud CLI y una versión actual de Docker.
El auxiliar de credenciales de gcloud CLI es el método de autenticación más simple de configurar. Configura Docker con las credenciales del usuario activo o de la cuenta de servicio en tu sesión de gcloud CLI. Dado que este auxiliar de credenciales depende de gcloud CLI, puede ser mucho más lento que el auxiliar de credenciales independiente. En el caso de compilaciones automáticas con herramientas de terceros o clientes de Docker con una gran cantidad de hosts de registro configurados, usa el auxiliar de credenciales independiente.
Para autenticarte en Artifact Registry, haz lo siguiente:
Accede a gcloud CLI como el usuario que ejecutará los comandos de Docker.
Para configurar la autenticación con credenciales de usuario, ejecuta el siguiente comando:
gcloud auth login
Para configurar la autenticación con credenciales de cuenta de servicio, ejecuta el siguiente comando:
gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
¿Por dónde
- ACCOUNT es la cuenta de servicio que quieres usar con Artifact Registry en el formato
USERNAME@PROJECT-ID.iam.gserviceaccount.com
. Si quieres usar una cuenta existente, puedes ver una lista de cuentas de servicio en la página Cuentas de servicio de Google Cloud Console o con el comandogcloud iam service-accounts list
. - KEY-FILE es el archivo de claves de la cuenta de servicio. Consulta la documentación de la administración de identidades y accesos (IAM) para obtener información sobre cómo crear una clave.
- ACCOUNT es la cuenta de servicio que quieres usar con Artifact Registry en el formato
Ejecuta el siguiente comando:
gcloud auth configure-docker HOSTNAME-LIST
En el ejemplo anterior, HOSTNAME-LIST es una lista separada por comas de nombres de host de repositorios que se agregará a la configuración del auxiliar de credenciales.
Por ejemplo, para agregar las regiones
us-central1
yasia-northeast1
, ejecuta el siguiente comando:gcloud auth configure-docker us-central1-docker.pkg.dev,asia-northeast1-docker.pkg.dev
Los nombres de host especificados se agregan a la configuración del auxiliar de credenciales. Puedes agregar otros nombres de host a la configuración más adelante si vuelves a ejecutar el comando.
Para ver una lista de las ubicaciones de los repositorios compatibles, ejecuta el siguiente comando:
gcloud artifacts locations list
El comando muestra la sección
credHelpers
de tu configuración de Docker actual y la configuración actualizada después de agregar los nombres de host especificados.Para aceptar los cambios de configuración, ingresa
y
.Las credenciales se guardan en el directorio de inicio del usuario.
- Linux:
$HOME/.docker/config.json
- Windows:
%USERPROFILE%/.docker/config.json
- Linux:
Docker requiere que los auxiliares de credenciales estén en el sistema
PATH
. Asegúrate de que el comando degcloud
esté en el sistemaPATH
.
Auxiliar de credenciales independiente
El auxiliar de credenciales de Docker independiente configura Docker para autenticar en Artifact Registry en un sistema en el que gcloud CLId no está disponible. Es mucho más rápido que el auxiliar de credenciales de gcloud CLI y usa las credenciales predeterminadas de la aplicación (ADC) para encontrar las credenciales en tu entorno de forma automática. Para operaciones que no sean enviar y extraer imágenes, como etiquetar o enumerar imágenes Recomendamos usar este método de autenticación para compilaciones automáticas con herramientas de terceros o clientes de Docker con una gran cantidad de hosts de registro configurados.
El auxiliar de credenciales de Docker independiente recupera las credenciales de Artifact Registry y las escribe en el archivo de configuración de Docker. De esta manera, puedes usar la herramienta de línea de comandos de Docker, docker
, para interactuar directamente con Artifact Registry.
Para usar el auxiliar de credenciales de Docker, sigue estos pasos:
Accede a la máquina como el usuario que ejecutará los comandos de Docker.
Descarga el auxiliar de credenciales de Docker independiente desde GitHub.
De manera opcional, puedes usar la utilidad de línea de comandos de
curl
. Por ejemplo:VERSION=2.1.22 OS=linux # or "darwin" for OSX, "windows" for Windows. ARCH=amd64 # or "386" for 32-bit OSs curl -fsSL "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz" \ | tar xz docker-credential-gcr \ && chmod +x docker-credential-gcr && sudo mv docker-credential-gcr /usr/bin/
Configura Docker para usar las credenciales de Container Registry cuando interactúes con este (solo es necesario que lo hagas una vez):
docker-credential-gcr configure-docker --registries=HOSTNAME-LIST
En el ejemplo anterior, HOSTNAME-LIST es una lista separada por comas de nombres de host de repositorios que se agregará a la configuración del auxiliar de credenciales.
Por ejemplo, para agregar las regiones
us-central1
yasia-northeast1
, ejecuta el siguiente comando:docker-credential-gcr configure-docker --registries=us-central1-docker.pkg.dev,asia-northeast1-docker.pkg.dev
Los nombres de host especificados se agregan a la configuración del auxiliar de credenciales. Puedes agregar otros nombres de host a la configuración más adelante si vuelves a ejecutar el comando.
Para ver una lista de las ubicaciones de los repositorios compatibles, ejecuta el siguiente comando:
gcloud artifacts locations list
Consulta la documentación del auxiliar de credenciales de Docker independiente en GitHub para obtener más información.
Las credenciales se guardan en el directorio de inicio del usuario.
- Linux:
$HOME/.docker/config.json
- Windows:
%USERPROFILE%/.docker/config.json
- Linux:
Docker requiere que los auxiliares de credenciales estén en el sistema
PATH
. Asegúrate de que el comando dedocker-credential-gcr
esté en el sistemaPATH
.Para verificar que el auxiliar de credenciales pueda recuperar tus credenciales con éxito, ejecuta el siguiente comando:
echo "https://HOSTNAME" | docker-credential-gcr get
Reemplaza HOSTNAME por un nombre de host que hayas agregado a la configuración. Por ejemplo:
echo "https://us-central1-docker.pkg.dev" | docker-credential-gcr get
Si el comando se ejecuta de forma correcta, el resultado JSON que se muestra incluirá un token en el campo
Secret
. Por ejemplo:{"ServerURL":"https://us-central1-docker.pkg.dev","Username":"_dcgcr_2_0_0_token","Secret":"ya29..."}
Docker ahora está configurado para autenticarse con Artifact Registry. Para enviar y extraer imágenes, asegúrate de que los permisos estén configurados de forma correcta.
Token de acceso
Puedes generar un token de acceso OAuth de corta duración para autenticarte con Artifact Registry. Dado que el token es válido durante 60 minutos, debes solicitarlo menos de una hora antes de usarlo para conectarte con Artifact Registry.
Para usar un token de acceso con credenciales de cuenta de servicio, haz lo siguiente:
Crea una cuenta de servicio para actuar en nombre de tu aplicación o elige una cuenta de servicio existente que uses en la automatización.
Otorga el rol de Artifact Registry específico a la cuenta de servicio para proporcionar acceso al repositorio.
Genera un token de acceso para la cuenta de servicio y autentica:
Debes tener los permisos en la función de creador de tokens de cuentas de servicio (
roles/iam.serviceAccountTokenCreator
) para suplantar la identidad de una cuenta de servicio, obtener un token y, luego, autenticarte como la cuenta de servicio.Ejecuta el siguiente comando y reemplaza ACCOUNT por la dirección de correo electrónico de tu cuenta de servicio y LOCATION la ubicación regional o multirregional del repositorio.
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 | docker login -u oauth2accesstoken --password-stdin https://LOCATION-docker.pkg.dev
Docker ahora está autenticado con Artifact Registry.
Clave de cuenta de servicio
Cualquier persona que tenga acceso a una clave privada válida para una cuenta de servicio podrá acceder a los recursos a través de la cuenta de servicio. Ten en cuenta que el ciclo de vida del acceso de la clave a la cuenta de servicio (y, por lo tanto, a los datos a los que tiene acceso la cuenta de servicio) es independiente del ciclo de vida del usuario que descargó la clave.
Usa los siguientes lineamientos para limitar el acceso a tus repositorios:
- Crea cuentas de servicio dedicadas que solo se usen para interactuar con repositorios.
- Otorga el rol de Artifact Registry específico para el acceso que requiere la cuenta de servicio. Por ejemplo, una cuenta de servicio que únicamente descarga artefactos solo requiere la función de lector de Artifact Registry.
- Configura los permisos para las cuentas de servicio dedicadas en cada repositorio, en lugar de hacerlo a nivel de proyecto. Luego, puedes especificar el acceso en función del contexto del repositorio. Por ejemplo, una cuenta de servicio para las compilaciones de desarrollo puede tener la función de lector de Artifact Registry en un repositorio de producción y la función de escritor de Artifact Registry en un repositorio de etapa de pruebas.
- Sigue las prácticas recomendadas para administrar credenciales.
A fin de crear una cuenta de servicio y una clave de cuenta de servicio nueva para usar solo con los repositorios de Artifact Registry, sigue estos pasos:
Crea una cuenta de servicio que actúe en nombre de tu aplicación o elige una cuenta de servicio existente que uses para la automatización.
Necesitarás la ubicación del archivo de claves de la cuenta de servicio para configurar la autenticación con Artifact Registry. En las cuentas existentes, puedes ver claves y crear claves nuevas en la página Cuentas de servicio.
De forma opcional, puedes codificar todo el contenido del archivo de claves en Base64.
Linux
base64 FILE-NAME > NEW-FILE-NAME
macOS
base64 -i FILE-NAME -o NEW-FILE-NAME
Windows
Base64.exe -e FILE-NAME > NEW-FILE-NAME
En el que FILE-NAME es el nombre de archivo de la clave original y NEW-FILE-NAME es el archivo de claves codificado en base64.
Verifica que los permisos estén configurados de forma correcta para la cuenta de servicio. Si usas la cuenta de servicio de Compute Engine, debes configurar de forma correcta los permisos y los permisos de acceso.
Usa la clave de la cuenta de servicio para configurar la integración con Docker:
Ejecuta el siguiente comando:
Linux/macOS
cat KEY-FILE | docker login -u KEY-TYPE --password-stdin \ https://LOCATION-docker.pkg.dev
Windows
Get-Content KEY-FILE | docker login -u KEY-TYPE --password-stdin https://LOCATION-docker.pkg.dev
Reemplaza lo siguiente:
- KEY-TYPE es uno de los siguientes:
_json_key
, si usas la clave de la cuenta de servicio en formato JSON, como se proporcionó cuando creaste el archivo._json_key_base64
, si codificas en Base64 todo el contenido del archivo.
- KEY-FILE es el nombre del archivo de claves de la cuenta de servicio en formato JSON.
- LOCATION es la ubicación regional o multirregional del repositorio en el que se almacena la imagen.
- KEY-TYPE es uno de los siguientes:
Docker ahora está autenticado con Artifact Registry.