Troubleshoot Cloud Run with SSH

SSH lets you establish a secure, interactive shell connection to your running container instances. This provides direct access to the container's file system and runtime environment, enabling you to inspect system resources, verify configurations, and troubleshoot.

SSH for Cloud Run uses the following services to secure connections:

Identity-Aware Proxy TCP forwarding proxies SSH connections, so requests must pass authentication and authorization checks before they reach your container. You can extend IAP access policies with context-aware access to restrict access based on attributes such as IP address and end-user device.
OS Login uses SSH certificate authentication to authenticate users. When you connect, the gcloud CLI mints a short-lived SSH certificate for you that expires after five minutes. The certificate is validated inside your container. Google checks IAM permissions for every login attempt.

SSH for Cloud Run automatically adds the required Google-managed binaries, including sshd and the binaries that validate your certificate, to your container's file system. These binaries are only accessible for the duration of the SSH session and are removed once the session ends. Existing SSH configurations, including /etc/passwd entries, are ignored by Cloud Run SSH in favor of Google-managed configurations.

Third-party open source copyright notices for Google-managed SSH dependencies are mounted inside your container when an SSH session is established at the following path: /usr/share/licenses/google_ssh/THIRD_PARTY_NOTICES.

SSH sessions and service instances

When you connect to a service using SSH, note the following:

If no instance of the service is running, Cloud Run starts a new instance for the SSH session.
Cloud Run aims to keep the service instance active for the duration of the SSH session. You are billed for the instance as usual while it is active.

Limitations

The following limitations apply to SSH:

SSH sessions last for a maximum of 24 hours. After 24 hours, the session is disconnected and you must reconnect.
IAP disconnects SSH sessions after one hour of inactivity. For more information, see IAP TCP forwarding known limitations.
SSH is only available for services that run on Cloud Run's second generation environment and Cloud Run instances.
When using SSH, host keys in the image are overwritten. The keys remain overwritten after the SSH session ends, until the service instance is restarted.
Windows: PuTTY is not supported. Use the OpenSSH client.
Extra care should be taken to secure your container when using SSH. Consider security best practices such as running application code as a non-root user.

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.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Run Admin API, Cloud Resource Manager API, Identity-Aware Proxy API, and Cloud OS Login APIs:

  gcloud services enable run.googleapis.com \
      cloudresourcemanager.googleapis.com \
      iap.googleapis.com \
      oslogin.googleapis.com

Install and initialize the gcloud CLI.
Update components:
```
gcloud components update
```
Windows: Ensure the OpenSSH client is installed.
OpenSSH Client is typically installed by default on Windows 10 and later. If it is not installed, you can install it by running the following command in PowerShell as an Administrator:
```
Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0
```
For more information, see Install OpenSSH.
Review the Cloud Run pricing page. To generate a cost estimate based on your projected usage, use the pricing calculator. SSH bills for network egress bytes. You are also billed as usual for the instance while it is kept active for an SSH session.
If your project uses VPC Service Controls (VPC-SC), note that the tunneling process checks iaptunnel.googleapis.com as the service name, rather than run.googleapis.com.

Required roles

To get the permissions that you need to complete these steps, ask your administrator to grant you the following IAM roles:

Service Account User (roles/iam.serviceAccountUser) on the service account
Cloud Run SSH Root Access (roles/run.sshRoot) on the service
Cloud Run Viewer (roles/run.viewer) on the service
IAP-secured Tunnel User (roles/iap.tunnelResourceAccessor) on the service
Cloud Run Developer (roles/run.developer) on the service
Logs View Accessor (roles/logging.viewAccessor) on the project
Browser (roles/browser) on the project
Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) on the project
IAP Policy Admin (roles/iap.admin) on the project for IAP management operations

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

If you aren't a member of the organization that the project is part of, Cloud Run blocks the SSH access. To gain SSH access, add the role, roles/compute.osLoginExternalUser or by using a custom role with the compute.oslogin.updateExternalUser permission.

You can grant the IAP-secured Tunnel User role at the project level, to restrict this role for a specific Cloud Run service or instance, run the following command:

For a specific service

gcloud beta iap tcp add-iam-policy-binding \
    --resource-type=cloud-run \
    --service=SERVICE \
    --region=REGION \
    --member=MEMBER \
    --role=roles/iap.tunnelResourceAccessor

Replace the following:

SERVICE: the name of your service.
REGION: the region that your service is deployed in.
MEMBER: the identity to grant access to.

For a specific instance

gcloud beta iap tcp add-iam-policy-binding \
    --resource-type=cloud-run \
    --instance=INSTANCE \
    --region=REGION \
    --member=MEMBER \
    --role=roles/iap.tunnelResourceAccessor

Replace the following:

INSTANCE: the name of your instance.
REGION: the region that your service is deployed in.
MEMBER: the identity to grant access to.

To grant the roles/iap.tunnelResourceAccessor at the project and region level, see Configure IAP access policies.

Use SSH with Cloud Run services

Configure service-level SSH access and connect to the service using SSH.

