Cambios para Docker

En este documento, se explican las diferencias entre Container Registry y Artifact Registry para autenticar, enviar y extraer imágenes de contenedores con Docker.

En esta guía, las comparaciones se enfocan en los repositorios estándares de Artifact Registry, repositorios de Artifact Registry independientes en Container Registry y admiten todas las características de Artifact Registry.

Si tu administrador configuró repositorios compatibles con el dominio gcr.io, las solicitudes a los nombres de host gcr.io se redireccionan de forma automática a un repositorio correspondiente de Artifact Registry, pero debes de todas formas Ten en cuenta las siguientes diferencias en el flujo de trabajo:

  • Creación de repositorio: En Artifact Registry, solo puedes enviar imágenes a un repositorio existente.
  • Permisos: Artifact Registry tiene sus propios permisos para controlar el acceso a los repositorios.

Para obtener información sobre las diferencias entre Container Registry y Artifact Registry cuando compilas con Cloud Build y su implementación en Cloud Run o Google Kubernetes Engine, consultaCambios para Cloud Build, Cloud Run y GKE las rutas "a GCP".

Usa esta información para adaptar los comandos, la configuración o la documentación existentes centrados en Container Registry con Docker.

Antes de comenzar

En este documento, se supone que hiciste lo siguiente:

  1. Enabled Artifact Registry en tu proyecto.
  2. Docker está instalado. Docker se incluye en Cloud Shell.

Descripción general

En un nivel alto, el flujo de trabajo para usar Docker con Container Registry o Art Registry es el mismo.

Container Registry Artifact Registry
Administrador
  1. Habilitar la API de Container Registry
  2. Agrega una host de registro, como “gcr.io”, mediante el envío de una imagen inicial al host.
  3. Otorga funciones de Cloud Storage en el depósito de almacenamiento para que el host del registro proporcione acceso a las imágenes.
Administrador
  1. Habilita la API de Artifact Registry
  2. Agrega un repositorio de Docker.
  3. Otorga funciones de Artifact Registry para proporcionar acceso a las imágenes.
Usuarios del registro
  1. Define la imagen como un archivo Dockerfile.
  2. Compila la imagen.
  3. Autentica en el registro.
  4. Etiquete y envíe la imagen al registro.
  5. Extrae la imagen del registro o impleméntala en un entorno de ejecución de Google Cloud.
Usuarios del registro
  1. Define la imagen como un archivo Dockerfile.
  2. Compila la imagen.
  3. Autentica en el registro.
  4. Etiquete y envíe la imagen al registro.
  5. Extrae la imagen del registro o impleméntala en un entorno de ejecución de Google Cloud.

Sin embargo, un acceso directo para Container Registry combina las funciones de administrador y usuario en un solo flujo de trabajo. Este acceso directo es común en:

  • Guías de inicio rápido y instructivos en los que realizas pruebas en un entorno para el que tienes permisos amplios.
  • Flujos de trabajo que usan Cloud Build, ya que la cuenta de servicio de Cloud Build tiene permisos para agregar un host de registro en el mismo proyecto de Google Cloud.

El flujo de trabajo de la combinación de teclas se ve de la siguiente manera:

  1. Habilita la API de Container Registry.
  2. Otorga permisos a la cuenta que accederá a Artifact Registry.
  3. Autentica en el registro. La opción de autenticación más simple es usar el auxiliar de credenciales de Docker en el SDK de Cloud. Este es un paso de configuración único.

    gcloud auth configure-docker
    
  4. Compila y etiqueta la imagen. Por ejemplo, este comando compila y etiqueta la imagen gcr.io/my-project/my-image:tag1:

    docker build -t gcr.io/my-project/my-image:tag1
    
  5. Envía la imagen al registro. Por ejemplo:

    docker push gcr.io/my-project/my-image:tag1
    

    Si el host del registro gcr.io no existe en el proyecto, Container Registry agrega el host antes de subir la imagen.

  6. Extrae la imagen del registro o impleméntala en un entorno de ejecución de Google Cloud. Por ejemplo:

    docker pull gcr.io/my-project/my-image:tag1
    

