Cambios para desarrollar y desplegar en Google Cloud

En este documento se explican las diferencias entre Container Registry y Artifact Registry al crear imágenes de contenedor con Cloud Build y desplegarlas en Google Cloud entornos de ejecución, como Cloud Run o Google Kubernetes Engine.

En esta guía, las comparaciones se centran en los repositorios estándar de Artifact Registry, que son repositorios normales de Artifact Registry independientes de Container Registry y que admiten todas las funciones de Artifact Registry. Si tu administrador ha configurado repositorios compatibles con el dominio gcr.io, las solicitudes a los nombres de host gcr.io se redirigen automáticamente a un repositorio de Artifact Registry correspondiente y las cuentas de servicio predeterminadas que tienen acceso a Container Registry tienen permisos predeterminados equivalentes en Artifact Registry.

Para obtener información sobre las diferencias entre Container Registry y Artifact Registry con un cliente Docker, consulta Cambios en la inserción y la extracción con Docker.

Usa esta información para adaptar los comandos, la configuración o la documentación que ya tengas y que estén centrados en Container Registry con Cloud Build.

Antes de empezar

En este documento se presupone que tienes lo siguiente:

1. Habilitar Artifact Registry en tu proyecto.
2. Habilitar la API de Cloud Build y la API de cualquier otro servicio de Google Cloud que estés usando con Artifact Registry.

Cambios en el flujo de trabajo

Cuando usas Cloud Build con Container Registry en el mismo proyecto, el flujo de trabajo es el siguiente:

1. Compila, etiqueta y envía una imagen al repositorio con Cloud Build mediante un Dockerfile o un archivo de configuración de compilación.

   En el siguiente ejemplo se crea la imagen my-image, se etiqueta con tag1 y se envía al host gcr.io del proyecto my-project:

   gcloud builds submit --tag gcr.io/my-project/my-image:tag1
   

2. Google Cloud Entornos de ejecución, como Cloud Run y Google Kubernetes Engine, extraen imágenes del registro.

   Por ejemplo, este comando despliega la imagen del paso anterior en Cloud Run como my-service.

   gcloud run deploy my-service --image gcr.io/my-project/my-image:tag1
   

El flujo de trabajo de Container Registry combina las responsabilidades de los administradores con la compilación y la implementación.

• Cuando habilitas algunas Google Cloud APIs, la API 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 registros y añadir hosts de registro de forma predeterminada.
• La cuenta de servicio de Cloud Build tiene permisos para crear cubos de almacenamiento de Cloud Storage. Esto significa que la cuenta puede añadir automáticamente hosts de Container Registry a un proyecto la primera vez que envíe una imagen al host. Esto también significa que la cuenta puede crear, leer y escribir en segmentos de almacenamiento de todo el proyecto, incluidos los segmentos que no utiliza Container Registry.

En Artifact Registry, los roles de administrador y de compilación están claramente separados, lo que cambia los pasos del flujo de trabajo de compilación e implementación. Para adaptar el flujo de trabajo de Container Registry a Artifact Registry, haz los cambios siguientes. Cada paso incluye un enlace a información adicional sobre cómo modificar el flujo de trabajo.

1. Nuevo: habilite 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 la API automáticamente.

2. Nuevo: crea el repositorio de Docker de destino si aún no existe. Debes crear un repositorio para poder insertar imágenes en él. Al enviar una imagen no se puede activar la creación de un repositorio y la cuenta de servicio de Cloud Build no tiene permisos para crear repositorios.

3. Cambiado: compila, etiqueta y envía una imagen al repositorio con Cloud Build mediante un Dockerfile o un archivo de configuración de compilación.

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

   gcloud builds submit --tag us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
   

4. Cambiado: despliega la imagen en un Google Cloud entorno de tiempo de ejecución como Cloud Run o GKE.

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

   gcloud run deploy my-service --image us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
   

Además, Artifact Registry usa roles diferentes a los de Container Registry para controlar el acceso a las imágenes. Debe configurar los permisos en las siguientes situaciones:

• Cloud Build o los entornos de ejecución están en un proyecto diferente al de Artifact Registry. Google Cloud
• Usas cuentas de servicio personalizadas para servicios como Cloud Build o GKE en lugar de las cuentas de servicio predeterminadas. Google Cloud
• Has concedido permisos a otras cuentas de usuario o de servicio.

Habilitar la API

Puntos clave:

• Además de la API de otros servicios de Google Cloud , como Cloud Build, Cloud Run y GKE, debes habilitar la API de Artifact Registry.

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

Container Registry

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

• Entorno flexible de App Engine
• Cloud Build
• Cloud Run Functions
• Cloud Run
• Análisis de contenedores o análisis bajo demanda en Artifact Analysis
• Google Kubernetes Engine

Con los permisos predeterminados, los usuarios que pueden ejecutar compilaciones en Cloud Build, analizar contenedores con Artifact Analysis o desplegar contenedores enGoogle Cloud runtimes tienen acceso implícito a las imágenes de Container Registry cuando el registro está en el mismo proyecto.

Artifact Registry

Debes habilitar la API de Artifact Registry. Servicios como Cloud Build, Cloud Run y GKE no habilitan automáticamente la API Artifact Registry.

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

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

Añadir registros y repositorios

Puntos clave:

• Debes crear un repositorio de Docker de Artifact Registry antes de enviar una imagen a él.
• Container Registry almacena todas las imágenes en una sola multirregión en el mismo segmento de almacenamiento. En Artifact Registry, puede crear varios repositorios en la misma región o en varias regiones 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, puede añadir hasta cuatro hosts de registro a su proyecto. Para añadir un host de registro, envía la primera imagen.

1. Para añadir un registro como gcr.io a tu proyecto, una cuenta con el rol Administrador de Storage a nivel de proyecto envía una imagen inicial.

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

   1. Añade el gcr.io host al proyecto
   2. Crea un segmento de almacenamiento para gcr.io en el proyecto.
   3. Guarda la imagen como gcr.io/my-project/my-image:1.0

2. Después de esta primera inserción, puedes conceder permisos a otros usuarios para el contenedor de almacenamiento.

De forma predeterminada, Cloud Build tiene los permisos necesarios para crear un segmento de almacenamiento, por lo que el envío inicial de la imagen y los envíos posteriores no se distinguen.

En un proyecto, un host de registro almacena todas las imágenes en el mismo segmento de almacenamiento. En el ejemplo siguiente, el proyecto my-project tiene dos imágenes llamadas web-app en el registro gcr.io. Una de ellas 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

Cloud Build no tiene permisos para crear un repositorio estándar en el dominio pkg.dev de Artifact Registry.

Una cuenta con el rol Administrador de repositorios de Artifact Registry debe crear el repositorio antes de que puedas insertar imágenes en él. Después, puedes conceder permisos al repositorio a otros usuarios.

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

Rutas de imágenes 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 no se puede enviar una imagen a un repositorio que no existe.

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

Concediendo permisos

Puntos clave:

• Los servicios deGoogle 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 estándar en el dominio pkg.dev.
• Concede los roles de Artifact Registry adecuados a otras cuentas que accedan a Artifact Registry.
• Container Registry admite el control de acceso a nivel de segmento de almacenamiento. Artifact Registry admite el control de acceso a nivel de repositorio.

En la siguiente comparación se describen los permisos de cada servicio:

Container Registry

Container Registry usa los roles de Cloud Storage para controlar el acceso. Cloud Build tiene los permisos necesarios en el rol Administrador de Storage para añadir hosts de Container Registry a un proyecto.

Lector de objetos de Storage a nivel de segmento de almacenamiento

Extraer (leer) imágenes de los hosts de registro del proyecto.

Editor de segmentos heredados de Storage a nivel de segmento de almacenamiento

Enviar (escribir) y extraer (leer) imágenes de hosts de registro del proyecto.

Administrador de Storage a nivel de proyecto

Añade un host de registro a un proyecto enviando una imagen inicial al host.

Después de enviar la imagen inicial a un registro, asigna roles de Cloud Storage a otras cuentas que necesiten acceder al segmento de almacenamiento. Ten en cuenta que cualquier cuenta con todos los permisos del rol Administrador de Storage puede leer, escribir y eliminar segmentos y objetos de almacenamiento en todo el proyecto.

Los permisos de un segmento de almacenamiento se aplican a todos los repositorios del registro. Por ejemplo, cualquier usuario con permisos de lector de objetos de Storage en el cubo de 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. Estos roles proporcionan una separación clara entre los roles de administrador y de usuario del repositorio.

Cloud Build tiene permisos en el rol Escritor de Artifact Registry, ya que solo necesita insertar y extraer imágenes con repositorios estándar en el dominio pkg.dev.

