Learn how to get started with Cloud Build by building a Docker imageand pushing the image to Artifact Registry. Artifact Registry provides a singlelocation for managing private packages and Docker container images.

You will first build the image using aDockerfile, which is the Dockerconfiguration file, and then build the same image using theCloud Build configuration file.

Guide me

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Build, Compute Engine and Artifact Registry APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

Toinitialize the gcloud CLI, run the following command:

gcloudinit

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Build, Compute Engine and Artifact Registry APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

Toinitialize the gcloud CLI, run the following command:

gcloudinit

If you've already installed Google Cloud CLI previously, make sure you have thelatest available version by runninggcloud components update.

1. Make sure that you have the following role or roles on the project: Artifact Registry Administrator, Cloud Build Editor, Logs Viewer, Service Account User, Service Usage Admin, Storage Bucket Viewer, Storage Object Creator

   Check for the roles

   1. In the Google Cloud console, go to theIAM page.

      Go to IAM
   2. Select the project.

   3. In thePrincipal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

   4. For all rows that specify or include you, check theRole column to see whether the list of roles includes the required roles.

   Grant the roles

   1. In the Google Cloud console, go to theIAM page.

      Go to IAM
   2. Select the project.
   3. Clickperson_addGrant access.

   4. In theNew principals field, enter your user identifier. This is typically the email address for a Google Account.

   5. ClickSelect a role, then search for the role.
   6. To grant additional roles, clickaddAdd another role and add each additional role.
   7. ClickSave.

Prepare source files to build

You'll need some sample source code to package into a container image. In this section,you'll create a shell script and aDockerfile. ADockerfile is a textdocument that contains instructions for Docker to build an image.

1. Open a terminal window.

2. Create a new directory namedquickstart-docker and navigate into it:

   mkdir quickstart-dockercd quickstart-docker

3. Create a file namedquickstart.sh with the following contents:

   #!/bin/shecho"Hello, world! The time is$(date)."

4. Create a file namedDockerfile with the following contents:

   FROMalpineCOPYquickstart.sh/CMD["/quickstart.sh"]

5. In the terminal window, run the following command to makequickstart.sh executable:

   chmod +x quickstart.sh

Create a Docker repository in Artifact Registry

1. Use thegcloud artifacts repositories createcommand to create a Docker repository namedquickstart-docker-repo in thelocationus-west2 with the description "Docker repository":

   gcloudartifactsrepositoriescreatequickstart-docker-repo--repository-format=docker\--location=us-west2--description="Docker repository"

2. Verify that your repository was created:

   gcloudartifactsrepositorieslist

   The list of displayed repositories should includequickstart-docker-repo.

   Artifact Registry uses anaming convention to identifyrepositories and images. For example, when you interact with Docker imagesstored in Artifact Registry in theus-west2 region, you useus-west2-docker.pkg.dev as the registry hostname in your commands.

Build an image using a Dockerfile

Use thegcloud builds submit command tobuild a Docker image using aDockerfile. You don't require a separateCloud Build config file.

1. Get your Google Cloud project ID by running the following command:

   gcloud config get-value project

2. Run the following command from the directory containingquickstart.sh andDockerfile:

   gcloudbuildssubmit--region=us-west2--tagus-west2-docker.pkg.dev/PROJECT_ID/quickstart-docker-repo/quickstart-image:tag1

   Note: If your project ID contains a colon, replace the colon with a forward slash.

   After the build is complete, the output should be similar to the following:

   DONE------------------------------------------------------------------------------------------------------------------------------------IDCREATE_TIMEDURATIONSOURCEIMAGESSTATUS545cb89c-f7a4-4652-8f63-579ac974be2e2020-11-05T18:16:04+00:0016Sgs://gcb-docs-project_cloudbuild/source/1604600163.528729-b70741b0f2d0449d8635aa22893258fe.tgzus-west2-docker.pkg.dev/gcb-docs-project/quickstart-docker-repo/quickstart-image:tag1SUCCESS

You've just built a Docker image namedquickstart-image using aDockerfileand pushed the image to Artifact Registry.

Build an image using a build config file

In this section you use a Cloud Build config file to build the sameDocker image built in the previous steps. The build config file instructsCloud Build to perform tasks based on your specifications.

1. In the same directory that containsquickstart.sh and theDockerfile,create a file namedcloudbuild.yaml with the following contents. This file isyour build config file. At build time, Cloud Build automaticallyreplaces$PROJECT_ID with your project ID.

   steps:-name:'gcr.io/cloud-builders/docker'script:|docker build -t us-west2-docker.pkg.dev/$PROJECT_ID/quickstart-docker-repo/quickstart-image:tag1 .automapSubstitutions:trueimages:-'us-west2-docker.pkg.dev/$PROJECT_ID/quickstart-docker-repo/quickstart-image:tag1'

2. Start the build by running the following command:

   gcloudbuildssubmit--region=us-west2--configcloudbuild.yaml

   After the build is complete, the output should be similar to the following:

   DONE------------------------------------------------------------------------------------------------------------------------------------IDCREATE_TIMEDURATIONSOURCEIMAGESSTATUS046ddd31-3670-4771-9336-8919e7098b112020-11-05T18:24:02+00:0015Sgs://gcb-docs-project_cloudbuild/source/1604600641.576884-8153be22c94d438aa86c78abf11403eb.tgzus-west2-docker.pkg.dev/gcb-docs-project/quickstart-docker-repo/quickstart-image:tag1SUCCESS

You've just builtquickstart-image using the build config file and pushed theimage to Artifact Registry.

View build details

1. Open the Cloud Build page in the Google Cloud console.

   Open the Cloud Build page

2. If necessary, select your project and clickOpen.

   You will see theBuild history page:

   

3. If necessary, selectus-west2in theRegion drop-down menu to viewbuilds in that region.

   There will be two builds listed, one for each of the builds you executed inthis quickstart.

4. Click one of the builds.

   You will see theBuild details page.

5. To view the artifacts of your build, underBuild Summary, clickBuild artifacts.

   You should see output similar to the following:

   

   You can download your build log and view your image details inArtifact Registry from this page.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used on this page, follow these steps.

1. Open the Artifact Registry page in the Google Cloud console.

   Open the Artifact Registry page

2. Select your project and clickOpen.

3. Selectquickstart-docker-repo.

4. ClickDelete.

You have now deleted the repository that you created as part of this quickstart.

What's next

• Learn how torun a Docker image.
• Learn how tocreate a basic build configfile.
• Learn how todeploy using Cloud Build.
• Learn how tobuild Node.js applications.
• Learn how tobuild Java applications.
• Learn how tobuild Go applications.