Prepare your environment

Linux

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

For information about access to this release, see the access request page.

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

• Submit an onboarding request
• Enable required Cloud APIs
• Configure Image Builder service account
• Configure trusted image organization policy
• Configure Artifact Registry

Before you begin

• If you haven't already, set up authentication. Authentication verifies your identity for access to Google Cloud 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 Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  1. Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command:

     gcloud init

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
  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.

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  For more information, see Authenticate for using REST in the Google Cloud 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 Google Cloud project for the image customization pipeline, submit this access request form or contact your Google Cloud 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 Google Cloud 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 Google Cloud 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 Google Cloud 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 Google Cloud 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.

   Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later.
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 email address for a Google Account.

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 Google Cloud 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

• Create and manage pipelines using the Google Cloud console.
• Create and manage pipelines programmatically.
• Learn how to define customization recipes in the Customization recipe schema.
• Review the Build configuration (cloudbuild.yaml) file structure.