Este flujo de trabajo se basa en los siguientes accesos directos:

  • La cuenta que envía imágenes tiene la función de administrador de almacenamiento o una función con los mismos permisos, como Propietario. Los permisos amplios de esta función permiten el acceso de lectura y escritura a todos los depósitos de almacenamiento de un proyecto, incluidos los depósitos que no utiliza Container Registry.
  • Cuando habilitas algunas API de Google Cloud, la API de Container Registry se habilita automáticamente. Esto significa que los usuarios de estos servicios tienen acceso implícito a Container Registry en el mismo proyecto. Por ejemplo, los usuarios que pueden ejecutar compilaciones en Cloud Build pueden enviar imágenes a los registros y agregar hosts de registro de forma predeterminada.

En Artifact Registry, hay una separación clara de las funciones de usuario de administrador y repositorio que cambian los pasos en el flujo de trabajo de compilación y de implementación. Para adaptar el flujo de trabajo de Container Registry para Artifact Registry, realiza los siguientes cambios. Cada paso vincula a información adicional sobre la modificación del flujo de trabajo.

  1. Nuevo: Habilita la API de Artifact Registry.

    Debes habilitar la API de Artifact Registry. Cloud Build y los entornos de ejecución, como Cloud Run y GKE, no habilitan automáticamente la API.

  2. Nuevo: Crea el repositorio de Docker de destino si aún no existe. Debes crear un repositorio antes de poder enviar cualquier imagen. Enviar una imagen no puede activar la creación de un repositorio y la cuenta de servicio de Cloud Build no tiene permisos para crear repositorios.

  3. Otorga permisos a la cuenta que interactuará con Artifact Registry.

  4. Modificado: Autentica al repositorio. Si usas el auxiliar de credenciales en el SDK de Cloud, debes especificar los hosts que deseas agregar a tu configuración de cliente de Docker. Por ejemplo, este comando agrega el host us-central-docker.pkg.dev:

    gcloud auth configure-docker us-central-docker.pkg.dev
    
  5. Cambiado: Compila y etiqueta la imagen.

    El siguiente comando de ejemplo es el mismo que el ejemplo de Container Registry, pero usa una ruta de acceso del repositorio de Artifact Logging para la imagen.

    docker build -t us-central-docker.pkg.dev/my-project/my-repo/my-image:tag1
    
  6. Modificado: Envía la imagen al repositorio mediante la ruta de Art Registry Registry. Por ejemplo:

    docker push us-central-docker.pkg.dev/my-project/my-repo/my-image:tag1
    
  7. Changeded: Extrae la imagen del repositorio mediante la ruta de Art Registry Registry. Por ejemplo:

    docker pull us-central-docker.pkg.dev/my-project/my-repo/my-image:tag1
    

Habilitar la API

Puntos clave:

En la siguiente comparación, se describe cómo habilitar la API para cada servicio:

Container Registry

Debes habilitar la API de Container Registry antes de usar Docker o otros clientes de terceros con Container Registry.

Cuando habilitas las siguientes API de Google Cloud, la API de Container Registry también se habilita automáticamente:

  • Entorno flexible de App Engine
  • Cloud Build
  • Cloud Functions
  • Cloud Run
  • Análisis de contenedores o análisis a pedido en el artefacto de artefactos
  • Google Kubernetes Engine

Con los permisos predeterminados, los usuarios que pueden ejecutar compilaciones en Cloud Build, analizar contenedores con Artifact Analysis o implementar contenedores en entornos de ejecución de Google Cloud, tienen acceso implícita a las imágenes de Container Registry cuando el registro se encuentra en la en el mismo proyecto.

Artifact Registry

Debes habilitar la API de Artifact Registry antes de usar los clientes de Docker o de otros servicios de Google Cloud con Artifact Registry.

Los servicios como Cloud Build, Cloud Run y GKE no habilitan automáticamente la API de Artifact Registry.

Puedes habilitar varias API en el mismo proyecto mediante gcloud. Por ejemplo, para habilitar la API de Cloud Build y la API de Artifact Registry, ejecuta el siguiente comando:

gcloud services enable
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com

Agrega registros y repositorios

