Cambios para compilar e implementar en Google Cloud

En este documento, se explican las diferencias entre Container Registry y Artifact Registry cuando compilas imágenes de contenedor con Cloud Build y, también, las implementas 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ándares de Artifact Registry, repositorios de Artifact Registry independientes en Container Registry y admiten todas las características de Artifact Registry. Si tu administrador configura 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 también debes tener en cuenta algunas diferencias en el flujo de trabajo, como las siguientes:

  • 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 mediante un cliente de Docker, consulta Cambios a enviar y extraer con Docker.

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

Antes de comenzar

En este documento, se supone que hiciste lo siguiente:

  1. Enabled Artifact Registry en tu proyecto.
  2. Habilitaste la API de Cloud Build y la API para 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 parece al 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 compila la imagen my-image, se etiqueta con tag1 y se envía al host gcr.io 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, se extraen imágenes del registro.

    Por ejemplo, con este comando, se 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 administrador con la compilación y la implementación.

  • 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.
  • La cuenta de servicio de Cloud Build tiene permisos para crear depósitos de almacenamiento de Cloud Storage. Esto significa que la cuenta puede agregar hosts de Container Registry automáticamente 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 depósitos de almacenamiento de todo el proyecto, incluidos los que no utiliza Container Registry.

En Artifact Registry, hay una separación clara de las funciones de administrador y compilación que cambian los pasos del 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. Modificado: 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 ejemplo de Container Registry, pero usa una ruta de acceso del repositorio de Artifact Registry para la imagen.

    gcloud builds submit --tag us-central1-docker.pkg.dev/my-repo/my-image:tag1
    
  4. Cambiado: 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 ejemplo de Container Registry, pero usa la ruta de acceso del repositorio de Artifact Registry para la imagen.

    gcloud run deploy my-service --image us-central1-docker.pkg.dev/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 se encuentran en un proyecto diferente al Artifact Registry.
  • Usas 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 otras cuentas de usuario o de servicio.

Habilitar la API

Puntos clave:

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

De forma predeterminada, Cloud Build tiene los permisos necesarios para crear un depósito de almacenamiento, por lo que el envío inicial de la imagen y las inserciones posteriores no se pueden distinguir.

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

Cloud Build no tiene permisos para crear un repositorio.

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:

  • 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.
  • Otorga las funciones adecuadas de Artifact Registry a otras cuentas que acceden a Artifact Registry.
  • 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 comparación siguiente, se describen los permisos para cada servicio:

Container Registry

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

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.

Cloud Build tiene permisos en la función de escritor de Artifact Registry, ya que solo necesita enviar y extraer imágenes.

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.

Compila y envía 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 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 con éxito una imagen a un host de registro que aún no existe en el proyecto de Google Cloud. Para esta inserción de imagen inicial, Cloud Build tiene permisos para agregar de forma automática el host de 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 acceso de las imágenes en tu archivo de configuración de compilación o compilación ogcloud builds submit comandos.

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.

El siguiente archivo de ejemplo cloudbuild.yaml 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.

El siguiente comando de ejemplo 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-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 tu configuración de implementació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 con la ruta de acceso a un repositorio de Artifact Registry existente.

El siguiente archivo de ejemplo cloudbuild.yaml 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 con 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 para 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

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