How to deploy a Docker image to Google Cloud Run?

Type Your Question

How to deploy a Docker image to Google Cloud Run?

Saturday, 1 March 2025

GOOGLE

Google Cloud Run is a fully managed compute platform that enables you to run stateless containers invocable via HTTP requests. It is serverless, meaning you don't need to manage servers. It automatically scales your containers based on incoming requests and scales down to zero when there is no traffic. Deploying a Docker image to Cloud Run is a straightforward process that unlocks significant scalability and operational benefits. This guide will walk you through the complete process, ensuring you can successfully deploy your containerized applications.

Prerequisites

Before we begin, ensure you have the following:

A Google Cloud Platform (GCP) account: If you don't have one, sign up for a free trial.
A GCP Project: Create a project within your GCP account to organize your resources.
The Google Cloud SDK (gcloud CLI) installed: This allows you to interact with your GCP resources from the command line. Refer to the official Google Cloud documentation for installation instructions.
Docker installed: You need Docker to build and run your container images locally.

Step 1: Setting up Your GCP Environment

First, you need to authenticate with your GCP account using the gcloud CLI:

gcloud auth login

This command will open a browser window where you can select your Google account and grant permissions to the gcloud CLI.

Next, configure the gcloud CLI to use your project:

gcloud config set project YOUR_PROJECT_ID

Replace YOUR_PROJECT_ID with the actual ID of your Google Cloud project.

Finally, configure your default compute region and zone (this is important for various GCP services, though Cloud Run itself is region-based):

gcloud config set compute/region YOUR_REGION
gcloud config set compute/zone YOUR_ZONE

Replace YOUR_REGION and YOUR_ZONE with your desired region (e.g., us-central1) and zone (e.g., us-central1-a). While these are important, for *Cloud Run*, you'll primarily define the region at deployment time. Different regions offer varying prices and service availability, so choose carefully based on your needs and audience. Common regions include us-central1, europe-west1, and asia-east1.

Enable the Cloud Run API and Container Registry API:

gcloud services enable run.googleapis.com containerregistry.googleapis.com

Step 2: Preparing Your Docker Image

This step involves building a Docker image for your application. If you already have an image, skip to Step 3.

Let's assume you have a simple Node.js application named app.js:

javascript
// app.js
const express = require('express');
const app = express();
const port = process.env.PORT || 8080;

app.get('/', (req, res) => {
res.send('Hello from Cloud Run!');
});

app.listen(port, () => {
console.log(App listening on port ${port});
});

You'll also need a package.json file:

json
// package.json
{
"name": "cloud-run-demo",
"version": "1.0.0",
"description": "A simple app for Cloud Run",
"main": "app.js",
"scripts": {
"start": "node app.js"
},
"dependencies": {
"express": "^4.17.1"
}
}

Now, create a Dockerfile:

dockerfile
# Use an official Node.js runtime as a parent image
FROM node:18-alpine

# Set the working directory in the container
WORKDIR /app

# Copy the package.json and package-lock.json files to the working directory
COPY package*.json ./

# Install any needed packages specified in package.json
RUN npm install

# Copy the rest of your application's source code from your host to your image filesystem.
COPY . .

# Make port 8080 available to the world outside this container
EXPOSE 8080

# Run app.js when the container launches
CMD [ "npm", "start" ]

Key improvements and explanations for the Dockerfile:

*Base Image:* node:18-alpine provides a minimal, production-ready Node.js environment. Using -alpine results in smaller image size.
*WORKDIR:* WORKDIR /app sets the working directory inside the container to /app, improving code organization and making subsequent commands cleaner.
*Caching Dependencies:* Copying package*.json first allows Docker to leverage caching effectively. When only the application code changes, Docker reuses the cached layer from the npm install command, significantly speeding up builds. Critically important for faster iteration and CI/CD.
*COPY . . :* Copies the current directory's contents into the /app folder of the container
*EXPOSE:* Exposes port 8080 to make it accessible to other containers and the host system.
*CMD:* CMD ["npm", "start"] defines the command to run when the container starts, leveraging the start script in package.json. It's an array, best practice per Docker docs.

Build the Docker image:

docker build -t gcr.io/YOUR_PROJECT_ID/cloud-run-image:latest .

Replace YOUR_PROJECT_ID with your GCP project ID. The -t flag tags the image, following the naming convention required for Google Container Registry. The :latest tag specifies the image version. It is generally advisable to use semantic versioning for image tags (e.g., 1.0.0) instead of latest for improved version control and rollback capabilities.

Step 3: Pushing the Image to Google Container Registry

Google Container Registry (GCR) is a private Docker registry within Google Cloud that stores your Docker images. Before pushing to GCR, configure Docker credentials to access your GCP account:

gcloud auth configure-docker

This command authenticates your Docker client with your Google Cloud credentials, allowing you to push images to your project's Container Registry.

Now, push the image to GCR:

docker push gcr.io/YOUR_PROJECT_ID/cloud-run-image:latest

Again, replace YOUR_PROJECT_ID with your project ID. This command uploads your newly built Docker image to Google Container Registry, making it available for Cloud Run to deploy.

Step 4: Deploying to Google Cloud Run

Deploying your Docker image to Cloud Run is remarkably simple. Use the following command:

gcloud run deploy cloud-run-service \
 --image gcr.io/YOUR_PROJECT_ID/cloud-run-image:latest \
 --platform managed \
 --region YOUR_REGION \
 --allow-unauthenticated

