Prepara el entorno

Antes de crear una canalización de Image Builder, primero debes preparar tu entorno de Google Cloud . Para preparar tu entorno, completa las siguientes tareas:

Antes de comenzar

  • Si aún no lo hiciste, configura la autenticación. La autenticación verifica tu identidad para acceder a los servicios y las APIs de Google Cloud . Para ejecutar código o muestras desde un entorno de desarrollo local, puedes autenticarte en Compute Engine seleccionando una de las siguientes opciones:

    Selecciona la pestaña que corresponda a la forma en que planeas usar las muestras de esta página:

    Console

    Cuando usas la consola de Google Cloud para acceder a los servicios y las APIs de Google Cloud , no necesitas configurar la autenticación.

    gcloud

    1. Instala Google Cloud CLI. Después de la instalación, inicializa Google Cloud CLI con el siguiente comando: 

      gcloud init

      Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

  • Configura una región y una zona predeterminadas.

    • REST

    Para usar las muestras de la API de REST incluidas en esta página en un entorno de desarrollo local, debes usar las credenciales que proporciones a la gcloud CLI.

      Instala Google Cloud CLI.

      Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

    Para obtener más información, consulta Autentícate para usar REST en la documentación de autenticación de Google Cloud .

Roles obligatorios

Para obtener los permisos que necesitas para preparar tu entorno, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Solicitud de incorporación

Image Builder está disponible de forma general con una lista de entidades permitidas. Para incorporar tu proyecto Google Cloud al canal de personalización de imágenes, envía elformulario de solicitud de acceso o comunícate con tu equipo de cuentas Google Cloud .

Cuentas de servicio incluidas en la lista de entidades permitidas

La lista de entidades permitidas otorga acceso a tu proyecto por número de proyecto. Como resultado, la lista de entidades permitidas solo cubre las cuentas de servicio, que incluyen las siguientes:

  • Cuentas de servicio administradas por el usuario que creas en tu proyecto
  • Cuentas de servicio predeterminadas que Google Cloud crea en tu proyecto, como la cuenta de servicio predeterminada de Compute Engine (PROJECT_NUMBER-compute@developer.gserviceaccount.com).

La lista de entidades permitidas no incluye las cuentas de servicio propiedad de Google, ya queGoogle Cloud crea estas cuentas de servicio en proyectos propiedad de Google en lugar de en tu proyecto. Las cuentas de servicio propiedad de Google incluyen las siguientes:

  • Agentes de servicio, como service-PROJECT_NUMBER@gcp-sa-SERVICE.iam.gserviceaccount.com.
  • La cuenta de servicio heredada de Cloud Build (PROJECT_NUMBER@cloudbuild.gserviceaccount.com), que Google posee y administra.

Para obtener más información sobre estos tipos de cuentas de servicio, consulta Tipos de cuentas de servicio.

Si una compilación se ejecuta como una cuenta de servicio propiedad de Google, no puede leer las imágenes de contenedor del orquestador de Image Builder en Artifact Registry. Como resultado, la canalización falla con un error de permiso denegado. Para evitar este error, ejecuta tus canalizaciones como una cuenta de servicio administrada por el usuario que crees en tu proyecto y especifica esa cuenta de servicio cuando envíes una compilación. Para obtener más información, consulta Configura la cuenta de servicio de Image Builder y Cuenta de servicio predeterminada de Cloud Build.

Habilita las APIs

Image Builder requiere que habilites las APIs de Compute Engine, Cloud Build, Artifact Registry, Service Usage y Resource Manager. Para habilitar las APIs con la consola de Google Cloud o Google Cloud CLI, selecciona una de las siguientes pestañas:

Console

Habilita las APIs de Compute Engine, Cloud Build, Artifact Registry, Service Usage y Cloud Resource Manager si alguna aún no está habilitada.

Roles necesarios para habilitar las APIs

Para habilitar APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

Habilitar las API

gcloud

Habilita las APIs de Compute Engine, Cloud Build, Artifact Registry, Service Usage y Cloud Resource Manager si alguna aún no está habilitada:

Roles necesarios para habilitar las APIs

Para habilitar APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles. 

gcloud services enable compute.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com serviceusage.googleapis.com cloudresourcemanager.googleapis.com

Configura la cuenta de servicio de Image Builder

