Artifact Registry es el servicio recomendado para administrar imágenes de contenedor. Container Registry sigue siendo compatible, pero solo recibirá correcciones de seguridad críticas. Obtén más información sobre la transición a Artifact Registry.

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. Verifica que hayas habilitado la API de Container Registry e instalado la CLI de gcloud. Consulta la página Inhabilita y habilita servicios para obtener instrucciones.

  2. Verifica que la cuenta que usas para la autenticación tenga permisos a fin de acceder a Container Registry. Te recomendamos usar una cuenta de servicio en lugar de una de usuario.

  3. Instala Docker, si aún no se encuentra instalado. Docker está incluido en Cloud Shell.

  4. 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 Mac OS, 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.

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:

Auxiliar de credenciales de gcloud (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 independiente
Esta opción es principalmente para configurar tus credenciales a fin de usarlas con Docker si no se usa la CLI de Google Cloud. 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.

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

Existen diferentes secciones en el archivo para los distintos métodos de autenticación:

credHelpers
Si usas el auxiliar de credenciales de Docker para la autenticación, Container Registry almacena su configuración 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 tus credenciales codificada en base64 en la sección auths del archivo.
credStore
Si configuraste un almacén de credenciales para administrar tus credenciales, la configuración de dicho almacén se encuentra en la sección credStore del archivo.

Cuando Docker se conecta a un registro, primero busca un asistente de credenciales asociado con el host. Por lo tanto, si tu config.json incluye la configuración de Container Registry en las secciones credHelpers y auths, se ignora la configuración de la sección auths.

Auxiliar de credenciales de gcloud

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 la CLI de gcloud para configurar la autenticación en Cloud Shell o en cualquier entorno en el que esté instalada la CLI de Google 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 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

Auxiliar de credenciales independiente

El asistente de credenciales independiente de Docker configura Docker para autenticarse en Container Registry en un sistema en el que la CLI de gcloud 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

Puedes generar un token de acceso OAuth de corta duración para autenticar con Container Registry. Dado que el token es válido durante 60 minutos, debes solicitarlo menos de una hora antes de usarlo para conectarte con Container Registry.

  1. Cree una cuenta de servicio nueva que interactuará con Container Registry.

    Console

    1. En Google Cloud Console, ve a la página Crear cuenta de servicio.

      Ve a la página Crear cuenta de servicio

    2. Selecciona el proyecto que deseas usar.

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

    4. Opcional: en el campo Descripción de la cuenta de servicio, ingresa una descripción.

    5. Haga clic en Crear.

    6. Haz clic en el campo Seleccionar una función. En Todas las funciones, selecciona una función de Cloud Storage adecuada en función de los permisos que deseas otorgar a la cuenta de servicio.

    7. Haga clic en Listo.

    gcloud

    Puedes ejecutar los siguientes comandos con la CLI de Google Cloud en tu máquina local o en Cloud Shell.

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

      gcloud iam service-accounts create NAME

    2. Otorga una función a la cuenta de servicio. Reemplaza PROJECT_ID por el ID del proyecto y ROLE por la función de Cloud Storage 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 otorgar diferentes funciones a 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"

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

    Console

    1. En Cloud Console, ve a la página Cuentas de servicio.

      Ir a la página Cuentas de servicio

    2. Haz clic en la dirección de correo electrónico de la cuenta de servicio que deseas usar.

    3. Haga clic en Claves.

    4. Haz clic en Agregar clave -> Crear nueva clave.

    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.

    6. Haga clic en Cerrar.

    gcloud

    Puedes ejecutar el siguiente comando con la CLI de Google Cloud en tu máquina local o en Cloud Shell.

    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

  3. Ejecuta el siguiente comando para acceder a la CLI de Google 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.

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

  5. 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. A diferencia del token de acceso de OAuth, una clave de cuenta de servicio no vence. Eres responsable de la seguridad de la clave privada y otras operaciones de administración de claves, 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. Cree una cuenta de servicio nueva que interactuará con Container Registry.

    Console

    1. En Google Cloud Console, ve a la página Crear cuenta de servicio.

      Ve a la página Crear cuenta de servicio

    2. Selecciona el proyecto que deseas usar.

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

    4. Opcional: en el campo Descripción de la cuenta de servicio, ingresa una descripción.

    5. Haga clic en Crear.

    6. Haz clic en el campo Seleccionar una función. En Todas las funciones, selecciona una función de Cloud Storage adecuada para la cuenta de servicio.

    7. Haga clic en Listo.

    gcloud

    Puedes ejecutar los siguientes comandos con la CLI de Google Cloud en tu máquina local o en Cloud Shell.

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

      gcloud iam service-accounts create NAME

    2. Otorga una función a la cuenta de servicio. Reemplaza PROJECT_ID por el ID del proyecto y ROLE por la función de Cloud Storage 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"

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

    Console

    1. En Cloud Console, ve a la página Cuentas de servicio.

      Ir a la página Cuentas de servicio

    2. Haz clic en la dirección de correo electrónico de la cuenta de servicio que deseas usar.

    3. Haga clic en Claves.

    4. Haz clic en Agregar clave -> Crear nueva clave.

    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.

    6. Haga clic en Cerrar.

    gcloud

    Puedes ejecutar el siguiente comando con la CLI de Google Cloud en tu máquina local o en Cloud Shell.

    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

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