Configure containers

This page describes how to configure the container port, entrypoint command and arguments for a Cloud Run service.

When Cloud Run starts a container, it runs the image's default entrypoint command and default command arguments. If you want to override the image's default entrypoint and command arguments, you can use the command and args fields in the container configuration. The command field specifies the actual command run by the container. The args field specifies the arguments passed to that command.

Note that you can have a maximum of 1000 arguments per container for each service.

Required roles

To get the permissions that you need to configure and deploy Cloud Run services, ask your administrator to grant you the following IAM roles:

For a list of IAM roles and permissions that are associated with Cloud Run, see Cloud Run IAM roles and Cloud Run IAM permissions. If your Cloud Run service interfaces with Google Cloud APIs, such as Cloud Client Libraries, see the service identity configuration guide. For more information about granting roles, see deployment permissions and manage access.

Configure the container port

Any configuration change leads to the creation of a new revision. Subsequent revisions will also automatically get this configuration setting unless you make explicit updates to change it.

For Cloud Run services, Cloud Run injects the PORT environment variable into the container. If you deploy multiple containers to a service, this is the ingress container. The container listens on the port defined by the PORT environment variable, rather than on a specific hardcoded port. If this isn't possible, configure listening to occur on the port that sends requests to the container. Note that port settings don't apply to Cloud Run jobs.

Console

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

    Go to Cloud Run

  2. Click Deploy container and select Service to configure a new service. If you are configuring an existing service, click the service, then click Edit and deploy new revision.

  3. If you are configuring a new service, fill out the initial service settings page, then click Container(s), volumes, networking, security to expand the service configuration page.

  4. Click the Container tab.

    image

    • Specify the port you want requests to be sent to, if not the default value of 8080. This also sets the PORT environment variable.
  5. Click Create or Deploy.

gcloud

You can update a service's port configuration using the following command:

gcloud run services update SERVICE --port PORT

Replace

  • SERVICE with the name of the service.
  • PORT with the port to send requests to. Note that the default port is 8080.

You can also configure ports during deployment using the command:

gcloud run deploy --image IMAGE_URL --port PORT

Replace IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL has the shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .

YAML

  1. If you are creating a new service, skip this step. If you are updating an existing service, download its YAML configuration:

    gcloud run services describe SERVICE --format export > service.yaml
  2. Update the containerPort: attribute:

    apiVersion: serving.knative.dev/v1
    kind: Service
    metadata:
      name: SERVICE
    spec:
      template:
        metadata:
          name: REVISION
        spec:
          containers:
          - image: IMAGE_URL
            ports:
            - containerPort: PORT
    

    Replace:

    • SERVICE with the name of your Cloud Run service
    • IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL has the shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
    • PORT with the port to send requests to
    • REVISION with a new revision name or delete it (if present). If you supply a new revision name, it must meet the following criteria:
      • Starts with SERVICE-
      • Contains only lowercase letters, numbers and -
      • Does not end with a -
      • Does not exceed 63 characters
      .
  3. Replace the service with its new configuration using the following command:

    gcloud run services replace service.yaml

Configure entrypoint and arguments

Any configuration change leads to the creation of a new revision. Subsequent revisions will also automatically get this configuration setting unless you make explicit updates to change it.

The specified container command and arguments override the default image ENTRYPOINT and CMD.

You can set entrypoint command and arguments using the Google Cloud console, the Google Cloud CLI, or using a YAML file when you create a new service or deploy a new revision:

Console

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

    Go to Cloud Run

  2. Click Deploy container and select Service to configure a new service. If you are configuring an existing service, click the service, then click Edit and deploy new revision.

  3. If you are configuring a new service, fill out the initial service settings page, then click Container(s), volumes, networking, security to expand the service configuration page.

  4. Click the Container tab.

    image

    • Specify the command you want the container to run, if not the command defined in your container, and optionally specify the arguments to the entrypoint command.
  5. Click Create or Deploy.

gcloud

To update the start command and arguments for an existing service:

gcloud run services update SERVICE --command COMMAND --args ARG1,ARG-N

Replace

  • COMMAND with the command that the container is to start up with if you are not using the default command.
  • ARG1 with the argument you are sending to the container command, use a comma delimited list for more than one argument.

To specify entrypoint and arguments during deployment of a new or existing service:

gcloud run deploy --image IMAGE_URL --command COMMAND --args ARG1,ARG-N

Replace IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL has the shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

To clear any entrypoint commands and arguments you have set (restore to container defaults), supply empty strings as follows:

gcloud run deploy --image IMAGE_URL --command "" --args ""

YAML

  1. If you are creating a new service, skip this step. If you are updating an existing service, download its YAML configuration:

    gcloud run services describe SERVICE --format export > service.yaml
  2. Update the command and args attributes:

    spec:
      containers:
      - image: IMAGE_URL
        command:
        - COMMAND
        args:
        - "ARG1"
        - "ARG-N"
    

    Replace

    • IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL has the shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • COMMAND with the command that the container is to start up with if you are not using the default command.
    • ARG1 with the argument you are sending to the container command. If you use multiple arguments, specify each on its own line, for example, as shown, ARG-N.
  3. Replace the service with its new configuration using the following command:

    gcloud run services replace service.yaml

