Configurar 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 Cloud Build ni para los entornos de ejecución, como Google Kubernetes Engine y Cloud Run, pero debes verificar que los permisos necesarios estén configurados. Google Cloud

Antes de empezar

  1. Instala Google Cloud CLI. Después de la instalación, inicializa la CLI de Google Cloud ejecutando el siguiente comando: 

    gcloud init

    Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  2. (Opcional) Configura los valores predeterminados de 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 que utilices una cuenta de servicio en lugar de una cuenta de usuario.
  4. Instala Docker si aún no lo has hecho. Docker está incluido en Cloud Shell.
  5. Docker requiere acceso con privilegios para interactuar con los registros. En Linux o Windows, añade el usuario que utilizas 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 añadir 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 añadir un usuario desde la petición de comando 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.

    Cierra sesión y vuelve a iniciarla para que se apliquen los cambios en la pertenencia a grupos. Si usas una máquina virtual, es posible que tengas que reiniciarla para que los cambios en la suscripción surtan efecto.

Elegir un método de autenticación

Están disponibles los siguientes métodos de autenticación:

Asistente 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 sencillo, pero puede ser más lento que el auxiliar de credenciales independiente.
Asistente de credenciales de Docker independiente
Esta opción se usa principalmente para configurar tus credenciales para usarlas con Docker si no tienes la CLI de Google Cloud. Es significativamente más rápido que el asistente de credenciales de la CLI de gcloud y usa las credenciales predeterminadas de la aplicación (ADC) para encontrar automáticamente las credenciales de tu entorno.
Token de acceso
Puedes generar un token de acceso de corta duración para una cuenta de servicio y, a continuación, usarlo para la autenticación con contraseña. Como 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 gestionado por el usuario que puedes usar como credencial de una cuenta de servicio. Como la credencial tiene una larga duración, es la opción menos segura de todos los métodos de autenticación disponibles.

Si es posible, utiliza un token de acceso o un asistente de credenciales para reducir el riesgo de que se acceda sin autorización a tus imágenes de contenedor. Si debes usar una clave de cuenta de servicio, asegúrate de seguir las prácticas recomendadas para gestionar las 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

El archivo tiene secciones independientes para los distintos métodos de autenticación:

credHelpers
Si usas el asistente de credenciales de Docker para la autenticación, Artifact Registry almacena los ajustes del asistente de credenciales en la sección credHelpers del archivo.
auths
Si usas Docker para iniciar sesión 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 has configurado un almacén de credenciales para gestionar tus credenciales, los ajustes del almacén de credenciales se encuentran en la sección credStore del archivo.

Cuando Docker se conecta a un registro, primero busca un asistente de credenciales asociado al host. Por lo tanto, si tu config.json incluye ajustes de Artifact Registry en las secciones credHelpers y auths, se ignorarán los ajustes de la sección auths.

Asistente de credenciales de la CLI de gcloud

El asistente de credenciales de la CLI de gcloud proporciona acceso seguro y de corta duración a los recursos de tu proyecto. Configura Docker para autenticarse en 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 asistente de credenciales de la CLI de gcloud es el método de autenticación más sencillo de configurar. Configura Docker con las credenciales de la cuenta de usuario o de servicio activa en tu sesión de la CLI de gcloud. Como este asistente de credenciales depende de la CLI de gcloud, puede ser significativamente más lento que el asistente de credenciales independiente. Si quieres automatizar las compilaciones con herramientas de terceros o clientes de Docker con un gran número de hosts de registro configurados, usa el auxiliar de credenciales independiente.

Para autenticarte en Artifact Registry, sigue estos pasos:

  1. Inicia sesión en gcloud CLI como el usuario que ejecutará los comandos de Docker.

  1. Ejecuta el siguiente comando:

    gcloud auth configure-docker HOSTNAME-LIST

    Donde HOSTNAME-LIST es una lista separada por comas de nombres de host de repositorios que se van a añadir a la configuración del asistente de credenciales.

    Por ejemplo, para añadir 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 añaden a la configuración del asistente de credenciales. Puedes añadir otros nombres de host a la configuración más adelante volviendo a ejecutar el comando.

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

    gcloud artifacts locations list

  2. El comando muestra la sección credHelpers de tu configuración actual de Docker y la configuración actualizada después de añadir los nombres de host especificados.

    Para aceptar los cambios de configuración, introduce y.

    Tus credenciales se guardan en el directorio principal de tu usuario.

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

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

Asistente de credenciales independiente

El asistente de credenciales de Docker independiente configura Docker para autenticarse en Artifact Registry en un sistema en el que la CLI de gcloud no está disponible. Es mucho más rápido que el asistente de credenciales de la CLI de gcloud y usa las credenciales predeterminadas de la aplicación (ADC) para encontrar automáticamente las credenciales en tu entorno. Para operaciones distintas a la inserción y extracción de imágenes, como etiquetar o enumerar imágenes. Recomendamos usar este método de autenticación para compilaciones automatizadas con herramientas de terceros o clientes de Docker con un gran número de hosts de registro configurados.

