Creating the secure image pipeline

This page explains how you can set up the Secure image pipeline to automate the generation of base container images.

Overview

The Secure image pipeline is an open source tool that sets up a framework of Google Cloud projects, resources, and a GitHub repository that you can use to create and maintain customized and secure base images. You can consume the images from Google Cloud projects.

The following image illustrates the framework of resources created by secure image pipeline:

Once you set up the pipeline, it creates the following resources:

• A GitHub repository hosting the source code for container images.

• Three Google Cloud projects: build project, staging project, and verified project. Anytime an image is updated in the image repository, Cloud Build triggers in the build project builds, signs, and pushes the updated image to the Artifact Registry repository in the staging project. When the image in the staging project is manually verified, the pipeline pushes the image to the verified project.

Costs

Secure image pipeline uses the following Google Cloud products.

• Cloud Build
• Artifact Registry
• Artifact Analysis
• Binary Authorization
• Pub/Sub
• Cloud Run
• Cloud Run functions

Use the Pricing Calculator to generate a cost estimate based on your projected usage.

Before you begin

• You'll need a Google Cloud organization to use the secure image pipeline. Google Workspace and Cloud Identity customers can create a Google Cloud organization:

  • Google Workspace: Sign up for Google Workspace.
  • Cloud Identity: Sign up for Cloud Identity.

  For more information on Google Cloud organization, see Quickstart using organizations.

• Install Terraform 0.14.10.

• If you don't have one already, create an account on GitHub.

  • If you have two-factor authentication set up on GitHub create a personal access token to use in place of a GitHub password with the command line.

Required IAM permissions

The user setting up the secure image pipeline requires the roles/organization.admin and roles/billing.admin Identity and Access Management roles for the Google Cloud organization. For instructions on granting IAM roles, see Granting, changing, and revoking access.

Setting up the secure image pipeline

The Secure image pipeline GitHub repository contains the script to automate the generation of base images.

To set up the secure image pipeline:

1. Clone the Secure image pipeline GitHub repository to your local machine:

   git clone https://github.com/GoogleCloudPlatform/secure-image-pipeline
   

2. Navigate to the secure-image-pipeline directory:

   cd secure-image-pipeline/
   

3. Copy env.sh.tmpl to env.sh:

   cp env.sh.tmpl env.sh
   

4. Open env.sh in your desired editor.

5. Edit the following values:

   • PARENT_ORGANIZATION: Enter the ID of your Google Cloud organization. The secure image pipeline script uses this organization to generate Google Cloud projects and base images.
   • BASEIMGFCT_PROJECT: Enter a string using which the script constructs the project IDs of the projects it creates. The string must be of 6 to 30 lowercase letters, digits, or hyphens. It must start with a letter, and cannot have a trailing hyphen. For example, if you specify foo, the script creates three projects with IDs foo-builder, foo-stage, and foo-verified.
   • BASEIMGFCT_BUCKET: Enter a name for a Cloud Storage bucket that the script creates to store the Terraform automation code. Make sure the name meets the bucket naming requirements.
   • BASEIMGFCT_REGION: Enter the name of the region to use or use the default value.
   • BILLING_ACCOUNT: Enter the billing account associated with the organization.
   • GITHUB_TOKEN: Enter your GitHub personal access token. The script uses this token to create a GitHub repository that contains the source code for the base images.

6. Run the setup script:

   ./setup.sh
   

7. Enter the following GitHub account information when prompted:

   1. The name of your GitHub organization.

   2. Your GitHub email address.

   3. Your GitHub username.

   4. Grant the script permission to create a new project to store base images.

   5. Enter "y".

   This operation takes a few minutes to run. When it finishes, it displays the message Link your GitHub repositories and press any key to continue.

8. Press any key to continue.

   The script opens a new Google Cloud console browser window to link your GitHub repository with your Google Cloud project.

9. Switch to the Google Cloud console browser window.

10. In the Manage your GitHub app installations pop-up, select your GitHub account.

11. Click Add another project.

12. In the Select a project drop-down, select the project of the format YOUR_PROJECT_NAME-builder.

13. Select the consent checkbox, and click Next.

14. In the list of repositories, select the repository named baseimgfact-[some number]-containers and click Connect (1) repositories.

15. In the Create push trigger page, click Skip. The script creates the push trigger for you automatically.

16. Click Done.

17. Switch back to the terminal.

18. Press any key to continue.

The script takes a few minutes to complete execution.

Resources created by the secure image pipeline

When the setup script completes execution, it creates the following resources:

GitHub:

• A repository named baseimgfct-[some number]-containers that contains the source code used for creating container images. The setup script seeds this repository with simple Dockerfiles, one for each of the popular Linux distributions.
• Deploy keys - separate write-access deploy keys for the repository.

Google Cloud projects:

• A Google Cloud project named YOUR_PROJECT_NAME-builder that contains resources to build and push an image to the staging project anytime the source code is updated in the GitHub repository.

  This project contains the Cloud Build triggers that invoke builds when a pull request or merge is performed in the main branch in baseimgfct-[some number]-containers. A pull request builds and pushed the images to the staging project. A merge builds and pushes the images to the verified project.

  IAM permissions for YOUR_PROJECT_NAME-builder: We recommend that you grant access to this project only to team members who are expected to make changes to the pipeline. For instructions on granting access to projects, see Granting, changing, and revoking access.

• A Google Cloud project named YOUR_PROJECT_NAME-stage that is used to stage images for a manual review before the images are released to the verified project. This project contains the following resources:

  • An Artifact Registry Docker repository that contains the built container images.
  • Cloud Run functions for each image in the project, which triggers a rebuild of the image anytime a new fix for a known vulnerability is found.
  • Pub/Sub topics that are used to execute the Cloud Run functionss.
  • An instance of the Voucher server that runs as a Cloud Run deployment. The Voucher server checks the image with a list of security policies requirements. You can either use the default policy requirements that come with the pipeline or specify a customized security policy. After the security checks pass, the Voucher server creates an attestation for the image using Binary Authorization. This attested image, also called a signed image is then pushed to the verified project.

  IAM permissions for YOUR_PROJECT_NAME-stage: We recommend that you only grant access for this project to developers who are allowed to read the staged images from Artifact Registry. For instructions on granting access to projects see, Granting, changing, and revoking access.

• A Google Cloud project named YOUR_PROJECT_NAME-verified. This project contains the final signed images that have been manually reviewed.

What's next?

• Learn how to use the base image pipeline.
• Learn how to specify a customized security policy.