Terraform

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

The following google_cloud_run_v2_service resource specifies a command and args. Replace /server with the command used to start your container, and add any necessary arguments to the args array.

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-service-containers"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"

      # Container "entry-point" command
      command = ["/server"]

      # Container "entry-point" args
      args = []
    }
  }
}

Use equals signs or commas in arguments

If you use equal signs in your arguments, supply these using the following format:

gcloud run deploy  \
  --args="--repo-allowlist=github.com/example/example_demo"

If your arguments use commas, refer to configuring environment variables for details on escaping those.

Configure container start order for sidecar deployments

To specify container start up order in a sidecar deployment, you use the container dependencies feature. You specify any containers that have dependencies and list the containers they depend on: those containers are started first. The containers that don't have any dependencies are always started first and concurrently.

You must use startup healthcheck probes if you want to use this feature successfully. The startup probe enables Cloud Run to inspect the health of a dependent container, making sure it passes successfully before it starts up the next container. If you don't use healthchecks, containers are started in the specified order even if containers they depend on fail to start.

Note that ingress containers have a default startup healthcheck probe.

You can use Google Cloud console, the Google Cloud CLI, or YAML to specify the startup order:

Console

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

    Go to Cloud Run

    • For an existing service, click the service in the list and select Edit and deploy new revision to display the revision deployment form.
    • For a new service, click Deploy container and select Service to display the Create service form.
  2. For a new service, specify the service name, ingress container URL, CPU allocation, ingress control, and authentication. In the Container(s), volumes, networking, security tab, do the following:

    1. Configure the ingress container.
    2. To add each of the other containers you are deploying, click Add container.
    3. For all containers except the ingress container, configure a startup healthcheck. Ingress containers have a default startup healthcheck.
    4. If a container needs other containers to start first before it can start, use the Container startup order menu to select the containers that must start first.
  3. For an existing service, follow these steps:

    1. For all containers except the ingress container, configure a startup healthcheck. Ingress containers have a default startup healthcheck.
    2. Each container is shown with its own Container startup order menu. If a container needs other containers to start first before it can start, use the Container startup order menu to select the containers that must start first.
  4. Finish any other required configurations, then click Create for a new service or Deploy for an existing service. Wait for the deployment to finish.

gcloud

Before using the Google Cloud CLI to specify startup order, you must configure a startup healthcheck for all containers except the ingress container. Ingress containers have a default startup healthcheck. You cannot configure healthchecks using the Google Cloud CLI.

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. To deploy multiple containers to a service with a specified startup order, run the command:

gcloud run deploy SERVICE \
     --container CONTAINER_1_NAME --image='INGRESS_IMAGE' --port='CONTAINER_PORT' \
     --container CONTAINER_2_NAME --image='SIDECAR_IMAGE' --depends-on=CONTAINER_1_NAME \
     --container CONTAINER_3_NAME --image='SIDECAR_IMAGE' --depends-on=CONTAINER_1_NAMECONTAINER_2_NAME
  • Replace SERVICE with the name of the service you are deploying to. You can omit this parameter entirely, but you will be prompted for the service name if you omit it.
  • Replace CONTAINER_PORT with the port where the ingress container listens for incoming requests. Unlike a single-container service, for a service containing sidecars, there is no default port for the ingress container. You must explicitly configure the container port for the ingress container and only one container can have the port exposed.
  • Replace INGRESS_IMAGE with a reference to the container image that should receive requests, for example, us-docker.pkg.dev/cloudrun/container/hello:latest.
  • Replace SIDECAR_IMAGE with a reference to the sidecar container image

    If you want to configure each container in the deploy command, supply each container's configuration after the container parameters.

YAML

  1. If you are creating a new service, skip this step. If you are updating an existing service, download its YAML configuration:

    gcloud run services describe SERVICE --format export > service.yaml
  2. Update the container-dependencies attribute:

    apiVersion: serving.knative.dev/v1
    kind: Service
    metadata:
      annotations:
      name: SERVICE
    spec:
      template:
        metadata:
          annotations:
            run.googleapis.com/container-dependencies: '{"CONTAINER1":["CONTAINER2"], "CONTAINER3":["CONTAINER1","CONTAINER2"]}'
    

    Replace

    • CONTAINER1 with the name of the first container that depends on one or more container. Note that you can set the container name in the YAML: Cloud Run will automatically generate a name if one isn't specified.
    • CONTAINER2 with the name of the container that must be started before CONTAINER1.
    • CONTAINER3 with the name of the second container that depends on one or more containers.

    In the example shown in the YAML snippet, CONTAINER2 is started first, CONTAINER1 is started second, and CONTAINER3 is started last.

  3. Replace the service with its new configuration using the following command:

    gcloud run services replace service.yaml

View container settings

To view the current container settings for your Cloud Run service:

Console

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

    Go to Cloud Run

  2. Click the service you are interested in to open the Service details page.

  3. Click the Revisions tab.

  4. In the details panel at the right, the container setting is listed under the Container tab.

gcloud

  1. Use the following command:

    gcloud run services describe SERVICE
  2. Locate the container setting in the returned configuration.