Quickstart: Build and deploy a C++ web app to Cloud Run

Quickstart: Build and deploy a C++ web app to Cloud Run

Learn how to use a single command to build and deploy a "Hello World" web application from a code sample to Google Cloud using Cloud Run.

By following the steps in this quickstart, Cloud Run automatically builds a Dockerfile for you when you deploy from source code.

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.

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.

Install the Google Cloud CLI.

Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

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

To initialize the gcloud CLI, run the following command:

gcloud init

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

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.

Install the Google Cloud CLI.

Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

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

To initialize the gcloud CLI, run the following command:

gcloud init

1. To set the default project for your Cloud Run service:

    gcloud config set project PROJECT_ID

   Replace PROJECT_ID with your Google Cloud project ID.

2. If you are under a domain restriction organization policy restricting unauthenticated invocations for your project, you will need to access your deployed service as described under Testing private services.

3. Enable the Cloud Run Admin API and the Cloud Build API:

   gcloud services enable run.googleapis.com \
       cloudbuild.googleapis.com

   After the Cloud Run Admin API is enabled, the Compute Engine default service account is automatically created.

4. Grant the Cloud Build service account the following IAM role.

   Click to view required roles for the Cloud Build service account

   Cloud Build automatically uses the Compute Engine default service account as the default Cloud Build service account to build your source code and Cloud Run resource, unless you override this behavior. For Cloud Build to build your sources, ask your administrator to grant Cloud Run Builder (roles/run.builder) to the Compute Engine default service account on your project:

     gcloud projects add-iam-policy-binding PROJECT_ID \
         --member=serviceAccount:[e-mail] \
         --role=roles/run.builder
     

   Replace PROJECT_NUMBER with your Google Cloud project number, and PROJECT_ID with your Google Cloud project ID. For detailed instructions on how to find your project ID, and project number, see Creating and managing projects.

   Granting the Cloud Run builder role to the Compute Engine default service account takes a couple of minutes to propagate.

   Note:

   The iam.automaticIamGrantsForDefaultServiceAccounts organization policy constraint prevents the Editor role from being automatically granted to default service accounts. If you created your organization after May 3, 2024, this constraint is enforced by default.

   We strongly recommend that you enforce this constraint to disable the automatic role grant. If you disable the automatic role grant, you must decide which roles to grant to the default service accounts, and then grant these roles yourself.

   If the default service account already has the Editor role, we recommend that you replace the Editor role with less permissive roles.To safely modify the service account's roles, use Policy Simulator to see the impact of the change, and then grant and revoke the appropriate roles.

5. Review Cloud Run pricing or estimate costs with the pricing calculator.

Write the sample application

To write an application in C++:

1. Create a new directory named helloworld-cpp and change directory into it:

   mkdir helloworld-cpp
   cd helloworld-cpp
   

2. Create a new file named CMakeLists.txt and paste the following code into it:

   cmake_minimum_required(VERSION 3.20)
   
   # Define the project name and where to report bugs.
   set(PACKAGE_BUGREPORT
       "https://github.com/GoogleCloudPlatform/cpp-samples/issues")
   project(cpp-samples-cloud-run-hello-world CXX)
   
   find_package(functions_framework_cpp REQUIRED)
   find_package(Threads)
   
   add_executable(cloud_run_hello cloud_run_hello.cc)
   target_compile_features(cloud_run_hello PRIVATE cxx_std_17)
   target_link_libraries(cloud_run_hello functions-framework-cpp::framework)
   
   include(GNUInstallDirs)
   install(TARGETS cloud_run_hello RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})

3. Create a new file named vcpkg.json and paste the following code into it:

   {
     "name": "cpp-samples-cloud-run-hello-world",
     "version-string": "unversioned",
     "homepage": "https://github.com/GoogleCloudPlatform/cpp-samples/",
     "description": [
       "Shows how to deploy a C++ application to Cloud Run."
     ],
     "dependencies": [
       "functions-framework-cpp"
     ]
   }
   