Puntos clave:

  • Debes crear un repositorio de Docker de Artifact Registry antes de enviar una imagen a él.

    Por lo general, un paso de creación de registro se excluye en la documentación que describe cómo enviar imágenes a Container Registry porque una cuenta con permisos de administrador de almacenamiento puede agregar un registro a un proyecto con la inserción inicial al host de registro.

  • Container Registry almacena todas las imágenes en una sola multirregión en el mismo depósito de almacenamiento. En Artifact Registry, puedes crear varios repositorios en la misma región o multirregión con políticas de acceso independientes.

En la siguiente comparación, se describe la configuración del repositorio en cada servicio:

Container Registry

En Container Registry, puedes agregar hasta cuatro hosts de registro a tu proyecto. Para agregar un host de registro, envía la primera imagen.

  1. Para agregar un registro como gcr.io a tu proyecto, una cuenta con la función de administrador de almacenamiento a nivel de proyecto envía una imagen inicial.

    Por ejemplo, si el host gcr.io no existe en el proyecto my-project, enviar la imagen gcr.io/my-project/my-image:1.0 activa los siguientes pasos:

    1. Agrega el host gcr.io al proyecto.
    2. Crea un depósito de almacenamiento para gcr.io en el proyecto.
    3. Almacena la imagen como gcr.io/my-project/my-image:1.0.
  2. Después de este envío inicial, puedes otorgar permisos al depósito de almacenamiento para otros usuarios.

Dentro de un proyecto, un host de registro almacena todas las imágenes en el mismo depósito de almacenamiento. En el siguiente ejemplo, el proyecto my-project tiene dos imágenes llamadas web-app en el registro gcr.io. Uno se encuentra directamente debajo del ID del proyecto my-project. La otra imagen está en el repositorio team1.

gcr.io/my-project/web-app
gcr.io/my-project/team1/web-app

Artifact Registry

Una cuenta con la función de administrador del repositorio de Artifact Registry debe crear el repositorio antes de enviar imágenes a él. Luego, puedes otorgar permisos al repositorio para otros usuarios.

En Artifact Registry, cada repositorio es un recurso independiente. Por lo tanto, todas las rutas de imágenes deben incluir un repositorio.

Rutas de imagen válidas:

us-central1-docker.pkg.dev/my-project/team1/web-app:1.0
us-central1-docker.pkg.dev/my-project/team2/web-app:1.0

Ruta de imagen no válida (no incluye un repositorio) :

us-central1-docker.pkg.dev/my-project/web-app:1.0

En los siguientes ejemplos, se muestran situaciones en las que falla una imagen en un repositorio faltante.

  • Enviar una imagen a us-central1-docker.pkg.dev/my-project/team1 si us-central1-docker.pkg.dev/my-project/team1 no existe.
  • Enviar una imagen a us-central1-docker.pkg.dev/my-project/team2 cuando us-central1-docker.pkg.dev/my-project/team1 exista, pero us-central1-docker.pkg.dev/my-project/team2 no existe.

Otorgando permisos

Puntos clave:

  • Otorga la función adecuada de Artifact Registry a la cuenta que usas con Artifact Registry.
  • Los servicios de Google Cloud tienen acceso de lectura o escritura equivalente a Container Registry y Artifact Registry. Sin embargo, la cuenta de servicio predeterminada de Cloud Build no puede crear repositorios.
  • Container Registry admite el control de acceso a nivel de depósito de almacenamiento. Artifact Registry admite el control de acceso a nivel del repositorio.

En la siguiente comparación, se describe la configuración de permisos en cada servicio:

Container Registry

Container Registry usa las funciones de Cloud Storage para controlar el acceso.

Visualizador de objetos de almacenamiento a nivel de depósito de almacenamiento
Extrae (lee) imágenes de hosts de registro existentes en el proyecto.
Escritor de depósitos heredados de Storage a nivel de depósito de almacenamiento
Envía y escribe (lee) imágenes para los hosts de registro existentes en el proyecto.
Administrador de almacenamiento a nivel de proyecto
Agrega una imagen inicial al host para agregar un host de registro.

Después de que la imagen inicial se envíe a un registro, debes otorgar funciones de Cloud Storage a otras cuentas que requieren acceso al depósito de almacenamiento. Ten en cuenta que cualquier cuenta con todos los permisos en la función de administrador de almacenamiento puede leer, escribir y borrar depósitos y objetos de almacenamiento en todo el proyecto.

