Deploy services using Compose

This page describes how to deploy services to Cloud Run using a file based on the Compose Specification.

You can deploy to Cloud Run with a Compose file in the following ways:

Using Compose to deploy to Cloud Run is ideal for development and simplifies the transition from your local environment to a cloud environment. It lets you maintain a consistent configuration format for both your local and deployed applications.

For managing production environments in an infrastructure-as-code (IaC) environment, we recommend using Terraform.

Limitations

  • Compose deployment deploys a single Cloud Run service with multiple containers.
  • Compose deployment translates only a subset of supported Cloud Run features.
  • Services created using Compose are set by default to max-instance = 1.
  • While it simplifies deployment, Cloud Run Compose deploy isn't a replacement for a comprehensive IAC strategy for production environments.

Supported features

When you deploy using a compose.yaml file, Cloud Run can automatically provision other Google Cloud resources as defined in your Compose file. If resources are required, Cloud Run prompts you for consent before creating them.

Cloud Run supports the following subset of Compose features:

Compose field Cloud Run mapping & description
services

Services map to individual containers in the deployed Cloud Run service.
volumes

Partially supported. Translates bind, volume, and tmpfs mounts into Cloud Run equivalents.
secrets

Supported.
configs

Supported.
build

Cloud Build builds the container using the build context, tagging and pushing to the cloud-run-source-deploy repository in Artifact Registry.
image

Deploys a prebuilt container image from a supported registry. Use if you have a prebuilt image. Only supports Docker Hub and Artifact Registry images. For custom images, you can push images to Artifact Registry and use them.
ports

A list of port mappings, such as 8080:8080, that determine the ingress container.
expose

A list of ports to expose but not publish, such as 3000, to ensure that dependent services have a port available for communication.
depends_on

Defines the container startup order. This ensures that any run-compose-listed service has a port defined by ports or expose so that other containers can communicate with it.
cpu_count / cpus

A hint used to set Cloud Run CPU and memory limits, automatically allocating resources according to the following logic:

  • <= 2 CPU: 1Gi Memory
  • <= 4 CPU: 2Gi Memory
  • > 4 CPU: 4Gi Memory
container_name

Sets the container's name for dependency resolution, defaulting to the service name if not specified.
environment

Passes environment variables to the corresponding container in Cloud Run.
command

Overrides the container's default command, declared by the container, by mapping to the args attribute in Cloud Run; for example, a Dockerfile's CMD instruction.
entrypoint

Supported.
env_file

Supported.
x-google-cloudrun:ingress-container

(Extension) Add this Google-specific extension to a service and set to true to mark as the ingress container that receives all external traffic.
x-google-cloudrun:volume-type: in-memory

(Extension) Add this Google-specific extension to a volume and set to in-memory instead of the default volume backed by Cloud Storage.

Volumes and configs mapped to Cloud Storage

If your compose.yaml file defines top-level volumes or configs, Cloud Run provisions a Cloud Storage bucket to manage this data. A single bucket is created per deployment, using folders to separate volumes and configs.

  • Named volumes: An empty folder corresponding to the volume name is created in the bucket.
  • Bind mounts: For bind mounts, Cloud Run uploads the contents of the local source directory to a folder in the bucket prior to deployment.
  • Configs: For each config defined with a file: source, Cloud Run uploads the contents of the local file to a folder in the bucket.

Required roles

During deployment, Cloud Run automatically grants the service identity of the deployed service the necessary roles to access provisioned resources:

  • Cloud Storage Bucket: roles/storage.objectUser
  • Secret Manager Secrets: roles/secretmanager.secretAccessor

Deploy services from container images with Compose

Define your services in a compose.yaml file and deploy them from existing container images. For more information, see Deploy container images.

Example: Single-service application

The following example shows a compose.yaml file for a web service that uses a prebuilt container image.

services:  web:  image: us-docker.pkg.dev/cloudrun/container/hello  ports:  - "8080:8080"

Deploy the services

  1. To deploy the services, run the gcloud beta run compose up command:

    gcloud beta run compose up compose.yaml

  2. Respond y to any prompts to install required components or to enable APIs.

  3. Optional: Make your service public if you want to allow unauthenticated access to the service.

    After deployment, the Cloud Run service URL is displayed. Copy this URL and paste it into your browser to view the running container. You can disable the default authentication from the Google Cloud console.

Communication between containers of the same instance

Cloud Run adds an entry to the /etc/hosts file in each container. This entry maps the service names to their internal IP addresses, which lets services communicate with each other using their service names.

Deploy from source with Compose

Define your services in a compose.yaml file and deploy them by building from source code. For more information, see Deploy services from source code.

Example: Single-service application

The following example shows a compose.yaml file for a web service that builds from source in the current directory.

services:  web:  build: .  ports:  - "8080:8080"

Deploy the services

  • In your project directory, create a compose.yaml file with your service definitions.

    1. To deploy the services, run the gcloud beta run compose up command:

      gcloud beta run compose up compose.yaml

    2. Respond y to any prompts to install required components or to enable APIs.

    3. Optional: Make your service public if you want to allow unauthenticated access to the service.

    After deployment, the Cloud Run service URL is displayed. Copy this URL and paste it into your browser to view the running container. You can disable the default authentication from the Google Cloud console.

Communication between containers of the same instance

Cloud Run adds an entry to the /etc/hosts file in each container. This entry maps the service names from your compose.yaml file to their internal IP addresses, which lets services communicate with each other using their service names.

What's next