4. Create a new file named cloud_run_hello.cc and paste the following code into it:

   #include <google/cloud/functions/framework.h>
   #include <cstdlib>
   
   namespace gcf = ::google::cloud::functions;
   
   auto hello_world_http() {
     return gcf::MakeFunction([](gcf::HttpRequest const& /*request*/) {
       std::string greeting = "Hello ";
       auto const* target = std::getenv("TARGET");
       greeting += target == nullptr ? "World" : target;
       greeting += "\n";
   
       return gcf::HttpResponse{}
           .set_header("Content-Type", "text/plain")
           .set_payload(greeting);
     });
   }
   
   int main(int argc, char* argv[]) {
     return gcf::Run(argc, argv, hello_world_http());
   }
   

   This code creates a basic web server that listens on the port defined by the PORT environment variable.

5. Create a new file named Dockerfile in the same directory as the source files. The C++ Dockerfile starts the application listening on the port defined by the PORT environment variable:

   # We chose Alpine to build the image because it has good support for creating
   # statically-linked, small programs.
   FROM alpine:3.21 AS build
   
   # Install the typical development tools for C++, and
   # the base OS headers and libraries.
   RUN apk update && \
       apk add \
           build-base \
           cmake \
           curl \
           git \
           gcc \
           g++ \
           libc-dev \
           linux-headers \
           ninja \
           pkgconfig \
           tar \
           unzip \
           zip
   
   # Use `vcpkg`, a package manager for C++, to install
   WORKDIR /usr/local/vcpkg
   ENV VCPKG_FORCE_SYSTEM_BINARIES=1
   RUN curl -sSL "https://github.com/Microsoft/vcpkg/archive/2024.04.26.tar.gz" | \
       tar --strip-components=1 -zxf - \
       && ./bootstrap-vcpkg.sh -disableMetrics
   
   # Copy the source code to /v/source and compile it.
   COPY . /v/source
   WORKDIR /v/source
   
   # Run the CMake configuration step, setting the options to create
   # a statically linked C++ program
   RUN cmake -S/v/source -B/v/binary -GNinja \
       -DCMAKE_TOOLCHAIN_FILE=/usr/local/vcpkg/scripts/buildsystems/vcpkg.cmake \
       -DCMAKE_BUILD_TYPE=Release
   
   # Compile the binary and strip it to reduce its size.
   RUN cmake --build /v/binary
   RUN strip /v/binary/cloud_run_hello
   
   # Create the final deployment image, using `scratch` (the empty Docker image)
   # as the starting point. Effectively we create an image that only contains
   # our program.
   FROM scratch AS cloud-run-hello
   WORKDIR /r
   
   # Copy the program from the previously created stage and the shared libraries it
   # depends on.
   COPY --from=build /v/binary/cloud_run_hello /r
   COPY --from=build /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1
   COPY --from=build /usr/lib/libstdc++.so.6 /usr/lib/libstdc++.so.6
   COPY --from=build /usr/lib/libgcc_s.so.1 /usr/lib/libgcc_s.so.1
   
   # Make the program the entry point.
   ENTRYPOINT [ "/r/cloud_run_hello" ]

Your app is finished and ready to be deployed.

Deploy to Cloud Run from source

Important: This quickstart assumes that you have owner or editor roles in the project you are using for the quickstart. Otherwise, refer to the Cloud Run Source Developer role for the required permissions for deploying a Cloud Run resource from source.

Use Cloud Build to create an image from the source code, and then deploy it.

1. In the source directory, use Cloud Build to create a docker image for your service

   gcloud builds submit --machine-type=e2_highcpu_32 --tag gcr.io/PROJECT_ID/cloud-run-hello-world

2. Deploy the image using the following command:

   gcloud run deploy --image=gcr.io/PROJECT_ID/cloud-run-hello-world

   If prompted to enable the API, Reply y to enable.

   1. When you are prompted for the service name, press Enter to accept the default name, for example helloworld.

   2. If you are prompted to enable additional APIs on the project, for example, the Artifact Registry API, respond by pressing y.

   3. When you are prompted for region: select the region of your choice, for example europe-west1.

   4. If you are prompted to create a repository in the specified region, respond by pressing y.

   5. If you are prompted to allow public access: respond y. You might not see this prompt if there is a domain restriction organization policy that prevents it; for more details see the Before you begin section.

   Then wait a few moments until the deployment is complete. On success, the command line displays the service URL.

3. Visit your deployed service by opening the service URL in a web browser.

Success: You deployed a C++ web app to Cloud Run.

Cloud Run locations

