GCP Onboarding

Onboarding a Google Cloud Platform (GCP) project to Klarity ImageFactory allows you to automate the creation of custom Compute Engine images. This guide explains how to set up a Service Account with the necessary permissions and how to provide the credentials to the platform.

Prerequisites

Before you begin, ensure you have the following:

1. A GCP Project where the images will be built and stored.
2. Permissions to create Service Accounts and assign IAM roles within that project.
3. The Compute Engine API enabled in your project.

Required Credentials

ImageFactory requires a full Service Account JSON key to authenticate. This key contains several fields that must be provided exactly as they appear in the downloaded file:

• type
• project_id
• private_key_id
• private_key
• client_email
• client_id
• auth_uri
• token_uri
• auth_provider_x509_cert_url
• client_x509_cert_url

Required GCP Permissions

The Service Account must be granted specific IAM roles to manage the image building lifecycle. Assign the following roles to the Service Account at the project level:

Role	Purpose
Compute Image User	Allows the platform to use base images for building.
Compute Instance Admin (v1)	Allows the platform to create and manage build instances.
Storage Object Admin	Allows the platform to manage temporary artifacts in Cloud Storage.

Step-by-Step Guide

Using the Onboarding Script (Recommended)

The ImageFactory UI provides a ready-made shell script that automates the GCP setup. This is the fastest way to onboard.

1. Navigate to Cloud Credentials in the sidebar and click Add Credentials.
2. Select GCP as the provider.
3. Enter your Project ID.
4. In step 2, you'll see the onboarding script displayed with a copy button. Run this script in Google Cloud Shell. The script automatically:
   • Creates a Service Account with the required IAM roles
   • Generates a JSON key for the Service Account
   • Outputs the credential values you need
5. Copy the output values into the corresponding fields in the ImageFactory form.

tip

The Cloud Shell script handles Service Account creation, IAM role assignment, and key generation automatically. You don't need to perform any manual setup.

Manual Setup

If you prefer to set up resources manually, follow these steps:

1. Create a Service Account

In the GCP Console, navigate to IAM & Admin > Service Accounts. Click "Create Service Account", give it a name like imagefactory-builder, and click "Create and Continue".

2. Assign IAM Roles

In the "Grant this service account access to project" section, add the three roles mentioned above: Compute Image User, Compute Instance Admin, and Storage Object Admin. Click "Continue" and then "Done".

3. Generate a JSON Key

Find your new service account in the list, click the three dots under "Actions", and select "Manage keys". Click "Add Key" > "Create new key", select "JSON", and click "Create". This will download the JSON file to your computer.

4. Add Account in ImageFactory

Open the downloaded JSON file and copy its contents. Use the ImageFactory console or API to add the account, pasting the JSON data into the appropriate configuration field.

Advanced Features

Service Account Sharing

If you need to share the Service Account across multiple projects or use a specific identity for distribution, you can use the gcpServiceAccount property in your configuration. This allows for more complex multi-project setups.

Custom Image Naming

ImageFactory allows you to define custom names for your GCP images. Note the following constraints for image names:

• Length must be between 3 and 45 characters.
• Must consist of lowercase letters, numbers, and dashes.
• A timestamp suffix is automatically appended to ensure uniqueness across builds.

Adding Your GCP Project

To onboard your GCP project, navigate to Cloud Credentials in the sidebar and click Add Credentials. Select GCP as the provider and use the provided onboarding script in Google Cloud Shell for the quickest setup.

For a detailed walkthrough of the onboarding interface, see the Cloud Credentials guide.

Via API

You can also onboard a GCP project programmatically using the GraphQL API:

mutation CreateGcpAccount {
  createAccount(input: {
    name: "Production-GCP"
    provider: GCP
    gcpConfig: {
      credentials: {
        type: "service_account"
        project_id: "your-project-id"
        private_key_id: "your-private-key-id"
        private_key: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
        client_email: "imagefactory-builder@your-project-id.iam.gserviceaccount.com"
        client_id: "your-client-id"
        auth_uri: "https://accounts.google.com/o/oauth2/auth"
        token_uri: "https://oauth2.googleapis.com/token"
        auth_provider_x509_cert_url: "https://www.googleapis.com/oauth2/v1/certs"
        client_x509_cert_url: "https://www.googleapis.com/robot/v1/metadata/x509/..."
      }
    }
  }) {
    id
    status
  }
}

Verifying the Connection

After submitting the credentials, ImageFactory will verify that it can authenticate and that the required permissions are present. Check the account status in the dashboard. If the status is ACCESS_SUCCESS, your GCP project is ready for use.