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:

From a prebuilt container image.
From source code.

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

To deploy the services, run the gcloud beta run compose up command:
```
gcloud beta run compose up compose.yaml
```
Respond y to any prompts to install required components or to enable APIs.
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

Learn more about managing services.
Learn about setting up authentication.
Learn how to manage secrets.