Configura la autenticación en Artifact Registry para Docker

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

No es necesario que configures la autenticación para Cloud Build o Google Cloud entornos de ejecución como Google Kubernetes Engine y Cloud Run, pero debería verifica que los permisos necesarios de configuración.

Antes de comenzar

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

    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 que 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
Configurar 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 lenta 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 gcloud CLI. auxiliar de credenciales y usa las credenciales predeterminadas de la aplicación (ADC) para buscar credenciales en tu entorno.
Token de acceso
Puedes generar un token de acceso de corta duración para una cuenta de servicio y, luego, usar el token para la autenticación con contraseña. Como el token solo es válido para 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 administradas por el usuario que puedes usar como credencial para un 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 tu 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 sus 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 está en la sección credStore del archivo.

Cuando Docker se conecta a un registro, primero busca un auxiliar de credenciales. asociada con el host. Por lo tanto, si tu config.json incluye Configuración de Artifact Registry en las secciones credHelpers y auths. se ignorará 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 tus los recursos del proyecto. Este configura Docker para que se autentique en Hosts de Artifact Registry en cualquier entorno en el que Google Cloud CLI esté instalada 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. 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 o clientes de Docker con una gran cantidad de registros 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 de repositorios separada por comas nombres de host 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 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 Docker actual. actual y la actualizada después de agregar los atributos y los nombres de host.

    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. a 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 credenciales predeterminadas de la aplicación (ADC) para encontrar credenciales en tu entorno. Para operaciones que no sean enviar y extrayendo imágenes, como etiquetarlas o mostrarlas en una lista. Recomendamos usar método de autenticación para compilaciones automatizadas con herramientas de terceros o Docker cliente 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.23
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 de repositorios separada por comas nombres de host 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 de nuevo.

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

    gcloud artifacts locations list

    Consulta la documentación independiente del auxiliar de credenciales de Docker 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 tu las credenciales, ejecuta el siguiente comando:

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

    Reemplaza HOSTNAME por un nombre de host que hayas agregado al configuración. Por ejemplo:

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

    Si el comando tiene éxito, el resultado JSON devuelto 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 correctamente.

Token de acceso

Puedes generar un token de acceso OAuth de corta duración para autenticarte Artifact Registry. Dado que el token es válido por 60 minutos, deberías 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. Crear una cuenta de servicio para realizar acciones en nombre de tu aplicación o elige una existente para la automatización.

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

  3. Genera un token de acceso para la cuenta de servicio y autentica:

    • Debes tener los permisos en el rol Creador de tokens de cuentas de servicio (roles/iam.serviceAccountTokenCreator) a suplantar la identidad de una cuenta de servicio para obtener un token y, luego, autenticarse como la cuenta de servicio.

      Ejecuta el siguiente comando y reemplaza ACCOUNT por dirección de correo electrónico de la cuenta de servicio y LOCATION regional o multirregional ubicación 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 la función Rol de Artifact Registry para el acceso requerido por 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 el regional o multirregional location del repositorio en el que se almacena la imagen.

Docker ahora está autenticado con Artifact Registry.