Los permisos de un depósito de almacenamiento se aplican a todos los repositorios del registro. Por ejemplo, cualquier usuario con permisos de visualizador de objetos de almacenamiento en el depósito para gcr.io/my-project puede leer imágenes en todos estos repositorios:

gcr.io/my-project/team1
gcr.io/my-project/team2
gcr.io/my-project/test
gcr.io/my-project/production

Artifact Registry

Artifact Registry tiene sus propias funciones para controlar el acceso. Estas funciones proporcionan una separación clara entre las funciones de usuario del administrador y del repositorio.

Solo las cuentas que administran repositorios deben tener la función de Administrador de repositorio de Artifact Registry o administrador de Artifact Registry.

Lector de Artifact Registry
Enumera los artefactos y repositorios. Descarga artefactos.
Escritor de Artifact Registry
Enumera los artefactos y repositorios. Descarga artefactos, sube versiones de artefactos nuevas y agrega o actualiza etiquetas.
Administrador del repositorio de Artifact Registry
Permisos y permisos de escritor de Artifact Registry para borrar artefactos y etiquetas.
Administrador de Artifact Registry
Permisos y permisos de administrador de repositorio de Artifact Registry para crear, actualizar, borrar y otorgar permisos a los repositorios.

Puedes aplicar estos permisos a nivel del repositorio. Por ejemplo:

  • Otorgar acceso al equipo 1 para us-central1-docker.pkg.dev/my-project/team1
  • Otorga acceso al equipo 2 para us-central1-docker.pkg.dev/my-project/team2.

Para obtener más información sobre cómo otorgar permisos de Artifact Registry, consulta la documentación del control de acceso.

Autentica el registro

Puntos clave:

  • Artifact Registry admite los mismos métodos de autenticación que Container Registry.
  • En el auxiliar de credenciales de Docker, debes especificar hosts para agregar a la configuración cliente de Docker.
  • Para la autenticación con docker login, usa el host de Artifact Registry en lugar de un host de Container Registry.

Usa el auxiliar de credenciales

El comando gcloud auth configure-docker y el auxiliar de credenciales independiente solo configuran Docker para los nombres de host *.gcr.io de forma predeterminada. Para Artifact Registry, debes especificar una lista de los hosts de Artifact Registry que deseas agregar a la configuración del cliente de Docker.

Por ejemplo, para configurar la autenticación en repositorios de Docker en la región us-central1, ejecuta el siguiente comando:

gcloud auth configure-docker us-central1-docker.pkg.dev

Si luego agregas repositorios en us-east1 y asia-east1, debes ejecutar el comando de nuevo para agregar los nombres de host regionales correspondientes a tu configuración de Docker.

gcloud auth configure-docker us-east-docker.pkg.dev,asia-east1-docker.pkg.dev

Para obtener más detalles sobre los métodos de autenticación de Artifact Registry, consulta Configura la autenticación para Docker.

Usa la autenticación de contraseñas

Cuando accedas a Docker, usa el nombre de host de Artifact Registry en lugar de un nombre de host *.gcr.io. En el siguiente ejemplo, se muestra la autenticación con una clave de cuenta de servicio codificada en base64 en el host us-central1-docker.pkg.dev:

cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-central1-docker.pkg.dev

Compila y etiqueta imágenes

Puntos clave: - Artifact Registry usa un nombre de host diferente para los repositorios.

Cuando etiquetas una imagen, usa la ruta de Artifact Registry en lugar de la ruta de Container Registry. Por ejemplo:

docker tag my-image us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

Envía imágenes al registro

Puntos clave: - En Artifact Registry, el repositorio de destino debe existir antes de enviar una imagen a él. - Artifact Registry usa un nombre de host diferente para los repositorios.

Cuando envíes una imagen, usa la ruta de Artifact Registry en lugar de la ruta de Container Registry. Por ejemplo:

docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

Extrae las imágenes del registro

Punto clave:

  • Los nombres de host de Artifact Registry son diferentes de los nombres de host de Container Registry.

Cuando extraes una imagen, usa la ruta de Artifact Registry en lugar de la ruta de Container Registry. Por ejemplo:

docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

Para obtener ejemplos de la implementación de imágenes en los entornos de ejecución de Google Cloud, como Cloud Run y GKE, consulta la página sobre cómo implementar imágenes.