Configura la autenticación en Artifact Registry para Docker

En esta página, se describe cómo configurar Docker para autenticarse en los repositorios de Docker de Artifact Registry.

No es necesario que configures la autenticación para Cloud Build ni para los entornos de ejecución de Google Cloud, como Google Kubernetes Engine y Cloud Run, pero debes verificar que los permisos requeridos estén configurados.

Antes de comenzar

  1. Install the Google Cloud CLI, then initialize it by running the following command: 

    gcloud init
  2. (Opcional) Configura valores predeterminados para los comandos de gcloud CLI.
  3. Verifica que la cuenta que usas para la autenticación tenga permiso para acceder a Artifact Registry. Te recomendamos usar una cuenta de servicio en lugar de una 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

    Aquí:

    • 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 la CLI de gcloud
Configura tus credenciales de Artifact Registry para usarlas con Docker directamente en gcloud CLI. Este es el método de autenticación más sencillo, pero puede ser más lento que el auxiliar de credenciales independiente.
Auxiliar de credenciales de Docker independiente
Esta opción es principalmente para configurar tus credenciales y usarlas con Docker si Google Cloud CLI no existe. Es mucho más rápido que el ayudante de credenciales de gcloud CLI y usa credenciales predeterminadas de la aplicación (ADC) para encontrar credenciales automáticamente en tu entorno.
Token de acceso
Puedes generar un token de acceso de corta duración para una cuenta de servicio y, luego, usarlo para la autenticación de contraseña. Dado que el token solo es válido durante 60 minutos, es una opción más segura que una clave de cuenta de servicio.
Clave de cuenta de servicio
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 tus 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

En el archivo, hay secciones separadas para los 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 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é 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 la cuenta de servicio en tu sesión de gcloud CLI. Como este auxiliar de credenciales depende de gcloud CLI, puede ser mucho más lento que el auxiliar 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

    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-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. Para agregar más adelante otros nombres de host a la configuración, ejecuta de nuevo 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 actual de Docker 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 realizar la autenticación en Artifact Registry en un sistema en el que gcloud CLI no está disponible. Es mucho más rápido que el ayudante de credenciales de la CLI de gcloud y usa las credenciales predeterminadas de la aplicación (ADC) para encontrar credenciales automáticamente en tu entorno. Para operaciones que no sean de envío ni recuperación de imágenes, como etiquetarlas o generar listas de ellas. Te recomendamos que uses este método de autenticación para compilaciones automatizadas 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.25
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-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. Para agregar más adelante otros nombres de host a la configuración, ejecuta de nuevo 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 correctamente tus credenciales, 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 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 autenticarte con Artifact Registry. Dado que el token es válido por 60 minutos, debes solicitarlo menos de una hora antes de usarlo para conectarte a Artifact Registry.

Para usar un token de acceso con credenciales de cuenta de servicio, haz lo siguiente:

  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.

  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 realiza la autenticación:

    Debes tener los permisos del rol de creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) para actuar en nombre 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 LOCATION por 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 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

    En el ejemplo anterior, 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 ubicación regional o multirregional del repositorio en la que se almacena la imagen.

Docker ahora está autenticado con Artifact Registry.