Let's break down the options:

* cloud run deploy cloud-run-service: Initiates the deployment to Cloud Run and names your service cloud-run-service. Choose a meaningful name.
* --image gcr.io/YOUR_PROJECT_ID/cloud-run-image:latest: Specifies the Docker image to deploy from Google Container Registry. Replace with your image URL.
* --platform managed: Indicates that you want to use the fully managed Cloud Run environment. There's also Cloud Run on GKE, which is Kubernetes based.
* --region YOUR_REGION: Specifies the region where your Cloud Run service will be deployed. Example: --region us-central1. Choose a region close to your users for lower latency.
* --allow-unauthenticated: Allows public, unauthenticated access to your service. Remove this if you want authentication. Cloud Run integrates tightly with Identity-Aware Proxy (IAP) for robust authentication.

During the deployment, you'll be prompted:

* Do you want to allow unauthenticated invocations to [cloud-run-service]? Select y to allow unauthenticated access (if you included --allow-unauthenticated) or n for authenticated access. If you choose authentication, you'll need to set up Identity-Aware Proxy (IAP) or similar.

The command will output the URL of your deployed Cloud Run service. This URL is where you can access your application.

Step 5: Accessing Your Deployed Application

Once the deployment is complete, the gcloud run deploy command will output the URL of your Cloud Run service. Open this URL in your browser to see your application running.

Best Practices for Cloud Run Deployments

* Use Small Base Images: Reduce your image size by using minimal base images (like alpine variants). Smaller images deploy faster.
* Leverage Docker Layer Caching: Structure your Dockerfile to take advantage of layer caching. Place dependencies installations before application code.
* Set Resource Limits: Configure resource limits (CPU and memory) for your Cloud Run service. This prevents services from consuming excessive resources and impacting other services. Use --cpu and --memory flags during deployment (e.g., --cpu 2, --memory 4Gi). Monitor CPU and Memory usage in Cloud Monitoring and adjust accordingly.
* Health Checks: While not explicitly configured with probes like in Kubernetes, ensure your application properly handles SIGTERM signals for graceful shutdowns, and restarts when it encounters an error. Cloud Run uses a HTTP health check against your endpoint.
* Logging and Monitoring: Cloud Run integrates seamlessly with Google Cloud Logging and Cloud Monitoring. Use these tools to monitor your application's performance, identify issues, and troubleshoot problems. Implement structured logging for better observability.
* Version Control: Use Git or a similar version control system to manage your application's code and Dockerfile.
* CI/CD Pipelines: Automate your deployment process with CI/CD pipelines (e.g., using Cloud Build, Jenkins, or GitLab CI). This ensures consistent and reliable deployments.
* Semantic Versioning: Use meaningful tags in your Docker images that follow a semantic versioning scheme, this assists in rolling back to the stable version during issue occurence on production release
* Use Service Accounts Always give your cloud run services the least amount of permissions possible through a secure service account with only enough IAM permissions
* Use Regional Networking When deploying resources into multiple regions that need connectivity consider the option to create private services access for Google's VPC.

Example CI/CD pipeline with Cloud Build

# cloudbuild.yaml
steps:
 - name: "gcr.io/cloud-builders/docker"
 args:
 [
 "build",
 "-t",
 "gcr.io/$PROJECT_ID/cloud-run-image:$SHORT_SHA",
 ".",
 ]
 - name: "gcr.io/cloud-builders/docker"
 args: ["push", "gcr.io/$PROJECT_ID/cloud-run-image:$SHORT_SHA"]
 - name: "gcr.io/google-cloud-sdk/cloudsdk"
 entrypoint: gcloud
 args:
 [
 "run",
 "deploy",
 "cloud-run-service",
 "--image",
 "gcr.io/$PROJECT_ID/cloud-run-image:$SHORT_SHA",
 "--platform",
 "managed",
 "--region",
 "us-central1",
 "--allow-unauthenticated",
 ]
images: ["gcr.io/$PROJECT_ID/cloud-run-image:$SHORT_SHA"]

This example cloudbuild.yaml defines a simple pipeline: it builds your Docker image, tags it with the git SHA, pushes it to Container Registry, and then deploys it to Cloud Run. To create the build trigger navigate to cloudbuild from your google cloud platform. Select the "triggers" and fill in required repositories with your preferred integration strategy.

Troubleshooting

* Image Pull Errors: Verify that your Docker image exists in Google Container Registry and that the Cloud Run service has permission to access it. Check the service account permissions.
* Port Configuration: Ensure your application is listening on port 8080 by default, or you have configured the PORT environment variable correctly.
* Deployment Errors: Examine the logs in Cloud Logging for any errors during deployment. The gcloud run deploy command will also provide error messages.
* Application Crashes: Monitor your application's health and logs to identify the root cause of crashes. Enable debugging in your application.

Conclusion

Deploying Docker images to Google Cloud Run is a straightforward process that provides scalability, serverless operation, and efficient resource utilization. By following these steps and adhering to best practices, you can easily deploy and manage your containerized applications on Google Cloud Platform. Remember to always consult the official Google Cloud Run documentation for the most up-to-date information and best practices. Cloud Run represents a key tool in the modern cloud-native landscape, empowering developers to focus on their application's logic and rapidly innovate.