> 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/harness-ai/use-harness-platform/connectors/cloud-providers/connect-to-google-cloud-platform-gcp/gcs-connector-settings-reference.md).
# Google Cloud Platform (GCP) connector settings reference
Settings and permissions for the GCP connector.
Use a Harness Google Cloud Platform (GCP) connector to integrate GCP with Harness. Use GCP with Harness to obtain artifacts, communicate with GCP services, provision infrastructure, deploy microservices, and manage other workloads.
You can use the GCP connector to connect to Kubernetes clusters in GCP. You can also use the [platform-agnostic Kubernetes Cluster connector](/harness-ai/use-harness-platform/connectors/cloud-providers/add-a-kubernetes-cluster-connector/kubernetes-cluster-connector-settings-reference.md).
This topic describes the roles and permissions required for each GCP service, GCP connector settings, and advanced GKE authentication settings.
***
## What you will learn from this topic
* The [role requirements](#role-requirements) for GKE, GCS, GCR, GAR, and Stackdriver.
* How to [install the gke-gcloud-auth-plugin](#install-the-gke-gcloud-auth-plugin-on-the-delegate) on a delegate for GKE authentication using Kubernetes 1.22 and later.
* The [GCP connector settings](#gcp-connector-settings), including credential options and OIDC configuration.
***
## Role requirements
Certain roles are required in your GCP account, depending on how you are using the GCP connector.
### GKE/Kubernetes role requirements
If you use the GCP connector to connect to GKE, the GCP service account used for any credentials requires:
* **Kubernetes Engine Developer** (`roles/container.clusterAdmin`)
* **Storage Object Viewer** (`roles/storage.objectViewer`)
For instructions on adding roles to your service account, go to the Google documentation on [Granting Roles to Service Accounts](https://cloud.google.com/iam/docs/granting-roles-to-service-accounts). For more information about GCP roles, go to the GCP documentation on [Understanding Roles](https://cloud.google.com/iam/docs/understanding-roles?_ga=2.123080387.-954998919.1531518087#curated_roles).
Alternately, you can use a service account that has only the **Storage Object Viewer** permission needed to query GCR, and then use either an in-cluster Kubernetes delegate or a direct [Kubernetes Cluster Connector](/harness-ai/use-harness-platform/connectors/cloud-providers/add-a-kubernetes-cluster-connector/kubernetes-cluster-connector-settings-reference.md) with the Kubernetes service account token for performing deployment.
{% hint style="warning" %}
Harness supports GKE 1.19 and later. If you use a version prior to GKE 1.19, enable Basic Authentication. If Basic Authentication is inadequate for your security requirements, use the [Kubernetes Cluster Connector](/harness-ai/use-harness-platform/connectors/cloud-providers/add-a-kubernetes-cluster-connector.md) instead.
{% endhint %}
### GCS and GCR role requirements
For Google Cloud Storage (GCS) and Google Container Registry (GCR), the following roles are required:
* Storage Object Viewer (`roles/storage.objectViewer`)
* Storage Object Admin (`roles/storage.objectAdmin`)
For more information, go to the GCP [Artifact registry roles reference](https://cloud.google.com/iam/docs/understanding-roles#artifact-registry-roles).
Ensure the Harness Delegate you have installed can reach `storage.cloud.google.com` and your GCR registry host, for example `gcr.io`. Registry host name is declared in your step settings. For example, you can declare it in the **Host** field in the [Build and Push to GAR step settings](https://developer.harness.io/continuous-integration/use-harness-ci/use-harness-ci/build-and-upload-artifacts/build-and-push/build-and-push-to-gar).
### GAR role requirements
For Google Artifact Registry, the following roles are required:
* Artifact Registry Reader
* Artifact Registry Writer
For more information, go the GCP documentation about [Configuring Roles for Artifact Registry](https://cloud.google.com/artifact-registry/docs/access-control)
### Google Cloud Operations Suite (Stackdriver) requirements
Most APM and logging tools are added to Harness as Verification Providers. For Google Cloud's operations suite (formerly Stackdriver), use the GCP connector.
The following roles and permissions are required:
* **Stackdriver Logs:** The minimum role requirement is **Logs Viewer** (`logging.viewer`)
* **Stackdriver Metrics:** The minimum role requirements are **Compute Network Viewer** (`compute.networkViewer`) and **Monitoring Viewer** (`monitoring.viewer`).
For more information, go to the Google documentation on [Access control](https://cloud.google.com/monitoring/access-control).
***
## Proxies and GCP with Harness
If you are using a proxy server in your GCP account, and you want to use GCP services with Harness, make sure the following items **do not** use your proxy:
* `googleapis.com`: For details, go to the Google documentation on [Proxy servers](https://cloud.google.com/storage/docs/troubleshooting#proxy-server).
* The `token_uri` value from your Google Service Account: For details, go to the Google documentation on [Creating service account keys](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating_service_account_keys).
***
## Auth Provider API and TokenRequest API options
Harness supports both the Auth Provider API and the TokenRequest API for GKE authentication.
Auth Provider API vs. TokenRequest API
In Kubernetes 1.22, the Auth Provider API was deprecated and replaced with the TokenRequest API. The TokenRequest API lets client libraries and tools request an authentication token from the Kubernetes API server dynamically, based on audience, scopes, and other parameters.
The key advantages of the TokenRequest API are finer-grained control over authentication and easier integration with external identity providers such as OAuth 2.0 providers.
To select which API to use:
* **Auth Provider API**: the current default. You do not have to change the default settings of Harness connectors or the Harness delegates you use.
* **TokenRequest API**: you must install the provider-specific plugin on the Harness delegate to use the TokenRequest API introduced in Kubernetes 1.22.
### Install the gke-gcloud-auth-plugin on the delegate
When using the Harness GCP connector with Kubernetes version 1.22 or later, you can use the **gke-gcloud-auth-plugin** to authenticate to a GKE cluster.
The GCP connector has two credential types. For each type, install the following dependencies on the Harness Delegates you use, or Harness falls back to the Auth Provider API format.
* **Service Account Key** (`ServiceAccountKey`): gcloud and the gke-gcloud-auth-plugin binary.
* **Inherit From Delegate** (`InheritFromDelegate`): gcloud and the gke-gcloud-auth-plugin binary.
Perform the following steps to install the gke-gcloud-auth-plugin on the delegate using an immutable delegate image and `INIT_SCRIPT`:
RHEL 7
```bash
tee -a /etc/yum.repos.d/google-cloud-sdk.repo << EOM
[google-cloud-cli]
name=Google Cloud CLI
baseurl=https://packages.cloud.google.com/yum/repos/cloud-sdk-el8-x86_64
enabled=1
gpgcheck=1
repo_gpgcheck=0
gpgkey=https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
EOM
# Install google-cloud-cli and google-cloud-cli-gke-gcloud-auth-plugin
microdnf install google-cloud-cli
microdnf install google-cloud-cli-gke-gcloud-auth-plugin
```
Ubuntu
```bash
apt-get install apt-transport-https ca-certificates gnupg
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | apt-key --keyring /usr/share/keyrings/cloud.google.gpg add -
apt-get update && apt-get install google-cloud-cli && apt-get install google-cloud-cli-gke-gcloud-auth-plugin
```
Go to [Install the gcloud CLI](https://cloud.google.com/sdk/docs/install) from Google and [Delegate installation overview](/harness-ai/use-harness-platform/delegates/delegate/install-delegates/overview.md) for further details.
***
## GCP connector settings
The GCP connector has the following settings to allow Harness to securely connect to Google Cloud Platform.
### Overview settings
Configure the following overview settings for the connector:
* **Name:** The unique name for the connector.
* **Id:** Harness automatically creates an **Id** ([Entity Identifier](/harness-ai/use-harness-platform/references/entity-identifier-reference.md)) based on the **Name**. You can change the **Id** during initial connector creation. Once saved, the **Id** cannot be changed.
* **Description:** Optional.
* **Tags:** For information about tags, go to the [Tags reference](/harness-ai/use-harness-platform/tags/overview.md#create-tags-for-pipelines).
### Details settings
Provide credentials that enable Harness to connect to your GCP account.
**Specify credentials here**
Select this option to use a GCP service account key.
* You can store a GCP service account keys as [Harness Encrypted File Secrets](/harness-ai/use-harness-platform/secrets/add-file-secrets.md).
* To obtain the Google Cloud's service account key file, go to the Google documentation on [Creating and managing service account keys](https://cloud.google.com/iam/docs/creating-managing-service-account-keys). JSON format is required.
**Use the credentials of a specific Harness Delegate**
Select this option to allow the connector to inherit its authentication credentials from the Harness Delegate that is running in GCP.
Learn more about credential inheritance
* **IAM role inheritance:** the connector inherits the GCP IAM role assigned to the delegate in GCP, such as a Harness Kubernetes delegate running in Google Kubernetes Engine (GKE). Make sure the delegate has the IAM roles that your connector needs.
* **GCP workload identity:** if you installed the Harness [Delegate](/harness-ai/use-harness-platform/delegates/delegate/install-delegates/overview.md) in a Kubernetes cluster in GKE that has [GCP Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity?hl=tr#enable_on_cluster) enabled and uses the same service account and node pool annotation, the GCP connector inherits these credentials if it uses that delegate.
* **Role and policy changes:** if the IAM role associated with your GCP connector does not have the policies required by the GCP service you want to access, you can modify or change the role assigned to the Harness Delegate that your GCP connector is using. You may need to wait up to five minutes for the change to take effect.
* **See also:**
* [Add a Google Cloud Platform (GCP) connector](/harness-ai/use-harness-platform/connectors/cloud-providers/connect-to-google-cloud-platform-gcp.md)
* [GCP Policy Simulator](https://cloud.google.com/iam/docs/simulating-access)
**Use OpenID Connect (OIDC)**
Select **OIDC** in **Details**, then select **Connect through Harness Platform for OIDC workflow** in **Select Connectivity Mode**. This option uses OIDC authentication to access public cloud resources without secrets or credentials.
To connect to GCP with OIDC, you must configure an [OIDC identity provider](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers) GCP and connect the service account with relevant permissions that Harness will use to operate in GCP. Use the following Harness OIDC provider endpoint and OIDC audience settings to create your OIDC identity provider.
* Harness OIDC Issuer provider endpoint: `https://app.harness.io/ng/api/oidc/account/`. See below for more details about the Issuer URL format, depending on the environment cluster for your Harness Account.
* OIDC audience: `https://iam.googleapis.com/projects//locations/global/workloadIdentityPools//providers/`
When accessing Google Cloud resources, use [Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation) to grant short-term access to the Harness GCP connector. For instructions, go to [Configure OIDC with GCP WIF for Harness Cloud](https://developer.harness.io/continuous-integration/use-harness-ci/secure-harness-ci/configure-oidc-gcp-wif-ci-hosted).
**Workload Identity Federation field requirements**
When configuring the GCP connector with OIDC, pay careful attention to the field formats:
{% hint style="info" %}
**Field format requirements**
* **Workload Pool ID**: enter only the pool name, for example `harness-pool`, not the full resource path.
* **Provider ID**: enter only the provider name, for example `harness-provider`, not the full resource path.
* **Project Number**: use the numeric project number, not the project ID.
{% endhint %}
**Correct format examples:**
* Workload Pool ID: `harness-pool`
* Provider ID: `harness-provider`
* Project Number: `421331508843`
**Incorrect format examples (will cause errors):**
* Workload Pool ID: `projects/421331508843/locations/global/workloadIdentityPools/harness-pool`
* Provider ID: `projects/421331508843/locations/global/workloadIdentityPools/harness-pool/providers/harness-provider`
Using full resource paths results in duplication errors such as:
```
"OIDC Configuration Error: Error encountered while obtaining OIDC Access Token from STS for Aud //iam.googleapis.com/projects/.../workloadIdentityPools/projects/..."
```
**Finding your WIF values in the GCP console**
Perform the following steps to locate the correct values in the Google Cloud console:
1. Navigate to **IAM & Admin** -> **Workload Identity Federation**.
2. Select your workload identity pool.
3. Copy the **Pool ID** (name only, not the full path).
4. Select your identity provider.
5. Copy the **Provider ID** (name only, not the full path).
6. Find the **Project Number** in the project selector dropdown or project settings.
**Enable cross-project access**
You can scope one connector to multiple GCP projects, eliminating the need to create separate connectors for each project.
This feature is supported when the GKE infrastructure type (Kubernetes, Helm, or Google Cloud Run) is selected. The connector allows access to multiple GCP projects for Kubernetes, Helm, and Google Cloud Run infrastructure types only.
**Project selection flow**: the system queries the list of GCP projects accessible through the connector. You can select a target project (for example, `project2`) in addition to the original project (`project1`). With both project values set, Harness invokes the relevant APIs using both projects.
**Configuring the project at the infrastructure level**
Perform the following steps to configure the **Project** at the infrastructure level:
1. Navigate to **Project Settings** -> **Environment**, and select your desired Kubernetes environment.
2. In the **Infrastructure Definition** section, select **Deployment Type** as **Kubernetes** or **Helm Native**, and **Infrastructure Type** as **Google Kubernetes Engine**.
3. In the **Cluster Details** section:
* For **Connector**: select the previously configured GCP connector.
* **Project (optional)**: select the project you want to use from the dropdown.
* **Cluster**: select a cluster from the dropdown, which lists all clusters associated with the selected project.
* **Namespace**: enter the target namespace in the target cluster.
For more detailed instructions on using this with a Kubernetes infrastructure, go to [Kubernetes infrastructure](https://developer.harness.io/continuous-delivery/use-continuous-delivery/deploy-services-on-different-platforms/kubernetes/define-your-kubernetes-target-infrastructure#google-kubernetes-engine-gke).
### OIDC claims supported in Harness
**Trusted Claims:**
* Harness validates the following claims internally to determine if the principal has the required permissions. When configuring trust on the Cloud Provider side, only these specific claims and their exact values should be accepted. Any claims outside this list must be rejected to avoid unauthorized access.
* `accountId`
* `organizationId`
* `projectIdentifier`
* `pipelineIdentifier`
* The following claims are validated for existence in Harness, but do not include an access check:
* `environmentIdentifier`
* `connectorIdentifier`
* `serviceIdentifier`
**Non-Trusted Claims**
* The following claims are considered non-trusted. They are not validated for existence or access control and are used for informational context only:
* `environmentType`
* `connectorName`
* `serviceName`
* `triggeredByName`
* `triggerByEmail`
* `stageType`
* `stepType`
* `context`
**Custom Parameters**
You can add attribute conditions in your Workload Identity Pools under Workload Identity Federation.
Here are the custom attributes for the Harness GCP OIDC JWT:
* **account\_id**: The account id of your Harness account.
* **organization\_id**: The organization id of your Harness organization.
* **organization\_name**: The organization name
* **project\_id**: The project id of your Harness project.
* **project\_name**: The project name.
* **connector\_id**: The id of the OIDC-enabled GCP connector that sent this token.
* **connector\_name**: The name of the OIDC-enabled GCP connector that sent this token.
* **pipeline\_Identifier**: Pipeline identifier
* **pipeline\_Name**: Pipeline Name
* **environment\_identifier**: Environment Identifier
* **environment\_name**: Environment name
* **environment\_type**: Environment Type
* **context**: This specifies the Harness context from when this OIDC token is generated. Possible values for this field are:
* `CONNECTOR_VALIDATION` - This context is sent when the connector is being setup.
* `PIPELINE_CONFIGURATION` - This context is sent when a pipeline configuration is being completed.
* `PIPELINE_EXECUTION` - This context is sent when a pipeline configuration is being executed.
* `PERPETUAL_TASK` - This context is sent when a perpetual task is executing.
**Examples**
JWT sent by a connector at the account scope
The header contains the signing key ID:
```json
{
"typ": "JWT",
"alg": "RS256",
"kid": "NjVBRjY5MDlCMUIwNzU4RTA2QzZFMDQ4QzQ2MDAyQjVDNjk1RTM2Qg"
}
```
The payload contains the claims, including the `aud` claim, which is the address of the Harness instance with the account ID:
```json
{
"sub": "Provider:Harness:Account:{account_id}",
"iss": "https://token.oidc.harness.io/account/{account_id}",
"aud": "https://app.harness.io/{account_id}",
"exp": 1632493867,
"iat": 1632493567,
"account_id": "{account_id}"
}
```
Custom attributes will be included in the JWT payload.
***
## Next steps
* [Add a Google Cloud Platform (GCP) connector](/harness-ai/use-harness-platform/connectors/cloud-providers/connect-to-google-cloud-platform-gcp.md): create a GCP connector using the Harness UI.