Building and Debugging Locally

This page explains how to use Container Builder on your local machine. Using the local builder, you can:

  • Iterate builds more quickly on your local machine.
  • Use a dry run to lint your config file.

Before you begin

  1. Install and initialize the Google Cloud SDK.

  2. Install Docker. It's a best practice to use the same Docker version as Container Builder.

  3. You need source code to build, a build config file for your build, and access from your local machine to any tools and dependencies required by your build steps.

  4. If your build needs access to a private registry, install and configure the Docker credential helper for Container Builder by running the commands:

    gcloud components install docker-credential-gcr
    
    docker-credential-gcr configure-docker
    

Install the local builder

The local builder is a component of the Google Cloud SDK's gcloud tool. To install the local builder, run the following command:

gcloud components install container-builder-local

After the local builder is installed, to view:

  • The command line help, run the command:

    container-builder-local --help
    
  • The installed version of the local builder, run the command:

    container-builder-local --version
    

Build locally

Warning: Run one build at a time on your local machine. Running multiple builds in parallel will cause the local builder to fail.

To build locally, run the following command:

container-builder-local --config=[BUILD_CONFIG] --dryrun=false --push [SOURCE_CODE]

Where:

  • [BUILD_CONFIG] is the path to and the name of your config file.
    • For example, if your config file is in the working directory and named cloudbuild.json, use the flag --config=cloudbuild.json.
    • The default value is cloudbuild.yaml, so if your config file is in the working directory and named cloudbuild.yaml, you do not need to add this flag.
  • [SOURCE_CODE] is the path to your source code.
    • As with Container Builder, you can use . for the source if the source code is in your current working directory.
    • If your build does not need source code, use the flag --no-source in place of [SOURCE_CODE].
  • --dryrun=false allows your build to run. The flag --dryrun is true by default. Running with the default value lints your config file but does not run build commands. You need to explicitly set --dryrun=false to execute your build.
  • --push will push the resulting images to the repository that's defined by the field images in the config file. By default, images are built but are not pushed to the registry.

After the build is complete, the images created are available on your local machine through Docker. If you added --push to the build command, they are available in the specified repository.

Preserve intermediary artifacts

During a build, intermediary artifacts are placed in a directory called workspace. By default, the builder deletes the workspace and its contents at the end of a build.

To run a build and to preserve the artifacts from the workspace, run the command:

container-builder-local --config=[BUILD_CONFIG] --dryrun=false --write-workspace=[LOCAL_DIRECTORY_PATH] [SOURCE_CODE]

Where:

  • [BUILD_CONFIG] is the path to your config file,
  • [SOURCE_CODE] is the path to your source code, and
  • [LOCAL_DIRECTORY_PATH] is the local directory where you want the workspace to be stored on your local machine.

Preserving the workspace allows you to:

  • Analyze intermediary artifacts when debugging a build.
  • Access a build result, such as a binary, that the builder created in the workspace.

Use substitutions in your build

To use substitutions in your build, use the flag --substitutions along with the key=value pair that you want to substitute.

For example,

container-builder-local --config=[BUILD_CONFIG] --dryrun=false --substitutions _KEY=value,_FOO=foo [SOURCE_CODE]

Where:

  • [BUILD_CONFIG] is the path to your config file,
  • [SOURCE_CODE] is the path to your source code, and
  • In this example, _KEY will be substituted with value, and _FOO will be substituted with foo.

For details about substitutions, including required syntax, see Substitutions.

Debug your build locally

To debug your build, you can:

Local builds run with the permissions available at execution time on your local host. In Container Builder, the build step executes with the permissions of your project's service account. If you are debugging a permissions issue, be sure to set up your permissions to match those of the Container Builder service account so that the local builds are in an environment as close as possible to the Container Builder environment.

Verify the build with a dry run

A dry run of the build will lint the config file, and will produce errors if it detects any issues. A dry run does not execute the build, so you can verify the config file without the overhead of running the build. Using the local builder is the only way to do a dry run of a build.

  1. Do a dry run of the build by using the command:

    container-builder-local --config=[BUILD_CONFIG] [SOURCE_CODE]
    

    Where:

    • [BUILD_CONFIG] is the path to your config file,
    • [SOURCE_CODE] is the path to your source code.
  2. Review any error messages and fix any issues in your config file.

Restrictions and limitations

  • The local builder can build on only Linux or macOS.
  • The local builder runs one build at a time on a given host. Running multiple builds in parallel will cause the local builder to fail.

Differences between the local builder and Container Builder

The local builder is designed to mimic Container Builder. A build that runs successfully on the local builder should run with the same behavior on Container Builder.

Differences that do exist between the two builders include:

  • The local builder executes on your local machine, Container Builder executes on Google Cloud Platform.
  • To run the build, the local builder uses your personal account, and the Container Builder uses the cloudbuild service account [PROJECT_ID]@cloudbuild.gserviceaccount.com. If you set any permissions on your personal account for the local builder, you may need to replicate these permissions on the cloudbuild service account. For details, see Setting Service Account Permissions.
  • The version of Docker used by the builders could be different. During execution, the local builder prints a warning whenever the Docker version installed is different from the one used in Container Builder. It's a best practice to use the same Docker version as the one used by Container Builder.

What's next?

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Container Builder