Configure service-level SSH access

You can allow inspect access on a specific service using the gcloud CLI or YAML:

gcloud

To enable access on an existing service, use the following command:

gcloud beta run services update SERVICE --ssh

You can also allow inspect access on a service by using the --ssh flag when deploying the service.

YAML

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
```
The following example contains the YAML configuration:
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  labels:
    cloud.googleapis.com/location: REGION
  annotations:
    run.googleapis.com/ssh-enabled: "true"
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    spec:
      containers:
        image: IMAGE_URL
```
Replace the following:
- SERVICE: the name of your Cloud Run service.
- REGION: the Google Cloud region—for example, us-central1.
- IMAGE_URL: 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 follows the format of LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
Create or update the service using the following command:
```
gcloud run services replace service.yaml
```
The gcloud run services replace command defaults to using service.yaml file if present.

You can disable SSH access on a per-service basis using the gcloud CLI or YAML:

gcloud

To disable access on the service, use the following command:

gcloud beta run services update SERVICE --no-ssh

YAML

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
```
The following example contains the YAML configuration:
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  labels:
    cloud.googleapis.com/location: REGION
  annotations:
    run.googleapis.com/ssh-enabled: "false"
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    spec:
      containers:
        image: IMAGE_URL
```
Replace the following:
- SERVICE: the name of your Cloud Run service.
- REGION: the Google Cloud region—for example, us-central1.
- IMAGE_URL: 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 follows the format of LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
Create or update the service using the following command:
```
gcloud run services replace service.yaml
```
The gcloud run services replace command defaults to using service.yaml file if present.

Connect to the service with SSH

To connect to a service by using SSH, use the gcloud CLI:

To connect to a service by using SSH, use the following Google Cloud CLI command:

  gcloud beta run services ssh SERVICE --region=REGION --project=PROJECT_ID

Replace the following:

SERVICE: the name of your service.
REGION: the region that your service is deployed in.
PROJECT_ID: the Google Cloud project ID.

If you are prompted to enter a passphrase for the SSH key, you can leave it empty. However, if you enter a passphrase, make sure you use the same passphrase for any subsequent SSH sessions from the same workspace.

When the SSH session is successfully completed, Cloud Run displays the following message:
```
Project: PROJECT_ID
Region: REGION
Service: SERVICE
Revision: REVISION
Instance: INSTANCE_ID
Container: CONTAINER
Image: IMAGE
```
To end your SSH session, type exit. Any changes you made on the container persist for as long as the container is kept alive. Exiting the session does not restart or kill the container.

Specify a service instance

To connect to a specific service instance by using SSH, use the Google Cloud CLI.

To connect to a Cloud Run service instance by using SSH, use the following Google Cloud CLI command:

  gcloud beta run services ssh SERVICE --region=REGION --project=PROJECT_ID --instance=INSTANCE_ID

Replace the following:

SERVICE: the name of your service.
REGION: the region that your service is deployed in.
PROJECT_ID: the Google Cloud project ID.
INSTANCE_ID: the instance ID. To find the service instance ID, go to the Logs page in the Observability section. The instance ID is located in the labels field for a log entry. You can't find the instance ID if you terminate the specific instance before connecting to it.

Specify a revision

To connect to a specific revision by using SSH, use the Google Cloud CLI.

To connect to a Cloud Run service revision by using SSH, use the following Google Cloud CLI command:

  gcloud beta run services ssh SERVICE --region=REGION --project=PROJECT_ID --revision=REVISION

Replace the following:

SERVICE: the name of your service.
REGION: the region that your service is deployed in.
PROJECT_ID: the Google Cloud project ID.
REVISION: the name of the revision.

Use SSH with Cloud Run instances

Configure instance-level SSH access and connect to the instance using SSH.

Configure instance-level SSH access

SSH is enabled by default for instances.

You can disable SSH access on a per-instance basis using the gcloud CLI or YAML:

gcloud

To disable access on the instance, use the following command:

gcloud beta run instances update INSTANCE --no-ssh

YAML

If you are creating a new instance, skip this step. If you are updating an existing instance, download its YAML configuration:
```
gcloud beta run instances describe INSTANCE --format export > instance.yaml
```

The following example contains the YAML configuration:

apiVersion: run.googleapis.com/v1
kind: Instance
metadata:
  name: INSTANCE
  labels:
    cloud.googleapis.com/location: REGION
  annotations:
    run.googleapis.com/ssh-enabled: "false"
    run.googleapis.com/launch-stage: BETA
spec:
  containers:
    image: IMAGE_URL

Replace the following:

INSTANCE: the name of your Cloud Run instance.
REGION: the Google Cloud region—for example, us-central1.
IMAGE_URL: a reference to the container image, such as us-docker.pkg.dev/cloudrun/container/hello:latest.

Create or update the instance using the following command:
```
gcloud beta run instances replace instance.yaml
```

You can allow inspect access on a specific instance using the gcloud CLI or YAML.

gcloud

To enable access on an existing instance, use the following command:

