Prepare your environment

Before you create an Image Builder pipeline, you must first prepare your Cloud de Confiance by S3NS environment. To prepare your environment, complete the following tasks:

Before you begin

  • If you haven't already, set up authentication. Authentication verifies your identity for access to Cloud de Confiance by S3NS services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Cloud de Confiance console to access Cloud de Confiance by S3NS services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, and then sign in to the gcloud CLI with your federated identity. After signing in, initialize the Google Cloud CLI by running the following command: 

      gcloud init
    2. Set a default region and zone.

    REST

    To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

      Install the Google Cloud CLI, and then sign in to the gcloud CLI with your federated identity.

    For more information, see Authenticate for using REST in the Cloud de Confiance authentication documentation.

Required roles

To get the permissions that you need to prepare your environment, ask your administrator to grant you the following IAM roles on your project:

  • Service Usage Admin (roles/serviceusage.serviceUsageAdmin)
  • Project Identity and Access Management (IAM) Admin (roles/resourcemanager.projectIamAdmin) or Service Account Admin (roles/iam.serviceAccountAdmin)
  • Artifact Registry Administrator (roles/artifactregistry.admin)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Onboarding request

Image Builder is in Preview. To onboard your Cloud de Confiance project for the image customization pipeline, submit this access request form or contact your Cloud de Confiance account representative.

Enable APIs

Image Builder requires that you enable the Compute Engine, Cloud Build, Artifact Registry, Service Usage, and Resource Manager APIs. To enable the APIs by using the Cloud de Confiance console or the Google Cloud CLI, select one of the following tabs:

Console

Enable the Compute Engine, Cloud Build, Artifact Registry, Service Usage, and Cloud Resource Manager APIs.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

gcloud

Enable the Compute Engine, Cloud Build, Artifact Registry, Service Usage, and Cloud Resource Manager APIs:

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles. 

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

Configure Image Builder service account

The Image Builder orchestrator runs using a user-managed service account. When you run an image build pipeline, Cloud Build attaches this service account to temporary worker VM and test VM instances to perform customization and validation actions. This service account needs the following roles:

  • Compute Admin (roles/compute.admin): manages VM instances, persistent disks, and guest OS images.
  • Service Account User (roles/iam.serviceAccountUser): allows Cloud Build to attach the service account to the ephemeral worker and test VM instances.
  • Storage Admin (roles/storage.admin): reads and writes temporary build artifacts and logs in the Cloud Storage workdir staging bucket.
  • Logging Log Writer (roles/logging.logWriter): writes execution logs to Cloud Logging.
  • Service Usage Viewer (roles/serviceusage.serviceUsageViewer): checks project service states during pipeline execution.
  • Cloud Build Editor (roles/cloudbuild.builds.editor): triggers and runs Cloud Build jobs and exports images.
  • (Optional) Artifact Registry Admin (roles/artifactregistry.admin): uploads generated OS image tar files to Artifact Registry.

You can use an existing service account or create a new dedicated service account for your build pipeline. To create a new dedicated service account and grant the required roles by using either the Cloud de Confiance console or the gcloud CLI, select one of the following tabs:

Console

    Ensure that you have the Create Service Accounts IAM role (roles/iam.serviceAccountCreator) and the Project IAM Admin role (roles/resourcemanager.projectIamAdmin). Learn how to grant roles.

  1. In the Cloud de Confiance console, go to the Create service account page.

    Go to Create service account
  2. Select your project.

  3. In the Service account name field, enter a name. The Cloud de Confiance console fills in the Service account ID field based on this name.

    In the Service account description field, enter a description. For example, Service account for quickstart.

  4. Click Create and continue.

  5. Grant the following roles to the service account: Compute Engine > Compute Admin, Service Accounts > Service Account User, Cloud Storage > Storage Admin, Cloud Logging > Logs Writer, Service Usage > Service Usage Viewer, Cloud Build > Cloud Build Editor, Artifact Registry > Artifact Registry Admin.

    To grant a role, find the Select a role list, then select the role.

    To grant additional roles, click Add another role and add each additional role.

  6. Click Continue.

  7. In the Service account users role field, enter the identifier for the principal that will attach the service account to other resources, such as Compute Engine instances.

    This is typically the identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies.

  8. Click Done to finish creating the service account.

gcloud

  1. Create a service account for your build pipeline:

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

  2. Grant the required roles (roles/compute.admin, roles/iam.serviceAccountUser, roles/storage.admin, roles/logging.logWriter, roles/serviceusage.serviceUsageViewer, and roles/cloudbuild.builds.editor) to your service account:

    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. Optional: Grant the optional role (roles/artifactregistry.admin) to your service account:

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

Replace the following:

  • SERVICE_ACCOUNT_NAME: the name of the build service account to create. For example, custom-builder-sa.
  • PROJECT_ID: your Cloud de Confiance project ID.
  • SERVICE_ACCOUNT_EMAIL: the email address of your build service account.

Configure trusted image organization policy

Because Image Builder internally uses standard Compute Engine image import and export tools during build execution, your project's trusted image policy (compute.trustedImageProjects) must explicitly allow images from the following projects:

  • projects/compute-image-import
  • projects/compute-image-tools

If your organization policy restricts these projects, the image export phase fails.

To update your organization policy:

  1. In your organization policy for the compute.trustedImageProjects constraint, add projects/compute-image-import and projects/compute-image-tools to your list of allowed publishers.
  2. For detailed instructions on configuring organization policy constraints, see Setting up trusted image policies and Export a custom image to Cloud Storage.

Configure Artifact Registry

To store and manage your custom OS images, security metadata, and SLSA build provenance attestations, you must set up a generic repository in Artifact Registry. Storing your images in Artifact Registry lets you maintain a secure, immutable record of published images.

When you configure an Artifact Registry destination, Image Builder performs the following steps:

  • Exports the finalized VM boot disk as a standard tar file (.tar.gz).
  • Uploads the tar file to your generic repository in Artifact Registry.
  • Generates and signs SLSA build provenance attestations for the artifact to link it to the source metadata.
  • Registers the production-ready Compute Engine image with Compute Engine by using the Artifact Registry tar file URI as the template source.

To configure a generic Artifact Registry, complete the following tasks:

  1. Ensure the service account that is used to run the Image Builder pipeline has the Artifact Registry Admin role (roles/artifactregistry.admin) on the repository or project level. For detailed instructions, see Configure Image Builder service account.

  2. Create a repository of format generic. To create your repository, run the gcloud artifacts repositories create command:

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

    Replace the following placeholders:

    • REPOSITORY_NAME: a name for your generic repository. For example, custom-os-images.
    • REPOSITORY_LOCATION: a supported region. For example, us-central1.

What's next