Chapter 2. Uploading images to GCP with image builder

With image builder you can build a gce image, provide credentials for your user or GCP service account, and then upload the gce image directly to the GCP environment.

2.1. Uploading a gce image to GCP using the CLI

Follow the procedure to set up a configuration file with credentials to upload your gce image to GCP.

Prerequisites

  • You have a user or service account Google credentials to upload images to GCP. The account associated with the credentials must have at least the following IAM roles assigned:

    • roles/storage.admin - to create and delete storage objects
    • roles/compute.storageAdmin - to import a VM image to Compute Engine.
  • You have an existing GCP bucket.

Procedure

  1. Using a text editor, create a gcp-config.toml configuration file with the following content:

    provider = "gcp"
    
    [settings]
    bucket = "GCP_BUCKET"
    region = "GCP_STORAGE_REGION"
    object = "OBJECT_KEY"
    credentials = "GCP_CREDENTIALS"

    Where:

    • GCP_BUCKET points to an existing bucket. It is used to store the intermediate storage object of the image which is being uploaded.
    • GCP_STORAGE_REGION is both a regular Google storage region and, a dual or multi region.
    • OBJECT_KEY is the name of an intermediate storage object. It must not exist before the upload, and it is deleted when the upload process is done. If the object name does not end with .tar.gz, the extension is automatically added to the object name.
    • GCP_CREDENTIALS is a Base64-encoded scheme of the credentials JSON file downloaded from GCP. The credentials determine which project the GCP uploads the image to.

      Note

      Specifying GCP_CREDENTIALS in the gcp-config.toml is optional if you use a different mechanism to authenticate with GCP. For more details on different ways to authenticate with GCP, see Authentication with GCP.

  2. Create a compose with an additional image name and cloud provider profile:

    $ sudo composer-cli compose start BLUEPRINT-NAME gce IMAGE_KEY gcp-config.toml

    Note: The image build, upload, and cloud registration processes can take up to ten minutes to complete.

Verification

  • Verify that the image status is FINISHED:

    $ sudo composer-cli compose status

2.2. Authenticating with GCP

You can use several different types of credentials with image builder to authenticate with GCP. If image builder configuration is set to authenticate with GCP using multiple sets of credentials, it uses the credentials in the following order of preference:

  1. Credentials specified with the composer-cli command in the configuration file.
  2. Credentials configured in the osbuild-composer worker configuration.
  3. Application Default Credentials from the Google GCP SDK library, which tries to automatically find a way to authenticate using the following options:

    1. If the GOOGLE_APPLICATION_CREDENTIALS environment variable is set, Application Default Credentials tries to load and use credentials from the file pointed to by the variable.
    2. Application Default Credentials tries to authenticate using the service account attached to the resource that is running the code. For example, Google Compute Engine VM.

      Note

      You must use the GCP credentials to determine which GCP project to upload the image to. Therefore, unless you want to upload all of your images to the same GCP project, you always must specify the credentials in the gcp-config.toml configuration file with the composer-cli command.

2.2.1. Specifying credentials with the composer-cli command

You can specify GCP authentication credentials in the provided upload target configuration gcp-config.toml. Use a Base64-encoded scheme of the Google account credentials JSON file to save time.

Procedure

  • In the provided upload target configuration gcp-config.toml, set the credentials:

    provider = "gcp"
    
    [settings]
    provider = "gcp"
    
    [settings]
    ...
    credentials = "GCP_CREDENTIALS"
  • To get the encoded content of the Google account credentials file with the path stored in GOOGLE_APPLICATION_CREDENTIALS environment variable, run the following command:

    $ base64 -w 0 "${GOOGLE_APPLICATION_CREDENTIALS}"

2.2.2. Specifying credentials in the osbuild-composer worker configuration

You can configure GCP authentication credentials to be used for GCP globally for all image builds. This way, if you want to import images to the same GCP project, you can use the same credentials for all image uploads to GCP.

Procedure

  • In the /etc/osbuild-worker/osbuild-worker.toml worker configuration, set the following credential value:

    [gcp]
    credentials = "PATH_TO_GCP_ACCOUNT_CREDENTIALS"