gcloud beta run instances update INSTANCE --ssh

You can also allow inspect access on a instance by using the --ssh flag when deploying the instance.

YAML

If you are creating a new instance, skip this step. If you are updating an existing instance, download its YAML configuration:
```
gcloud beta run instances describe INSTANCE --format export > instance.yaml
```

The following example contains the YAML configuration:

apiVersion: run.googleapis.com/v1
kind: Instance
metadata:
  name: INSTANCE
  labels:
    cloud.googleapis.com/location: REGION
  annotations:
    run.googleapis.com/ssh-enabled: "true"
    run.googleapis.com/launch-stage: BETA
spec:
  containers:
    image: IMAGE_URL

Replace the following:

INSTANCE: the name of your Cloud Run instance.
REGION: the Google Cloud region—for example, us-central1.
IMAGE_URL: a reference to the container image, such as us-docker.pkg.dev/cloudrun/container/hello:latest.

Create or update the instance using the following command:
```
gcloud beta run instances replace instance.yaml
```

Connect to the instance with SSH

To connect to an instance by using SSH, use the following Google Cloud CLI command:

  gcloud beta run instances ssh INSTANCE --region=REGION --project=PROJECT_ID

Replace the following:

INSTANCE: the name of your instance.
REGION: the region that your service is deployed in.
PROJECT_ID: the Google Cloud project ID.

If you are prompted to enter a passphrase for the SSH key, you can leave it empty. However, if you enter a passphrase, make sure you use the same passphrase for any subsequent SSH sessions from the same workspace.

When the SSH session is successfully completed, Cloud Run displays the following message:

  Project: PROJECT_ID
  Region: REGION
  Instance: INSTANCE
  Revision: REVISION
  Container: CONTAINER
  Image: IMAGE

To end your SSH session, type exit.

Use the OpenSSH client to connect

To use your OpenSSH client to connect:

Run the gcloud beta run services ssh command on the target service. This initiates the SSH tunnel and generates the certificate.

Add the following to your SSH configuration:

Host cloud-run-ssh
    HostName cloud-run-default
    User root
    IdentityFile /Users/USER/.ssh/google_compute_engine
    CertificateFile /Users/USER/.ssh/google_compute_engine_cert/PROJECT_ID_REGION_SERVICE-cert.pub
    CheckHostIP no
    HashKnownHosts no
    HostKeyAlias cloud-run-default
    IdentitiesOnly yes
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null
    ProxyUseFdpass no
    ProxyCommand /usr/local/bin/python3 -S /Users/USER/google-cloud-sdk/lib/gcloud.py beta run start-iap-tunnel --project_number=PROJECT_NUMBER --project_id=PROJECT_ID --workload_type=service --deployment_name=SERVICE --region=REGION

Replace the following:

USER: the username on your local machine.
PROJECT_ID: the Google Cloud project ID.
PROJECT_NUMBER: the Google Cloud project number.
REGION: the region that your service is deployed in.
SERVICE: the name of your service.

If the gcloud CLI is installed in a different folder, you might need to update the location in the last line.

Run the following command:
```
ssh cloud-run-ssh
```

Your SSH certificate expires after five minutes. If you try to establish an SSH connection with your service after five minutes, you must rerun gcloud beta run services ssh to re-generate the certificate.

SSH Access Logs

To capture audit logs for SSH key management, you must enable audit logs for the Cloud OS Login API. See View OS Login audit logs. To access SSH logs of Cloud Run resources, you must have access to Cloud Audit Logs for that project.

The following example queries all Cloud Run services for the past day:

gcloud logging read '
  logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access" AND
  protoPayload.serviceName="oslogin.googleapis.com" AND
  protoPayload.request.instance:"run.googleapis.com"
' --project=PROJECT_ID \
  --freshness=1d \
  --format="table(timestamp, protoPayload.authenticationInfo.principalSubject:label=USER, protoPayload.request.instance:label=CLOUD_RUN_SERVICE)"

Secure and control SSH access

You can control who can use SSH and how it is restricted in your environment.

Disable SSH access with organization policies

To set an organization policy to disable SSH, use the custom constraint that restricts enabling SSH debugging access on Cloud Run services.

What's next

Learn more about troubleshooting Cloud Run issues.
Learn more about troubleshooting Cloud Run services.
Read about known issues in Cloud Run.

Troubleshoot Cloud Run with SSH Stay organized with collections Save and categorize content based on your preferences.

SSH sessions and service instances

Limitations

Before you begin

Required roles

For a specific service

For a specific instance

Use SSH with Cloud Run services

Configure service-level SSH access

gcloud

YAML

gcloud

YAML

Connect to the service with SSH

Specify a service instance

Specify a revision

Use SSH with Cloud Run instances

Configure instance-level SSH access

gcloud

YAML

gcloud

YAML

Connect to the instance with SSH

Use the OpenSSH client to connect

SSH Access Logs

Secure and control SSH access

Disable SSH access with organization policies

What's next

Troubleshoot Cloud Run with SSH