Configura la autenticación en Artifact Registry para Docker

En esta página, se describe cómo configurar Docker para que se autentique 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

  1. Instala Google Cloud CLI y, luego, inicializa la ejecución del siguiente comando: 

    gcloud init
  2. (Opcional) Establece los valores predeterminados para gcloud CLI de gcloud.
  3. Verifica que la cuenta que usas para la autenticación tenga permisos para acceder a Artifact Registry. Te recomendamos usar una cuenta de servicio en lugar de una cuenta de usuario.
  4. Instala Docker si aún no está instalado. Docker está incluido en Cloud Shell.

  5. 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 obligatorio 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 usarlas 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 se usa principalmente para configurar tus credenciales para usarlas con Docker en ausencia de Google Cloud CLI. Es mucho más rápido que el auxiliar de credenciales de gcloud CLI y usa credenciales predeterminadas de la aplicación (ADC) para encontrar 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 a fin de autenticar con contraseña. Dado que el token solo es válido por 60 minutos, es una opción más segura que una clave de 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 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

Hay secciones separadas en el archivo para diferentes 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 codificada en base64 de tus credenciales en la sección auths del archivo.
credStore
Si configuraste un almacén de credenciales para administrar tus credenciales, la configuración del almacén de credenciales se encuentra 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. Este configura Docker para que se autentique en los hosts de Artifact Registry en cualquier entorno en el que esté instalada 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 sencillo de configurar. Configura Docker con las credenciales del usuario activo o de la cuenta de servicio en tu sesión de gcloud CLI. Debido a que este auxiliar de credenciales depende de gcloud CLI, puede ser mucho más lento que el asistente de credenciales independiente. Para compilaciones automatizadas 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:

  1. Accede a gcloud CLI como el usuario que ejecutará los comandos de Docker.

  2. Ejecuta el siguiente comando:

    gcloud auth configure-docker HOSTNAME-LIST

    Donde HOSTNAME-LIST es una lista separada por comas de los nombres de host del repositorio para agregar a la configuración del auxiliar de credenciales.

    Por ejemplo, para agregar las regiones us-west1 y asia-northeast1, ejecuta el siguiente comando:

    gcloud auth configure-docker us-west1-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 ejecutando el comando de nuevo.

    Para ver una lista de las ubicaciones de los repositorios compatibles, ejecuta el siguiente comando:

    gcloud artifacts locations list

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

  4. Docker requiere que los auxiliares de credenciales estén en el sistema PATH. Asegúrate de que el comando de gcloud esté en el sistema PATH.

Auxiliar de credenciales independiente

El auxiliar de credenciales de Docker independiente configura Docker para autenticarse en Artifact Registry en un sistema en el que gcloud CLI no está disponible. Es significativamente más rápido que el Asistente de credenciales de gcloud CLI y usa las credenciales predeterminadas de la aplicación (ADC) para encontrar de forma automática las credenciales en tu entorno. 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 las 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:

  1. Accede a la máquina como el usuario que ejecutará los comandos de Docker.

  2. 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/

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

    Donde HOSTNAME-LIST es una lista separada por comas de los nombres de host del repositorio para agregar a la configuración del auxiliar de credenciales.

    Por ejemplo, para agregar las regiones us-west1 y asia-northeast1, ejecuta el siguiente comando:

    docker-credential-gcr configure-docker --registries=us-west1-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 ejecutando el comando de nuevo.

    Para ver una lista de las ubicaciones de los repositorios compatibles, ejecuta el siguiente comando:

    gcloud artifacts locations list

    Para obtener más información, consulta la documentación del auxiliar de credenciales de Docker independiente en GitHub.

    Las credenciales se guardan en el directorio de inicio del usuario.

    • Linux: $HOME/.docker/config.json
    • Windows: %USERPROFILE%/.docker/config.json

  4. Docker requiere que los auxiliares de credenciales estén en el sistema PATH. Asegúrate de que el comando de docker-credential-gcr esté en el sistema PATH.

  5. Para verificar que el auxiliar de credenciales pueda recuperar tus credenciales de forma correcta, 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-west1-docker.pkg.dev" | docker-credential-gcr get

    Si el comando se ejecuta de forma correcta, el resultado de JSON que se muestra incluye un token en el campo Secret. Por ejemplo:

    {"ServerURL":"https://us-west1-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 de OAuth de corta duración para autenticar con Artifact Registry. Dado que el token es válido por 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:

  1. Crea una cuenta de servicio para actuar en nombre de tu aplicación o elige una cuenta de servicio existente que uses para la automatización.

  2. Otorga el rol específico de Artifact Registry a la cuenta de servicio para proporcionar acceso al repositorio.

  3. 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 cuenta de servicio (roles/iam.serviceAccountTokenCreator) para suplantar la identidad de una cuenta de servicio, obtener un token para ella 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 la ubicación LOCATION regional o multirregional de 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 específico de Artifact Registry 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:

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

    Ir a la página Cuentas de servicio

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

    Donde FILE-NAME es el nombre del archivo de claves original y NEW-FILE-NAME es el archivo de claves codificado en base64.

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

  4. 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 una de las siguientes opciones:
      • _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 región o multirregional ubicación del repositorio donde se almacena la imagen.

Docker ahora está autenticado con Artifact Registry.