Cambios para compilar e implementar en Google Cloud

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

En esta guía, las comparaciones se enfocan en los repositorios estándar de Artifact Registry, los repositorios normales de Artifact Registry que son independientes de Container Registry y admiten todas las características de Artifact Registry. Si tu administrador configura repositorios con compatibilidad con el dominio gcr.io, las solicitudes a los nombres de host gcr.io se redireccionan de forma automática a un repositorio de Artifact Registry correspondiente, y las cuentas de servicio predeterminadas que tienen acceso a Container Registry tienen permisos predeterminados equivalentes para Artifact Registry.

Para obtener información sobre las diferencias entre Container Registry y Artifact Registry mediante un cliente de Docker, consulta Cambios en el envío y la extracción con Docker.

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

Antes de comenzar

En este documento, se supone que cuentas con lo siguiente:

1. Habilitar Artifact Registry en tu proyecto
2. Habilitaste la API de Cloud Build y la API de cualquier otro servicio de Google Cloud que uses con Artifact Registry.

Cambios en el flujo de trabajo

Cuando usas Cloud Build con Container Registry dentro del mismo proyecto, el flujo de trabajo se ve de la siguiente manera:

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 compila la imagen my-image, se etiqueta con tag1 y se envía al gcr.io host en el proyecto my-project:

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

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

   Por ejemplo, este comando implementa 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 de las 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 registros y agregar hosts de registro de forma predeterminada.
• La cuenta de servicio de Cloud Build tiene permisos para crear buckets de almacenamiento de Cloud Storage. Esto significa que la cuenta puede agregar automáticamente hosts de Container Registry a un proyecto la primera vez que envía una imagen al host. También significa que la cuenta puede crear, leer y escribir en buckets de almacenamiento de todo el proyecto, incluidos los buckets que no usa Container Registry.

En Artifact Registry, hay una separación clara de las funciones de administrador y de compilación que cambian los pasos del flujo de trabajo de compilación e implementación. A fin de adaptar el flujo de trabajo de Container Registry para Artifact Registry, realiza los siguientes cambios. Cada paso se 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 para poder enviarle imágenes. El envío de 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. Cambiado: Compila, etiqueta y envía una imagen al repositorio con Cloud Build mediante Dockerfile o un archivo de configuración de compilación.

   El siguiente comando de ejemplo es el mismo que el 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. Cambiada: Implementa la imagen en un entorno de ejecución de Google Cloud, como Cloud Run o GKE.

   El siguiente comando de ejemplo es el mismo que el 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 funciones diferentes a las de Container Registry para controlar el acceso a las imágenes. Debes configurar permisos en las siguientes situaciones:

• Los entornos de ejecución de Cloud Build o Google Cloud están en un proyecto diferente que Artifact Registry.
• Usa cuentas de servicio personalizadas para los servicios de Google Cloud, como Cloud Build o GKE, en lugar de las cuentas de servicio predeterminadas.
• Otorgaste permisos a otra cuenta de usuario o de servicio.

Habilitar la API

Puntos clave:

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

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

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 Artifact Analysis
• 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 los entornos de ejecución de Google Cloud tienen acceso de forma implícita a las imágenes en Container Registry cuando el registro está en el mismo proyecto.

Artifact Registry

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

Puedes habilitar varias APIs en el mismo proyecto con gcloud. Por ejemplo, para habilitar la API de Cloud Build y 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 enviarle una imagen.
• Container Registry almacena todas las imágenes en una sola multirregión en el mismo bucket 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 bucket 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 bucket de almacenamiento para otros usuarios.

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

Dentro de un proyecto, un host de registro almacena todas las imágenes en el mismo bucket de almacenamiento. En el siguiente ejemplo, el proyecto my-project tiene dos imágenes llamadas web-app en el registro gcr.io. Uno está directamente en el ID del proyecto my-project. La otra imagen se encuentra 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 la función de administrador del repositorio de Artifact Registry debe crear el repositorio antes de enviarle imágenes. 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 imagen deben incluir un repositorio.

Rutas de acceso 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