Solo las cuentas que gestionan repositorios deben tener el rol Administrador del repositorio de Artifact Registry o Administrador de Artifact Registry.

Lector de Artifact Registry

Lista de artefactos y repositorios. Descargar artefactos.

Escritor de Artifact Registry

Lista de artefactos y repositorios. Descargar artefactos, subir nuevas versiones de artefactos y añadir o actualizar etiquetas.

Administrador del repositorio de Artifact Registry

Permisos de escritura de Artifact Registry y permisos para eliminar artefactos y etiquetas.

Administrador de Artifact Registry

Permisos de administrador del repositorio de Artifact Registry y permisos para crear, actualizar, eliminar y conceder permisos a repositorios.

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

• Concede acceso al equipo 1 a us-central1-docker.pkg.dev/my-project/team1
• Concede acceso al equipo 2 a us-central1-docker.pkg.dev/my-project/team2.

Para obtener información sobre cómo conceder permisos de Artifact Registry, consulta la documentación sobre control de acceso.

Crear y enviar imágenes

Puntos clave:

• Debes crear un repositorio de Docker de Artifact Registry antes de enviar una imagen a él.
• Los nombres de host de Artifact Registry son diferentes de los de Container Registry.

Cloud Build puede compilar, etiquetar y enviar una imagen en un solo paso.

Con Container Registry, Cloud Build puede enviar correctamente una imagen a un host de registro que aún no existe en el Google Cloud proyecto. Para esta inserción inicial de la imagen, Cloud Build tiene permisos para añadir automáticamente el host del registro al proyecto.

Para adaptar un flujo de trabajo de Container Registry, sigue estos pasos:

1. Configura tus repositorios antes de enviar imágenes a ellos.
2. Actualiza las rutas de las imágenes en el archivo de configuración de compilación o en los gcloud builds submit comandos.

Compilar con un archivo de configuración de compilación

Sustituye las rutas de Container Registry de las imágenes que crees por la ruta a un repositorio de Artifact Registry.

El siguiente archivo cloudbuild.yaml crea la imagen us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1:

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: [ 'build', '-t', 'us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1', '.' ]
images:
- 'us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1'

A continuación, puedes compilar la imagen con el comando:

gcloud builds submit --config cloudbuild.yaml

Compilar con un Dockerfile

Sustituye las rutas de Container Registry de las imágenes que crees por la ruta a un repositorio de Artifact Registry.

El siguiente comando de ejemplo crea la imagen us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1 con un Dockerfile en el directorio actual:

gcloud builds submit --tag us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1

Desplegar imágenes

Punto clave:

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

Para adaptar un flujo de trabajo de Container Registry, actualiza las rutas de las imágenes en la configuración y los comandos de despliegue. En las siguientes secciones se muestran ejemplos de Cloud Build, Cloud Run y GKE, pero el mismo enfoque se aplica a cualquier otro Google Cloud servicio que despliegue imágenes.

Cloud Build

Sustituye las rutas de Container Registry de las imágenes que despliegues por la ruta a un repositorio de Artifact Registry.

El siguiente archivo cloudbuild.yaml implementa la imagen de ejemplo us-docker.pkg.dev/cloudrun/container/hello.

steps:
- name: 'gcr.io/cloud-builders/gcloud'
  args:
  - 'run'
  - 'deploy'
  - 'cloudrunservice'
  - '--image'
  - 'us-docker.pkg.dev/cloudrun/container/hello'
  - '--region'
  - 'us-central1'
  - '--platform'
  - 'managed'
  - '--allow-unauthenticated'

Cloud Run

Sustituye las rutas de Container Registry de las imágenes que despliegues por la ruta a un repositorio de Artifact Registry.

Por ejemplo, este comando implementa la imagen de muestra us-docker.pkg.dev/cloudrun/container/hello.

gcloud run deploy my-service --image us-docker.pkg.dev/cloudrun/container/hello

GKE

Sustituye las rutas de Container Registry de las imágenes que crees por la ruta a un repositorio de Artifact Registry.

En los siguientes ejemplos de Artifact Registry se usa la imagen de ejemplo us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0.

Para crear un clúster desde la línea de comandos, sigue estos pasos:

kubectl create deployment hello-server --image=us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0

Especificar una imagen en un manifiesto de implementación:

In a deployment manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  selector:
    matchLabels:
      run: my-app
  template:
    metadata:
      labels:
        run: my-app
    spec:
      containers:
      - name: hello-app
        image: us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0