Cloud Run is regional, which means the infrastructure that runs your Cloud Run services is located in a specific region and is managed by Google to be redundantly available across all the zones within that region.

Meeting your latency, availability, or durability requirements are primary factors for selecting the region where your Cloud Run services are run. You can generally select the region nearest to your users but you should consider the location of the other Google Cloud products that are used by your Cloud Run service. Using Google Cloud products together across multiple locations can affect your service's latency as well as cost.

Cloud Run is available in the following regions:

Subject to Tier 1 pricing

• asia-east1 (Taiwan)
• asia-northeast1 (Tokyo)
• asia-northeast2 (Osaka)
• asia-south1 (Mumbai, India)
• europe-north1 (Finland) Low CO₂
• europe-north2 (Stockholm) Low CO₂
• europe-southwest1 (Madrid) Low CO₂
• europe-west1 (Belgium) Low CO₂
• europe-west4 (Netherlands) Low CO₂
• europe-west8 (Milan)
• europe-west9 (Paris) Low CO₂
• me-west1 (Tel Aviv)
• northamerica-south1 (Mexico)
• us-central1 (Iowa) Low CO₂
• us-east1 (South Carolina)
• us-east4 (Northern Virginia)
• us-east5 (Columbus)
• us-south1 (Dallas) Low CO₂
• us-west1 (Oregon) Low CO₂

Subject to Tier 2 pricing

• africa-south1 (Johannesburg)
• asia-east2 (Hong Kong)
• asia-northeast3 (Seoul, South Korea)
• asia-southeast1 (Singapore)
• asia-southeast2 (Jakarta)
• asia-south2 (Delhi, India)
• australia-southeast1 (Sydney)
• australia-southeast2 (Melbourne)
• europe-central2 (Warsaw, Poland)
• europe-west10 (Berlin) Low CO₂
• europe-west12 (Turin)
• europe-west2 (London, UK) Low CO₂
• europe-west3 (Frankfurt, Germany)
• europe-west6 (Zurich, Switzerland) Low CO₂
• me-central1 (Doha)
• me-central2 (Dammam)
• northamerica-northeast1 (Montreal) Low CO₂
• northamerica-northeast2 (Toronto) Low CO₂
• southamerica-east1 (Sao Paulo, Brazil) Low CO₂
• southamerica-west1 (Santiago, Chile) Low CO₂
• us-west2 (Los Angeles)
• us-west3 (Salt Lake City)
• us-west4 (Las Vegas)

If you already created a Cloud Run service, you can view the region in the Cloud Run dashboard in the Google Cloud console.

OK

Clean up

To avoid additional charges to your Google Cloud account, delete all the resources you deployed with this quickstart.

Delete your repository

Cloud Run doesn't charge you when your deployed service isn't in use. However, you might still be charged for storing the container image in Artifact Registry. To delete Artifact Registry repositories, follow the steps in Delete repositories in the Artifact Registry documentation.

Delete your service

Cloud Run services don't incur costs until they receive requests. To delete your Cloud Run service, follow one of these steps:

Console

To delete a service:

1. In the Google Cloud console, go to Cloud Run:

   Go to Cloud Run

2. Locate the service you want to delete in the services list, and click its checkbox to select it.

3. Click Delete. This deletes all revisions of the service.

gcloud

To delete a service, run the following command:

gcloud run services delete SERVICE --region REGION

Replace the following:

• SERVICE: name of your service.
• REGION: Google Cloud region of the service.

Delete your test project

Deleting your Google Cloud project stops billing for all resources in that project. To release all Google Cloud resources in your project, follow these steps:

Caution: Deleting a project has the following effects:

• Everything in the project is deleted. If you used an existing project for the tasks in this document, when you delete it, you also delete any other work you've done in the project.
• Custom project IDs are lost. When you created this project, you might have created a custom project ID that you want to use in the future. To preserve the URLs that use the project ID, such as an appspot.com URL, delete selected resources inside the project instead of deleting the whole project.

If you plan to explore multiple architectures, tutorials, or quickstarts, reusing projects can help you avoid exceeding project quota limits.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

What's next

For more information on building a container from code source and pushing to a repository, see:

• Developing Cloud Run services
• Building Containers
• Test a Cloud Run service locally
• Deploying from source code