Artifact Registry es un servicio universal de administración de paquetes que admite contenedores y otros formatos. Obtén información sobre cómo realizar la transición desde Container Registry para obtener más flexibilidad y control sobre los artefactos.

Métodos de autenticación

En esta página, se describe cómo configurar un cliente de terceros para autenticarse con Container Registry.

Los servicios de Google Cloud que se integran con Container Registry están preconfigurados con permisos para acceder a los repositorios en el mismo proyecto. No necesitas configurar la autenticación para estos servicios, pero debes verificar que los permisos estén configurados de forma adecuada.

Antes de comenzar

  1. La cuenta que usarás para la autenticación debe tener permisos a fin de acceder al registro. Te recomendamos usar una cuenta de servicio en lugar de una de usuario. Las cuentas de servicio no están asociadas con un usuario específico, y las aplicaciones de Google Cloud pueden usar la estrategia Credenciales predeterminadas de la aplicación para obtener las credenciales de forma automática.

  2. Instala la versión más reciente del SDK de Cloud. Para actualizar una instalación existente, ejecuta el comando de gcloud components update.

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

  4. Instala Docker si aún no lo hiciste.

  5. Docker necesita acceso con privilegios para interactuar con los registros. Si Docker está instalado en Linux o Windows, agrega el usuario que usas para ejecutar los comandos de Docker al grupo de seguridad de este.

    En MacOS, Docker se ejecuta desde una máquina virtual con el usuario raíz, por lo que este paso no es obligatorio. Para obtener detalles sobre Docker en MacOS, consulta la documentación de Docker.

    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.

Métodos de autenticación

Debes configurar cualquier cliente de terceros que deba acceder a Container Registry.

Los siguientes métodos de autenticación están disponibles:

gcloud como auxiliar de credenciales (recomendado)
Configura tus credenciales de Container Registry para usarlas con Docker directamente en gcloud. Usa este método cuando sea posible para un acceso seguro y de corta duración a los recursos de tu proyecto. Esta opción solo es compatible a partir de la versión 18.03 de Docker.
Auxiliar de credenciales de Docker independiente
Esta opción es principalmente para configurar tus credenciales y usarlas con Docker si el SDK de Cloud no existe. Esta opción solo es compatible a partir de la versión 18.03 de Docker.
Token de acceso
Las credenciales predeterminadas de la aplicación proporcionan tokens de acceso de corta duración que una cuenta de servicio usa para acceder a tus recursos de Google Cloud. Es la alternativa más segura para usar gcloud como auxiliar de credenciales.
Archivo de claves JSON

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 cualquier otro método de autenticación disponible para reducir el riesgo de acceso no autorizado a tus artefactos. Si debes usar una clave de cuenta de servicio, asegúrate de seguir las recomendaciones para administrar credenciales.

Algunas herramientas o flujos de trabajo no proporcionan una buena asistencia para usar gcloud como auxiliar de credenciales. Si usas una de las opciones alternativas, asegúrate de comprender las implicaciones de seguridad.

Auxiliares de credenciales

Los auxiliares de credenciales de Docker lo configuran para la autenticación con un registro específico. Container Registry proporciona lo que se describe a continuación:

  • Un asistente de credenciales de gcloud
  • Un auxiliar de credenciales independiente para sistemas en los que el SDK de Cloud no está disponible

gcloud como auxiliar de credenciales de Docker

Te recomendamos que utilices este método cuando sea posible. Proporciona acceso seguro y de corta duración a los recursos de tu proyecto.

Usa gcloud para configurar la autenticación en Cloud Shell o en cualquier entorno en el que esté instalado el SDK de Cloud. Cloud Shell incluye una versión actual de Docker.