La ruta de acceso a la imagen no es 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 el envío de una imagen a un repositorio faltante.

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

Otorgando permisos

Puntos clave:

• 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 estándar en el dominio pkg.dev.
• Otorga los roles de Artifact Registry adecuados a otras cuentas que acceden a Artifact Registry.
• Container Registry admite el control de acceso a nivel de bucket de almacenamiento. Artifact Registry admite el control de acceso a nivel del repositorio.

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

Container Registry

Container Registry usa los roles de Cloud Storage para controlar el acceso. Cloud Build tiene los permisos necesarios en la función de administrador de almacenamiento para agregar hosts de Container Registry a un proyecto.

Visualizador de objetos de Storage a nivel del bucket de almacenamiento

Extrae (lectura) imágenes de los hosts de registro existentes en el proyecto.

Escritor de buckets heredados de almacenamiento a nivel del bucket de almacenamiento

Enviar (escribir) y extraer (leer) imágenes para los hosts de registro existentes en el proyecto

Administrador de almacenamiento a nivel de proyecto

Para agregar un host de registro a un proyecto, envía una imagen inicial al host.

Después del envío inicial de imágenes a un registro, otorgas funciones de Cloud Storage a otras cuentas que requieren acceso al bucket de almacenamiento. Ten en cuenta que cualquier cuenta con todos los permisos en el rol de administrador de almacenamiento puede leer, escribir y borrar buckets y objetos de almacenamiento en todo el proyecto.

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

Cloud Build tiene permisos en la función de escritor de Artifact Registry, ya que solo necesita enviar y extraer imágenes con repositorios estándar en el dominio pkg.dev.

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

Lector de Artifact Registry

Enumerar artefactos y repositorios Descarga los artefactos.

Escritor de Artifact Registry

Enumerar artefactos y repositorios Descarga artefactos, sube versiones nuevas de ellos 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 del repositorio de Artifact Registry para crear, actualizar, borrar y otorgar permisos a los repositorios.

Puedes aplicar estos permisos a nivel de 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 detalles sobre cómo otorgar permisos de Artifact Registry, consulta la documentación de control de acceso.

Compila y envía imágenes

Puntos clave:

• Debes crear un repositorio de Docker de Artifact Registry antes de enviarle una imagen.
• Los nombres de host de Artifact Registry son diferentes de los nombres de host 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 proyecto de Google Cloud. Para este envío inicial de imágenes, Cloud Build tiene permisos para agregar de forma automática el host de registro al proyecto.

Sigue estos pasos para adaptar un flujo de trabajo de Container Registry:

1. Configura los repositorios antes de enviarles imágenes.
2. Actualiza las rutas de acceso de la imagen en tu archivo de configuración de compilación o en los comandos gcloud builds submit.

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

Reemplaza las rutas de acceso de Container Registry para las imágenes que compilas con la ruta de acceso a un repositorio de Artifact Registry existente.

En el siguiente archivo cloudbuild.yaml de ejemplo, se compila 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'

Luego, puedes compilar la imagen con el siguiente comando:

gcloud builds submit --config cloudbuild.yaml

Compila con un Dockerfile

Reemplaza las rutas de acceso de Container Registry para las imágenes que compilas con la ruta de acceso a un repositorio de Artifact Registry existente.

Con el siguiente comando de ejemplo, se compila 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

Implementa imágenes

Punto clave:

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

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

Cloud Build

Reemplaza las rutas de acceso de Container Registry para las imágenes que implementas por la ruta de acceso a un repositorio de Artifact Registry existente.

En el siguiente archivo cloudbuild.yaml de ejemplo, se implementa la imagen de muestra 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

Reemplaza las rutas de acceso de Container Registry para las imágenes que implementas por la ruta de acceso a un repositorio de Artifact Registry existente.

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

Reemplaza las rutas de acceso de Container Registry para las imágenes que compilas con la ruta de acceso a un repositorio de Artifact Registry existente.

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

Crea un clúster desde la línea de comandos:

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

Especificación de 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/artifact-registry-samples/containers/gke/hello-app:1.0