El orquestador de Image Builder se ejecuta con una cuenta de servicio administrada por el usuario. Cuando ejecutas una canalización de compilación de imágenes, Cloud Build conecta esta cuenta de servicio a instancias temporales de VM de trabajador y de prueba para realizar acciones de personalización y validación. Esta cuenta de servicio necesita los siguientes roles:

  • Administrador de Compute (roles/compute.admin): Administra instancias de VM, discos persistentes e imágenes de SO invitado.
  • Usuario de cuenta de servicio (roles/iam.serviceAccountUser): Permite que Cloud Build conecte la cuenta de servicio al trabajador efímero y a las instancias de VM de prueba.
  • Administrador de almacenamiento (roles/storage.admin): Lee y escribe registros y artefactos de compilación temporales en el bucket de etapa de pruebas workdir de Cloud Storage.
  • Logging Log Writer (roles/logging.logWriter): Escribe registros de ejecución en Cloud Logging.
  • Visualizador de Service Usage (roles/serviceusage.serviceUsageViewer): Verifica los estados del servicio del proyecto durante la ejecución de la canalización.
  • Editor de Cloud Build (roles/cloudbuild.builds.editor): Activa y ejecuta trabajos de Cloud Build, y exporta imágenes.
  • (Opcional) Administrador de Artifact Registry (roles/artifactregistry.admin): Sube los archivos .tar de la imagen de SO generada a Artifact Registry.

Puedes usar una cuenta de servicio existente o crear una nueva cuenta de servicio dedicada para tu canalización de compilación. Usa una cuenta de servicio que resida en tu proyecto. No ejecutes tus canalizaciones como una cuenta de servicio propiedad de Google, como la cuenta de servicio heredada de Cloud Build, ya que la lista de entidades permitidas de Image Builder no cubre estas cuentas de servicio. Para obtener más información, consulta Cuentas de servicio incluidas en la lista de entidades permitidas y Cuenta de servicio predeterminada de Cloud Build.

Para crear una nueva cuenta de servicio dedicada y otorgar los roles requeridos con la consola de Google Cloud o gcloud CLI, selecciona una de las siguientes pestañas:

Console

    Asegúrate de tener el rol de IAM de Creador de cuentas de servicio (roles/iam.serviceAccountCreator) y el rol de Administrador de IAM de proyecto (roles/resourcemanager.projectIamAdmin). Obtén más información para otorgar roles.

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

    Ve a Crear cuenta de servicio
  2. Elige tu proyecto.

  3. Escribe un nombre en el campo Nombre de cuenta de servicio. La consola de Google Cloud completa el campo ID de cuenta de servicio según este nombre.

    Opcional: en el campo Descripción de la cuenta de servicio, escribe una descripción. Por ejemplo, Service account for quickstart.

  4. Haz clic en Crear y continuar.

  5. Otorga los siguientes roles a la cuenta de servicio: Compute Engine > Administrador de Compute, Cuentas de servicio > Usuario de cuenta de servicio, Cloud Storage > Administrador de almacenamiento, Cloud Logging > Escritor de registros, Service Usage > Visualizador de Service Usage, Cloud Build > Editor de Cloud Build, Artifact Registry > Administrador de Artifact Registry.

    Para otorgar un rol, busca la lista Selecciona un rol y, luego, selecciona el rol.

    Para otorgar roles adicionales, haz clic en Agregar otro rol y agrega cada rol adicional.

  6. Haz clic en Continuar.

  7. En el campo Rol de los usuarios de la cuenta de servicio, ingresa el identificador del principal que conectará la cuenta de servicio a otros recursos, como las instancias de Compute Engine.

    Esta suele ser la dirección de correo electrónico de una Cuenta de Google.

  8. Haz clic en Listo para terminar de crear la cuenta de servicio.

gcloud

  1. Crea una cuenta de servicio para tu canalización de compilación:

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
    --display-name="Image Builder Service Account"

  2. Otorga los roles requeridos (roles/compute.admin, roles/iam.serviceAccountUser, roles/storage.admin, roles/logging.logWriter, roles/serviceusage.serviceUsageViewer y roles/cloudbuild.builds.editor) a tu cuenta de servicio:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/compute.admin"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/iam.serviceAccountUser"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.admin"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/logging.logWriter"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/serviceusage.serviceUsageViewer"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/cloudbuild.builds.editor"

  3. Opcional: Otorga el rol opcional (roles/artifactregistry.admin) a tu cuenta de servicio:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/artifactregistry.admin"

