Configura la autenticación en Artifact Registry para Docker

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

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

    gcloud init
  2. (Opcional) Configura los valores predeterminados para gcloud CLI de gcloud.
  3. 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.
  4. Instala Docker, si aún no se encuentra 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 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:

  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

    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 y asia-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

  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 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:

  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

    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 y asia-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

  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 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:

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

  2. Otorga el rol de Artifact Registry específico 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 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:

  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

    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.

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

Docker ahora está autenticado con Artifact Registry.