Para configurar la autenticación, sigue estos pasos:

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

    • Para configurar la autenticación con credenciales de usuario, ejecuta el siguiente comando:

      gcloud auth login

    • Para configurar la autenticación con credenciales de cuenta de servicio, ejecuta el siguiente comando:

      gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE

      Donde

      • ACCOUNT es el nombre de la cuenta de servicio en el formato [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com. Puedes ver las cuentas de servicio existentes en la página Cuentas de servicio de Cloud Console o con el comando de gcloud iam service-accounts list.
      • KEY-FILE es el archivo de claves de la cuenta de servicio. Consulta la documentación de la administración de identidades y accesos (IAM) para obtener información sobre cómo crear una clave.

  2. Configura Docker con el siguiente comando:

    gcloud auth configure-docker

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

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

Docker ahora está configurado para autenticarse con Container Registry. Para enviar y extraer imágenes, asegúrate de que los permisos estén configurados de forma correcta.

Auxiliar de credenciales de Docker independiente

El auxiliar de credenciales de Docker independiente configura Docker para autenticar en Container Registry en un sistema en el que el SDK de Cloud no está disponible.

El auxiliar de credenciales recupera tus credenciales de Container Registry, ya sea automáticamente o desde una ubicación especificada mediante la marca --token-source. Luego, 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 Container Registry.

Para configurar la autenticación, sigue estos pasos:

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

  2. Descarga docker-credential-gcr de las versiones de GitHub:

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

    VERSION=2.0.0
OS=linux  # or "darwin" for OSX, "windows" for Windows.
ARCH=amd64  # or "386" for 32-bit OSs, "arm64" for ARM 64.

curl -fsSL "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz" \
| tar xz --to-stdout ./docker-credential-gcr \
> /usr/local/bin/docker-credential-gcr && chmod +x /usr/local/bin/docker-credential-gcr

  3. Configura Docker con el siguiente comando:

    docker-credential-gcr configure-docker

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

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

Consulta la documentación del auxiliar de credenciales de Docker independiente en GitHub para obtener más información.

Docker ahora está configurado para autenticarse con Container Registry. Para enviar y extraer imágenes, asegúrate de que los permisos estén configurados de forma correcta.

Token de acceso

Un token de acceso es una credencial de corta duración que proporciona acceso a tus recursos de Google Cloud. Puedes usar un token de acceso como contraseña para conectarte a Container Registry.

Google Cloud obtiene un token de acceso con las credenciales predeterminadas de la aplicación.

  1. Obtén la clave para la cuenta de servicio que interactuará con Container Registry.

    Console

    1. En Google Cloud Console, abrirá la página Crea clave de cuenta de servicio.

      Ir a la página Crear clave de la cuenta de servicio

    2. En la lista de cuentas de servicio, selecciona la cuenta de servicio que deseas usar.

      Para crear una nueva cuenta de servicio, selecciona Nueva cuenta de servicio y especifica el nombre de servicio, ID y la función de Container Registry adecuada según los permisos que deseas otorgar a la cuenta de servicio.

    3. Seleccione JSON como tipo de clave.

    4. Haga clic en Crear. Se descargará a tu computadora un archivo JSON con la clave.

      En las instrucciones de esta página, se usa el nombre de archivo keyfile.json para este archivo de claves.

    gcloud

    Puedes ejecutar los siguientes comandos con el SDK de Cloud en tu máquina local o en Cloud Shell.

    1. Crea la cuenta de servicio. Reemplaza NAME por un nombre para la cuenta de servicio.

      gcloud iam service-accounts create NAME

    2. Otorga permisos a la cuenta de servicio. Reemplaza PROJECT_ID con tu ID del proyecto y ROLE con la función de Container Registry adecuada para la cuenta de servicio. Esta función se aplica a todos los repositorios del proyecto. Puedes cambiar la función más adelante y también puedes establecer permisos diferentes para la cuenta de servicio en repositorios específicos.

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"

    3. Genera el archivo de claves. En las instrucciones de esta página, se usa el nombre de archivo keyfile.json para el archivo de claves.

      gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com

  2. Ejecuta el siguiente comando para acceder al SDK de Cloud como una cuenta de servicio.

    gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE

    Donde

    • ACCOUNT es el nombre de la cuenta de servicio en el formato [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com.
    • KEY-FILE es el archivo de claves de la cuenta de servicio. Consulta la documentación de IAM para obtener información sobre la creación de una clave.

  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. Obtén un token de acceso para la cuenta de servicio. Dado que el token es de corta duración, solicítalo menos de una hora antes de usarlo para conectarte a Container Registry.

    Linux/macOS

    • El nombre de usuario es oauth2accesstoken.
    • La contraseña es tu token de acceso. Por ejemplo, gcloud auth print-access-token

    Por ejemplo:

    gcloud auth print-access-token | docker login -u oauth2accesstoken --password-stdin https://[HOSTNAME]

    donde [HOSTNAME] es gcr.io, us.gcr.io, eu.gcr.io o asia.gcr.io.

    O bien, para clientes de Docker más antiguos que no son compatibles con --password-stdin:

    docker login -u oauth2accesstoken -p "$(gcloud auth print-access-token)" https://[HOSTNAME]

    Windows

    • El nombre de usuario es oauth2accesstoken.
    • La contraseña es el resultado de gcloud auth print-access-token.
    1. Obtén el token de acceso
    gcloud auth print-access-token

    La string que se muestra es el token de acceso que usas como contraseña. En este ejemplo, ya29.8QEQIfY_... representa el token de acceso que se muestra.

    ya29.8QEQIfY_...
    1. Accede con el token de acceso
    docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." https://[HOSTNAME]

    donde [HOSTNAME] es gcr.io, us.gcr.io, eu.gcr.io o asia.gcr.io.

Docker ahora está autenticado con Container Registry.

Archivo de claves JSON

Una clave de cuenta de servicio es un par de claves de larga duración que puedes usar como credencial para una cuenta de servicio. Eres responsable de la seguridad de la clave privada y otras operaciones de administración, como la rotación de claves.

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. Por ejemplo, a algunas cuentas de servicio creadas automáticamente por Google Cloud, como la cuenta de servicio de Container Registry, se les otorga la función de lectura y escritura Editor para el proyecto principal. La cuenta de servicio predeterminada de Compute Engine está configurada con acceso de solo lectura al almacenamiento dentro del mismo proyecto.

Además, 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 las siguientes pautas para limitar el acceso a tus imágenes de contenedor:

A fin de crear una cuenta de servicio y una clave de cuenta de servicio nueva para usar solo con los repositorios de Container Registry, sigue estos pasos:

  1. Crea la cuenta de servicio para interactuar con los repositorios:

    Console

    1. En Google Cloud Console, abrirá la página Crea clave de cuenta de servicio.

      Ir a la página Crear clave de la cuenta de servicio

    2. En la lista Cuenta de servicio, selecciona Cuenta de servicio nueva.

    3. Ingresa un nombre en el campo Nombre de cuenta de servicio.

    4. En la lista función, seleccione la función de Container Registry correspondiente a la cuenta de servicio.

    5. Haga clic en Crear. Se descargará a tu computadora un archivo JSON con la clave.

      En las instrucciones de esta página, se usa el nombre de archivo keyfile.json para este archivo de claves.

    gcloud

    Puedes ejecutar los siguientes comandos con el SDK de Cloud en tu máquina local o en Cloud Shell.

    1. Crea la cuenta de servicio. Reemplaza NAME por un nombre para la cuenta de servicio.

      gcloud iam service-accounts create NAME

    2. Otorga permisos a la cuenta de servicio. Reemplaza PROJECT_ID con tu ID del proyecto y ROLE con la función adecuada para la cuenta de servicio.

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"

    3. Genera el archivo de claves. En este ejemplo, el nombre del archivo de claves de salida es keyfile.json.

      gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com

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

  3. Usa la clave de la cuenta de servicio como contraseña a fin de autenticarte con Docker.

    Linux/macOS

    • El nombre de usuario es _json_key (NO el nombre de la cuenta de servicio).
    • keyfile.json es la clave de la cuenta de servicio que creaste.

    Por ejemplo:

    cat keyfile.json | docker login -u _json_key --password-stdin https://[HOSTNAME]

    donde [HOSTNAME] es gcr.io, us.gcr.io, eu.gcr.io o asia.gcr.io.

    O bien, para clientes de Docker más antiguos que no son compatibles con --password-stdin:

    docker login -u _json_key -p "$(cat keyfile.json)" https://[HOSTNAME]

    donde [HOSTNAME] es gcr.io, us.gcr.io, eu.gcr.io o asia.gcr.io.

    Windows

    • El nombre de usuario es _json_key (NO el nombre de la cuenta de servicio).
    • keyfile.json contiene la clave JSON de la cuenta de servicio.

    Por ejemplo:

    docker login -u _json_key --password-stdin https://[HOSTNAME] < keyfile.json

    donde [HOSTNAME] es gcr.io, us.gcr.io, eu.gcr.io o asia.gcr.io.

    O bien, para clientes de Docker más antiguos que no son compatibles con --password-stdin:

    set /p PASS=<keyfile.json
docker login -u _json_key -p "%PASS%" https://[HOSTNAME]

    donde [HOSTNAME] es gcr.io, us.gcr.io, eu.gcr.io o asia.gcr.io.

Docker ahora está autenticado con Container Registry.