Reemplaza lo siguiente:

  • SERVICE_ACCOUNT_NAME: Es el nombre de la cuenta de servicio de compilación que se creará. Por ejemplo, custom-builder-sa
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • SERVICE_ACCOUNT_EMAIL: La dirección de correo electrónico de tu cuenta de servicio de compilación.

Configura la política de la organización de imágenes confiables

Dado que Image Builder usa internamente herramientas estándar de importación y exportación de imágenes de Compute Engine durante la ejecución de la compilación, la política de imágenes de confianza (compute.trustedImageProjects) de tu proyecto debe permitir explícitamente las imágenes del siguiente proyecto:

  • projects/compute-image-import

Si la política de la organización restringe este proyecto, fallará la fase de exportación de la imagen.

Para actualizar la política de la organización, sigue estos pasos:

  1. En la política de la organización para la restricción compute.trustedImageProjects, agrega projects/compute-image-import a tu lista de publicadores permitidos.
  2. Si deseas obtener instrucciones detalladas para configurar restricciones de políticas de la organización, consulta Configura políticas de imágenes confiables y Exporta una imagen personalizada a Cloud Storage.

Configura los requisitos de acceso y de red de VPC

Durante las fases de compilación y validación, Image Builder aprovisiona VMs de trabajador y de prueba temporales en tu proyecto de Google Cloud . De forma predeterminada, Image Builder conecta las instancias a tu red de VPC default y asigna direcciones IP externas efímeras.

Si especificas un network o un subnetwork personalizados, o bien configuras externalIP: none en tu archivo de receta imagebuilder.yaml, haz lo siguiente:

  • Acceso privado a Google y Cloud NAT: Si las VMs de trabajador o de prueba están configuradas con externalIP: none (sin IP externa), tu subred de VPC debe tener habilitado el Acceso privado a Google para que las instancias puedan acceder a las APIs y los servicios de Google (como Cloud Storage y Artifact Registry). Si los pasos de personalización descargan paquetes del SO o dependencias de repositorios externos de Internet, también debes configurar Cloud NAT en la subred.
  • Reglas de firewall: Asegúrate de que las reglas de firewall de tu VPC permitan el tráfico de salida a las APIs de Google y a los repositorios de software necesarios. Si planeas conectarte a VMs de trabajadores activas para la depuración interactiva (debug: true), asegúrate de que las reglas de firewall permitan la entrada en el puerto TCP 22. Si las instancias de VM no tienen una IP externa, permite la entrada desde el rango de IP de Identity-Aware Proxy (IAP) 35.235.240.0/20 para el reenvío de TCP.

Configura Artifact Registry

Para almacenar y administrar tus imágenes de SO personalizadas, los metadatos de seguridad y las certificaciones de procedencia de la compilación de SLSA, debes configurar un repositorio genérico en Artifact Registry. Almacenar tus imágenes en Artifact Registry te permite mantener un registro seguro e inmutable de las imágenes publicadas.

Cuando configuras un destino de Artifact Registry, Image Builder realiza los siguientes pasos:

  • Exporta el disco de arranque de la VM finalizado como un archivo tar estándar (.tar.gz).
  • Sube el archivo tar a tu repositorio genérico en Artifact Registry.
  • Genera y firma certificaciones de procedencia de compilación de SLSA para el artefacto y, así, lo vincula a los metadatos de origen.
  • Registra la imagen de Compute Engine lista para producción en Compute Engine con el URI del archivo .tar de Artifact Registry como fuente de la plantilla.

Para configurar un registro de Artifact Registry genérico, completa las siguientes tareas:

  1. Asegúrate de que la cuenta de servicio que se usa para ejecutar la canalización de Image Builder tenga el rol de Administrador de Artifact Registry (roles/artifactregistry.admin) a nivel del repositorio o del proyecto. Para obtener instrucciones detalladas, consulta Configura la cuenta de servicio de Image Builder.

  2. Crea un repositorio con el formato generic. Para crear tu repositorio, ejecuta el comando gcloud artifacts repositories create:

    gcloud artifacts repositories create REPOSITORY_NAME \
    --repository-format=generic \
    --location=REPOSITORY_LOCATION

    Reemplaza los marcadores de posición que se indican más abajo:

    • REPOSITORY_NAME: Un nombre para tu repositorio genérico. Por ejemplo, custom-os-images
    • REPOSITORY_LOCATION: Una región admitida. Por ejemplo, us-central1.

¿Qué sigue?