El asistente de credenciales de Docker independiente obtiene tus credenciales de Artifact Registry y las escribe en el archivo de configuración de Docker. De esta forma, 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. Inicia sesión en el equipo con la cuenta del usuario que ejecutará los comandos de Docker.

  2. Descarga el asistente de credenciales de Docker independiente desde GitHub.

    También puedes usar la utilidad de línea de comandos curl. Por ejemplo:

    VERSION=2.1.29
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 que use tus credenciales de Artifact Registry cuando interactúes con Artifact Registry (solo tienes que hacerlo una vez):

    docker-credential-gcr configure-docker --registries=HOSTNAME-LIST

    Donde HOSTNAME-LIST es una lista separada por comas de nombres de host de repositorios que se van a añadir a la configuración del asistente de credenciales.

    Por ejemplo, para añadir 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 añaden a la configuración del asistente de credenciales. Puedes añadir otros nombres de host a la configuración más adelante volviendo a ejecutar el comando.

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

    gcloud artifacts locations list

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

    Tus credenciales se guardan en el directorio principal de tu usuario.

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

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

  5. Para verificar que el asistente de credenciales puede recuperar tus credenciales correctamente, ejecuta el siguiente comando:

    echo "https://HOSTNAME" | docker-credential-gcr get

    Sustituye HOSTNAME por un nombre de host que hayas añadido a la configuración. Por ejemplo:

    echo "https://us-west1-docker.pkg.dev" | docker-credential-gcr get

    Si el comando se ejecuta correctamente, la salida JSON devuelta 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 ya está configurado para autenticarse con Artifact Registry. Para enviar y descargar imágenes, asegúrate de que los permisos estén configurados correctamente.

Token de acceso

Puedes generar un token de acceso de OAuth de corta duración para autenticarte con Artifact Registry. Como el token es válido durante 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, sigue estos pasos:

  1. Crea una cuenta de servicio para que actúe en nombre de tu aplicación o elige una cuenta de servicio que ya uses para la automatización.

  2. Concede 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 autentícalo:

    Debes tener los permisos del rol 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, a continuación, autenticarte como la cuenta de servicio.

    Ejecuta el siguiente comando y sustituye ACCOUNT por tu dirección de correo de la 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

Ahora Docker está autenticado con Artifact Registry.

Clave de cuenta de servicio

Cualquier persona que tenga acceso a una clave privada válida de una cuenta de servicio podrá acceder a los recursos a través de esa cuenta. 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 ha descargado la clave.

Sigue estas directrices para limitar el acceso a tus repositorios:

  • Crea cuentas de servicio específicas que solo se usen para interactuar con repositorios.
  • Asigna el rol de Artifact Registry específico para el acceso que necesita la cuenta de servicio. Por ejemplo, una cuenta de servicio que solo descarga artefactos solo requiere el rol Lector de Artifact Registry.
  • Configure los permisos de sus cuentas de servicio dedicadas en cada repositorio en lugar de hacerlo a nivel de proyecto. A continuación, puedes especificar el acceso en función del contexto del repositorio. Por ejemplo, una cuenta de servicio para compilaciones de desarrollo puede tener el rol Lector de Artifact Registry para un repositorio de producción y el rol Escritor de Artifact Registry para un repositorio de staging.
  • Sigue las prácticas recomendadas para gestionar las credenciales.

Para crear una cuenta de servicio y una clave de cuenta de servicio que solo se puedan usar con repositorios de Artifact Registry, sigue estos pasos:

  1. Crea una cuenta de servicio para que actúe en nombre de tu aplicación o elige una que ya tengas y que uses para la automatización.

    Necesitarás la ubicación del archivo de clave de cuenta de servicio para configurar la autenticación con Artifact Registry. En el caso de las cuentas que ya tengas, puedes ver las claves y crear otras en la página Cuentas de servicio.

    Ir a la página Cuentas de servicio

  2. También puedes codificar en Base64 todo el contenido del archivo de claves.

    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 clave original y NEW-FILE-NAME es el archivo de clave codificado en Base64.

  3. Verifica que los permisos estén configurados correctamente para la cuenta de servicio. Si utilizas la cuenta de servicio de Compute Engine, debes configurar correctamente tanto los permisos como los ámbitos de acceso.

  4. Usa la clave de la cuenta de servicio para configurar la integración con Docker:

    Ejecuta el siguiente comando:

    Linux o 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

    Haz los cambios siguientes:

    • KEY-TYPE es uno de los siguientes:
      • _json_key si utilizas la clave de la cuenta de servicio en formato JSON, tal como se proporcionó al crear el archivo.
      • _json_key_base64 si has codificado en Base64 todo el contenido del archivo.
    • KEY-FILE es el nombre del archivo de clave de cuenta de servicio en formato JSON.
    • LOCATION es la ubicación regional o multirregional del repositorio donde se almacena la imagen.

Ahora Docker está autenticado con Artifact Registry.