How do I create a config file?

 

Creating a basic build configuration filebookmark_border

This page describes how to create a build configuration file that you can use to start a build on Cloud Build.

A build config file defines the fields that are needed for Cloud Build to perform your tasks. You'll need a build config file if you're starting builds using the gcloud command-line tool or build triggers. You can write the build config file using the YAML or the JSON syntax.

Before you begin

• Read Build Configuration Overview to understand all the fields you can include in a build config file.

Creating a build config

The following steps explain how to create a simple build config file. Each of the fields in the config file defines a part of the task you want to perform. The only required field in the build config file is the name field for a step; all other fields are optional.

Note: The example config file created in this page does not include all available fields. Build Configuration Overview explains all the fields that you can include in a build config file.

YAMLJSON

1. Create the build config file. In your project root directory, create a file named cloudbuild.yaml. This is your Cloud Build build config file.

2. Add the steps field. The steps section in the build config file contains the build steps that you want Cloud Build to perform.

   steps:
   

3. Add the first step. Under steps:, add a name field and point it to a container image to execute your task. Cloud Build and its developer community provides several container images with common tools and languages installed in them. You can use any of these images (also called Cloud Builders), or any publicly available image in a build step. For information on different types of container images you can use in a build step, see Cloud Builders.

   The following snippet shows a build step with a docker builder gcr.io/cloud-builders/docker, which is a container image running Docker.

   steps:
   - name: 'gcr.io/cloud-builders/docker'
   

4. Add step arguments. The args field of a step takes a list of arguments and passes them to the builder referenced by the name field. If the builder in the name field has an entrypoint, args in the list will be used to access that entrypoint. If the builder in the name field does not have an entrypoint, the first element in args will be used as the entrypoint.

   In the following example:

   • build is the entrypoint to the Docker cloud builder
   • -t is the Docker tag
   • gcr.io/my-project/my-image is the name of the image to be built

   • . is the location of the source code

     Note: . means that the source code is in the current working directory

     steps:
     - name: 'gcr.io/cloud-builders/docker'
       args: ['build', '-t', 'gcr.io/my-project/my-image', '.']
     

5. Include any additional fields for the step. You can add more fields to your build step such as environment variables and working directories, to configure your build steps. For a description of all the fields you can include in a build step, see Build steps.

   In the following example, the timeout field is included to specify that the docker step must be timed-out after 500s:

   steps:
   - name: 'gcr.io/cloud-builders/docker'
     args: ['build', '-t', 'gcr.io/my-project/my-image', '.']
     timeout: 500s
   

6. Add more steps. You can add any number of build steps to your build config file by including additional name fields and pointing them to cloud builders.

   The following snippet includes two more steps to the build config file:

   • a docker build step to invoke the docker push command, to push the image build in the previous step to Container Registry.

   • a kubectl build step to invoke the kubectl set image command, which deploys the image to a Kubernetes Engine cluster. The env field is included to specify the Compute Engine zone and Kubernetes Engine cluster.

     steps:
     - name: 'gcr.io/cloud-builders/docker'
       args: ['build', '-t', 'gcr.io/my-project/my-image', '.']
       timeout: 500s
     - name: 'gcr.io/cloud-builders/docker'
       args: ['push', 'gcr.io/my-project/my-image']
     - name: 'gcr.io/cloud-builders/kubectl'
       args: ['set', 'image', 'deployment/my-deployment', 'my-container=gcr.io/my-project/my-image']
       env:
       - 'CLOUDSDK_COMPUTE_ZONE=us-east4-b'
       - 'CLOUDSDK_CONTAINER_CLUSTER=my-cluster'
     

7. Include additional build configuration. You can configure the build further by including fields such as machineType and tags. For the complete list of fields you can include in the build config file see Build Configuration Overview.

   The following example adds the following fields for the build:

   • machineType that specifies the virtual machine size to run the build.
   • timeout that specifies the time after which the build will be timed out.

   • tags for annotating the build.

     steps:
     - name: 'gcr.io/cloud-builders/docker'
       args: ['build', '-t', 'gcr.io/my-project/my-image', '.']
       timeout: 500s
     - name: 'gcr.io/cloud-builders/docker'
       args: ['push', 'gcr.io/my-project/my-image']
     - name: 'gcr.io/cloud-builders/kubectl'
       args: ['set', 'image', 'deployment/my-deployment', 'my-container=gcr.io/my-project/my-image']
       env:
       - 'CLOUDSDK_COMPUTE_ZONE=us-east4-b'
       - 'CLOUDSDK_CONTAINER_CLUSTER=my-cluster'
     options:
         machineType: 'N1_HIGHCPU_8'
     timeout: 660s
     tags: ['mytag1', 'mytag2']
     

8. Store the built images and artifacts. If your build produces any container images, you can choose to store them in Container Registry. You can do this using the images field.

   The following example stores the image built in the docker step to Container Registry:

   steps:
   - name: 'gcr.io/cloud-builders/docker'
     args: ['build', '-t', 'gcr.io/my-project/my-image', '.']
     timeout: 500s
   - name: 'gcr.io/cloud-builders/docker'
     args: ['push', 'gcr.io/my-project/my-image']
   - name: 'gcr.io/cloud-builders/kubectl'
     args: ['set', 'image', 'deployment/my-deployment', 'my-container=gcr.io/my-project/my-image']
     env:
     - 'CLOUDSDK_COMPUTE_ZONE=us-east4-b'
     - 'CLOUDSDK_CONTAINER_CLUSTER=my-cluster'
   options:
       machineType: 'N1_HIGHCPU_8'
   timeout: 660s
   tags: ['mytag1', 'mytag2']
   images: ['gcr.io/my-project/myimage']
   

   If your build produces any non-container artifacts, you can store them in Cloud Storage using the artifacts field. For instructions on doing this, see Storing Images and Artifacts.

What's next

• Learn how to run your builds manually and using triggers using the build config file.
• Learn how to write build configs for including dependencies, and building, testing, and deploying artifacts.