> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/continuous-delivery/3.0/use-deployments/overview-3/google-cloud-run-infrastructure.md).

# Google Cloud Run infrastructure

Create Harness environments and Google Cloud Run infrastructure definitions to target your GCP project for deployment.

An infrastructure definition links your logical Harness environment to the actual physical resources: the GCP project and region where Harness deploys your Cloud Run service. You create the environment and infrastructure definition at **Deployments > Environments** and reuse them across pipelines and stages.

***

### What you will learn <a href="#what-you-will-learn" id="what-you-will-learn"></a>

* How to create a Harness environment for Google Cloud Run.
* How to configure an infrastructure definition with a GCP connector and region.
* The GCP authentication methods supported and the IAM permissions required.
* How to reuse infrastructure definitions across pipelines and stages.

***

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

* **A GCP project** with Cloud Run enabled.
* **A Harness GCP connector** configured with one of the supported authentication methods. Go to [GCP authentication](#gcp-authentication) to configure one.
* **IAM permissions** on the GCP service account or identity. Go to [Cloud Run permissions](#cloud-run-permissions) to review the minimum required permissions.

***

### Create an environment <a href="#create-an-environment" id="create-an-environment"></a>

You can create an environment from **Deployments > Environments**, or inline during stage configuration at step 3 (**Configure environments**) of the stage wizard.

When configuring a stage, step 3 presents two options:

* **Environment**: deploy to one or more environments.
* **Environment group**: deploy to a pre-configured group of environments.

Select **Environment**, then use the **Create or select environment** field to create a new environment or pick an existing one. Enable the **Deploy environments in parallel** toggle if you are deploying to multiple environments and want them to run concurrently.

To create a standalone environment:

1. Go to **Deployments**, expand the drop-down, and select **Environments**.
2. Click **+ New Environment**.
3. Enter a name and select an environment type: **Pre-Production** or **Production**.
4. Click **Save**.

***

### Create an infrastructure definition <a href="#create-an-infrastructure-definition" id="create-an-infrastructure-definition"></a>

Infrastructure definitions live inside an environment. Each definition targets a specific GCP project and region.

1. Open the environment and select the **Infrastructure Definitions** tab.
2. Click **+ Create Infrastructure**.
3. In the **Create Infrastructure** dialog, select **Google Cloud Run** and click **Save**.
4. Configure the following in the infrastructure definition form:

#### Top-level fields <a href="#top-level-fields" id="top-level-fields"></a>

| Field       | Description                                                                        |
| ----------- | ---------------------------------------------------------------------------------- |
| **Name**    | The infrastructure definition name. Harness auto-suggests an ID that you can edit. |
| **Storage** | **Inline** (Harness stores the definition) or a Git repository.                    |

#### Cluster details: Provisioner configuration <a href="#cluster-details" id="cluster-details"></a>

Expand **Cluster Details** and then **Provisioner Configuration** to configure the target GCP environment:

| Field         | Required | Description                                                                                                                                                                                                          |
| ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Connector** | Yes      | A Harness GCP connector that authenticates with GCP. Click **Create or select connector** to create a new one or pick an existing connector.                                                                         |
| **Project**   | Yes      | The GCP project to deploy to. This is a searchable dropdown populated from the connector. You can select any project the connector has access to, including projects different from the connector's default project. |
| **Region**    | Yes      | The region where Cloud Run will run the service (for example, `us-central1` or `asia`).                                                                                                                              |

{% hint style="info" %}
**Cross-project deployments**

The **Project** field supports cross-project deployments. If your GCP connector has permissions across multiple projects, the dropdown lists all accessible projects. Select the target project regardless of which project the connector was originally created for.
{% endhint %}

#### Simultaneous deployments <a href="#simultaneous-deployments" id="simultaneous-deployments"></a>

| Field                        | Default | Description                                                                                                                                                                            |
| ---------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Simultaneous deployments** | `False` | By default, Harness queues deployments to the same infrastructure to avoid conflicts. Set to `True` to allow multiple deployments to run concurrently against the same infrastructure. |

#### Additional sections <a href="#additional-sections" id="additional-sections"></a>

* **Scope to Specific Services**: restrict this infrastructure definition so it is only available to selected services.
* **Metadata**: add tags and other metadata to the infrastructure definition.

5. Click **Save**.

***

### GCP authentication <a href="#gcp-authentication" id="gcp-authentication"></a>

Harness supports three authentication methods for GCP connectors used with Cloud Run deployments.

#### Service account <a href="#service-account" id="service-account"></a>

Provide a GCP service account JSON key. Harness activates the key using `gcloud auth activate-service-account` before running deployment commands.

To create a GCP connector with a service account key:

1. Go to **Account Settings > Connectors** and click **+ New Connector**.
2. Select **GCP** under Cloud Providers.
3. Select **Specify credentials here** and upload or paste the service account JSON key.
4. Complete the connector setup and click **Save and Continue**.

#### OIDC <a href="#oidc" id="oidc"></a>

Use OpenID Connect to authenticate without storing a service account key in Harness. Harness exchanges an OIDC token for GCP credentials using a Workload Identity Pool.

To create a GCP OIDC connector:

1. Go to **Account Settings > Connectors** and click **+ New Connector**.
2. Select **GCP** under Cloud Providers.
3. Select **Use OpenID Connect (OIDC)**.
4. Provide the Workload Identity Pool ID, Workload Provider ID, GCP project ID, and the service account email to impersonate.
5. Complete the connector setup and click **Save and Continue**.

The OIDC service account must have the `iam.workloadIdentityPools.createCredentialConfig` permission and `iam.serviceAccounts.actAs` on the Cloud Run service identity.

#### Inherit from delegate <a href="#inherit-from-delegate" id="inherit-from-delegate"></a>

Use the GCP credentials of the node where the delegate is running. This is suited for delegates deployed on GKE with Workload Identity or on GCE with an attached service account. At runtime, Harness runs `gcloud auth list --filter=status:ACTIVE` to identify the active service account on the delegate node, then uses Application Default Credentials for all subsequent operations.

To create a GCP connector that inherits from the delegate:

1. Go to **Account Settings > Connectors** and click **+ New Connector**.
2. Select **GCP** under Cloud Providers.
3. Select **Use the credentials of a specific Harness Delegate**.
4. Select the delegate tag and complete the connector setup.

{% hint style="warning" %}
**Plugin version for Inherit from Delegate**

When using Inherit from Delegate, use plugin image version `1.0.4` or later. Earlier versions fail when the `gcloud` CLI outputs extra messages (update notifications, survey prompts) alongside the account list. Go to [Google Cloud Run services](/continuous-delivery/3.0/use-deployments/overview-3/google-cloud-run-services.md#container-plugin-image) for the current image reference.
{% endhint %}

***

### Cloud Run permissions <a href="#cloud-run-permissions" id="cloud-run-permissions"></a>

The following IAM permissions are required on the GCP service account or identity used for deployment.

#### Minimum permissions <a href="#minimum-permissions" id="minimum-permissions"></a>

The table below lists the minimum permissions required for each operation:

| Operation                                    | Permissions required                                                                                                                       |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| List and describe services                   | `run.services.list`, `run.services.get`                                                                                                    |
| Deploy or update a service                   | `run.services.create`, `run.services.update`                                                                                               |
| Delete a service (first-deployment rollback) | `run.services.delete`                                                                                                                      |
| Manage jobs                                  | `run.jobs.create`, `run.jobs.update`, `run.jobs.get`, `run.jobs.run`                                                                       |
| Invoke a service                             | `run.routes.invoke`                                                                                                                        |
| Instance sync and post-deploy verification   | `monitoring.timeSeries.list`, `monitoring.metricDescriptors.list`                                                                          |
| View configuration                           | `run.configurations.list`, `run.configurations.get`                                                                                        |
| Manage IAM policies                          | `resourcemanager.projects.getIamPolicy`, `resourcemanager.projects.setIamPolicy`                                                           |
| OIDC authentication                          | `iam.workloadIdentityPools.createCredentialConfig`                                                                                         |
| Service account key authentication           | `iam.serviceAccounts.get`, `iam.serviceAccounts.signBlob`                                                                                  |
| Service account impersonation                | `iam.serviceAccounts.actAs` (required on the Cloud Run service identity, even when the deployer and service identity are the same account) |

#### Predefined roles <a href="#predefined-roles" id="predefined-roles"></a>

The following predefined roles can be used instead of individual permissions:

| Role                                                                     | Purpose                                                                                                                                                         |
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `roles/run.admin` (Cloud Run Admin)                                      | Full administrative access to manage Cloud Run services. Required for deploying services.                                                                       |
| `roles/iam.serviceAccountUser` (Service Account User)                    | Permission to use service accounts for running Cloud Run services. Required even when the deployer and Cloud Run service identity are the same account.         |
| `roles/logging.viewer` (Logging Viewer)                                  | Access to logs for debugging Cloud Run services.                                                                                                                |
| `roles/monitoring.viewer` (Monitoring Viewer)                            | Required for post-deploy instance verification. Without this role, the deploy step succeeds but then fails with a `PermissionDenied` error during verification. |
| `roles/iam.workloadIdentityPoolAdmin` (IAM Workload Identity Pool Admin) | Required for OIDC authentication setup.                                                                                                                         |

***

### Next steps <a href="#next-steps" id="next-steps"></a>

* Go to [Deployment strategies](https://github.com/harness/harness-developer-hub/tree/main/3k-docs/delivery/continuous-delivery/use-deployments/google-cloud-run/google-cloud-run-deployment-strategies/README.md) to configure your pipeline execution strategy.
* Go to [Google Cloud Run services](/continuous-delivery/3.0/use-deployments/overview-3/google-cloud-run-services.md) to configure the service manifest and artifact source.

{% @harness-feedback/feedback %}