Add a Google Cloud Platform (GCP) connector

Connect Harness to your GCP accounts and services.

Use a Harness Google Cloud Platform (GCP) connector to integrate GCP with Harness. You can use GCP with Harness to obtain or upload artifacts, communicate with GCP services, provision infrastructure, push images, and deploy microservices and other workloads. When a pipeline runs, Harness uses the credentials provided in the GCP connector's settings to authenticate and perform operations with GCP.

---

What you will learn from this topic

• How to add a GCP connector at the account, org, or project scope.

• How to configure credentials using a service account key, delegate credential inheritance, or OIDC.

• How to select a connectivity mode and complete the connector setup.

• How to configure the roles and policies required for GKE, GCS, GCR, GAR, or Stackdriver.

• How to install the gke-gcloud-auth-plugin on a delegate for GKE authentication using Kubernetes 1.22 and later.

• How to define a GCP connector using a YAML example.

---

Before you begin

• Assign IAM roles to the GCP service account or Harness Delegate that you will attach to the connector.

  • The necessary IAM roles and policies depend on which GCP service you will use with Harness and which operations you will want Harness to perform in GCP.

  • GCP connectors can also inherit IAM roles from Harness Delegates running in GCP. If you want your connector to inherit from a delegate, make sure the delegate has the necessary roles.

  • If you find that 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 GCP account or the Harness Delegate that your GCP connector is using. You might need to wait up to five minutes for the change to take effect.

  • For details about the roles and policies required to use a GCP connector with GKE, GCS, GCR, GAR, or Stackdriver, go to Google Cloud Platform (GCP) Connector Settings Reference.

  • The GCP Policy Simulator is useful for evaluating policies and access.

• Check your GKE version.

  • Harness supports GKE 1.19 and later.

  • If you use a version prior to GKE 1.19, please enable Basic Authentication. If Basic authentication is inadequate for your security requirements, use the Kubernetes Cluster Connector.

• Add the GKE metadata server IP to your NO_PROXY list.

  • If your GCP connector will inherit credentials from a delegate that uses a proxy and the GKE cluster or VM where the delegate is installed uses Workload Identity to authenticate, then you must add the GKE metadata server IP (169.254.169.254) to your NO_PROXY list.

  • To verify the IP address, go to Understanding the GKE metadata server in the GCP docs.

  • To add the IP address to your NO_PROXY list, do the following:

    • Open the harness-delegate.yaml you used to create the delegate, and add the GKE metadata server IP address to the NO_PROXY setting in the StatefulSet spec:

          - name: NO_PROXY  
            value: "169.254.169.254"

      Apply harness-delegate.yaml again to restart the Kubernetes delegate (kubectl apply -f harness-delegate.yaml).

---

Create a GCP connector

Perform the following steps to create the GCP connector.

The connector wizard guides you through four steps: Overview, Details, Select Connectivity Mode, and Connection Test. If you select Connect through a Harness Delegate in Select Connectivity Mode, the wizard adds a Delegates Setup step.

Overview

Perform the following steps:

1. Go to Project Settings (or Account Settings or Organization Settings) -> Connectors.

2. Select New Connector -> Cloud Providers -> GCP - Cloud Provider.

3. Enter a Name. Harness automatically creates an Id based on the name using the Entity Identifier format. You can edit the ID before saving; once saved, the ID is immutable.

4. Optionally, add a Description and tags.

1. Select Continue to proceed to Details.

Details

The GCP connector supports three credential methods. Select the method that matches your GCP setup.

• Specify credentials here: Authenticate using a GCP service account key. For more information, go to Details settings in the GCP connector settings reference.

• Use the credentials of a specific Harness Delegate: Allow the connector to inherit its authentication credentials from the Harness Delegate that is running in GCP. This option requires Connect through a Harness Delegate in the next step.

• OIDC: Enables OIDC authentication to access GCP resources without secrets or credentials. For more information, go to Use OpenID Connect (OIDC) in the GCP connector settings reference.

Select Continue to proceed to Select Connectivity Mode.

Select connectivity mode

On the Connect to the provider page, select how you want Harness to communicate with GCP. The available options depend on what you chose for Details settings in the previous step.

• Connect through Harness Platform: Harness communicates with GCP through a direct, secure communication between Harness and GCP. All credentials are encrypted and stored in the Secret Manager configured in Harness. A Harness Delegate still performs deployment operations, even when you select this connectivity mode. This connectivity mode is required for Harness Cloud build infrastructure.

• Connect through a Harness Delegate: Harness communicates with GCP behind your corporate firewall, through a Harness Delegate you install in your environment. You must choose this option if you chose to inherit delegate credentials.

• Connect through Harness Platform for OIDC workflow: This option appears only if you selected OIDC in Details. It uses OIDC authentication to access public cloud resources without secrets or credentials. For more information, go to Use OpenID Connect (OIDC) in the GCP connector settings reference.

Select Continue (or Save and Continue for the OIDC connectivity mode) to proceed.

Delegates Setup

If you selected Connect through a Harness Delegate, select the Delegates this connector will use:

• Use any available Delegate: Harness selects an available delegate at runtime. To learn how Harness selects delegates, go to Delegate overview.

• Only use Delegates with all of the following tags: Use Tags to match one or more suitable delegates. To learn more about delegate tags, go to Use delegate selectors. You can select Install new Delegate to add a delegate without exiting connector configuration. For guidance on installing delegates, go to Delegate installation overview.

It is possible to create a connector with a non-existent delegate. This behavior is intended. This design allows customers to replace a delegate with a new one of the same name or tag.

Select Save and Continue to proceed to Connection Test.

Connection Test

Harness validates the GCP connector authentication and permissions and shows the delegate that executed the check. If the test succeeds, select Finish to complete the connector setup.

For private network connectivity options with Harness Cloud, see Private network connectivity options.

---

YAML examples

The following YAML examples show how to configure a GCP connector for each credential type.

Specify credentials here

The following YAML defines a GCP connector that uses the Specify credentials here credential type with a GCP service account key, and connects through a Harness Delegate.

GCP connector YAML

connector:
  name: GCP-qa-target # Connector display name shown in the Harness UI
  identifier: GCPqatarget # Unique connector identifier, cannot be changed after creation
  accountIdentifier: <YOUR_ACCOUNT_ID> # Harness account identifier that owns the connector
  type: Gcp # Connector type
  spec:
    credential:
      type: ManualConfig # Use the Specify credentials here credential type
      spec:
        secretKeyRef: account.<YOUR_SECRET_ID> # Identifier of the Harness secret storing the GCP service account key
    executeOnDelegate: true # Connect through a Harness Delegate
    proxy: false # Set to true if the delegate connects to GCP through a proxy
    ignoreTestConnection: false # Run the connection test when the connector is saved

Use the credentials of a specific Harness Delegate

The following YAML defines a GCP connector that uses the Use the credentials of a specific Harness Delegate credential type, and selects a delegate by tag.

GCP connector YAML

connector:
  name: GcpManualSXp0MjZmBY # Connector display name shown in the Harness UI
  identifier: GcpManualYH6md2VtFy # Unique connector identifier, cannot be changed after creation
  description: GcpManualSXp0MjZmBY # Optional connector description
  accountIdentifier: <YOUR_ACCOUNT_ID> # Harness account identifier that owns the connector
  type: Gcp # Connector type
  spec:
    credential:
      type: InheritFromDelegate # Use the Use the credentials of a specific Harness Delegate credential type
    delegateSelectors:
      - <YOUR_DELEGATE_SELECTOR> # Delegate tag used to select a delegate for this connector
    executeOnDelegate: true # Connect through a Harness Delegate
    proxy: false # Set to true if the delegate connects to GCP through a proxy
    ignoreTestConnection: false # Run the connection test when the connector is saved

---

Troubleshooting

Troubleshoot GCP connector errors

If the connection test fails due to a credentials issue, use the GCP CLI or console to check the credentials of the GCP service account or delegate. The GCP Policy Simulator is useful for evaluating policies and access.

Due to the limited scope of the initial connection test, credentials can pass the connection test and then fail when you use the connector in a pipeline if the IAM role the connector is using does not have the roles and policies needed for the pipeline's operations. For example, if a pipeline has a Run step that references a GCP connector, the connector may need specific roles or policies to execute the operations required by the Run step.

If you experience any errors with GCP connectors, verify that the IAM roles and policies it is using are correct. For a list of roles and policies, go to the GCP connector settings reference.

---

Next steps

• GCP connector settings reference: review GCP connector settings, credential options, required roles and permissions, and the gke-gcloud-auth-plugin setup.

• Configure OIDC with GCP WIF for Harness Cloud: use Workload Identity Federation to authenticate Harness Cloud builds with GCP.

• Kubernetes infrastructure: define a GKE target infrastructure for a Kubernetes deployment.

Use a Harness Google Cloud Platform (GCP) connector to integrate GCP with Harness. You can use GCP with Harness to obtain or upload artifacts, communicate with GCP services, provision infrastructure, push images, and deploy microservices and other workloads. When a pipeline runs, Harness uses the credentials provided in the GCP connector's settings to authenticate and perform operations with GCP.

To connect to Kubernetes clusters in GCP, you can use a GCP connector or the platform-agnostic Kubernetes Cluster connector.

Auth Provider API and TokenRequest API options

Harness provides the option of using the Auth Provider API or TokenRequest API for authentication. Complete this setup if you want to use this option for your GCP connector.

Summary of Auth Provider and TokenRequest API changes

In Kubernetes 1.22, the Auth Provider API was deprecated and replaced with a new TokenRequest API. The TokenRequest API is used by client libraries and tools to request an authentication token from the Kubernetes API server.

The TokenRequest API provides a more flexible and extensible authentication mechanism than the Auth Provider API. Instead of relying on pre-configured authentication plugins, client libraries and tools can now dynamically request authentication tokens from the Kubernetes API server based on their specific needs and requirements.

To use the TokenRequest API for authentication, client libraries and tools can send a TokenRequest object to the Kubernetes API server. The TokenRequest object specifies the audience, scopes, and other parameters for the requested token. The Kubernetes API server then validates the request, generates a token with the requested parameters, and returns the token to the client.

One advantage of the TokenRequest API is that it allows for more fine-grained control over authentication and authorization. For example, a client library or tool can request a token with only the necessary scopes to perform a specific operation, rather than requesting a token with full cluster access.

Another advantage of the TokenRequest API is that it allows for easier integration with external identity providers and authentication systems. Client libraries and tools can use the TokenRequest API to request authentication tokens from external providers, such as OAuth2 providers or custom authentication systems, and use those tokens to authenticate to the Kubernetes API server.

Overall, the TokenRequest API provides a more flexible and extensible authentication mechanism than the deprecated Auth Provider API, and allows for more fine-grained control over authentication and authorization in Kubernetes.

To select which API to use:

• Auth Provider API: this is 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(s) 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, you can use the gke-gcloud-auth-plugin to authenticate to GKE cluster.

The Harness GCP connector has 2 credential types. For each type, you must install the following dependencies in the Harness Delegates you use or Harness will follow the old Auth Provider API format.

• Service Account Key (ServiceAccountKey): gcloud and gke-gcloud-auth-plugin binary.

• Inherit From Delegate (InheritFromDelegate): gcloud and gke-gcloud-auth-plugin binary.

You can install the gke-gcloud-auth-plugin on the delegate by creating a delegate with an immutable image and updating the following commands in INIT_SCRIPT:

RHEL 7 OS

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

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

For more information, go to Install the gcloud CLI from Google and Delegate installation overview.

Prepare GCS

Before creating the GCP connector, you need to:

• Assign IAM roles to the GCP service account or Harness Delegate that you will attach to the connector.

  • The necessary IAM roles and policies depend on which GCP service you will use with Harness and which operations you will want Harness to perform in GCP.

  • GCP connectors can also inherit IAM roles from Harness Delegates running in GCP. If you want your connector to inherit from a delegate, make sure the delegate has the necessary roles.

  • If you find that 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 GCP account or the Harness Delegate that your GCP connector is using. You might need to wait up to five minutes for the change to take effect.

  • For details about the roles and policies required to use a GCP connector with GKE, GCS, GCR, GAR, or Stackdriver, go to Google Cloud Platform (GCP) Connector Settings Reference.

  • The GCP Policy Simulator is useful for evaluating policies and access.

• Check your GKE version.

  • Harness supports GKE 1.19 and later.

  • If you use a version prior to GKE 1.19, please enable Basic Authentication. If Basic authentication is inadequate for your security requirements, use the Kubernetes Cluster Connector.

• Add the GKE metadata server IP to your NO_PROXY list.

  • If your GCP connector will inherit credentials from a delegate that uses a proxy and the GKE cluster or VM where the delegate is installed uses Workload Identity to authenticate, then you must add the GKE metadata server IP (169.254.169.254) to your NO_PROXY list.

  • To verify the IP address, go to Understanding the GKE metadata server in the GCP docs.

  • To add the IP address to your NO_PROXY list, do the following:

    • Open the harness-delegate.yaml you used to create the delegate, and add the GKE metadata server IP address to the NO_PROXY setting in the StatefulSet spec:

          - name: NO_PROXY  
            value: "169.254.169.254"

      Apply harness-delegate.yaml again to restart the Kubernetes delegate (kubectl apply -f harness-delegate.yaml).

Create a GCP connector

1. Open a Harness project, and select Connectors under Project Setup.

2. Select New Connector, and then select GCP under Cloud Providers.

3. Input a Name for the connector. Description and Tags are optional. Harness automatically creates an Id (entity identifier) for the connector based on the Name.

4. Select Continue to configure credentials. For more information about these options, go to the Details settings in the GCP connector settings reference.

   • Specify credentials here: Use a GCP service account key.

   • Use the credentials of a specific Harness Delegate: Allow the connector to inherit its authentication credentials from the Harness Delegate that is running in GCP.

   • OIDC: Enables OIDC authentication. For more information, go to Use OIDC.

5. Select Continue to proceed to Select Connectivity Mode and select how you want Harness to connect to GCP. For more information about these options, go to the Connectivity mode settings in the GCP connector settings reference.

   • Connect through Harness Platform: Use a direct, secure communication between Harness and GCP. This connectivity mode is required for Harness Cloud build infrastructure.

   • Connect through a Harness Delegate: Harness communicates with GCP through a Harness Delegate in GCP. You must choose this option if you chose to inherit delegate credentials. If you select this option, you must select if you want Harness to use any available delegate or only use delegates with specific tags.

   It is possible to create a connector with a non-existent delegate. This behavior is intended. This design allows customers to replace a delegate with a new one of the same name or tag.

   • Connect through Harness Platform for OIDC: This option uses OIDC authentication to access public cloud resources without secrets or credentials. For more information, go to Use OIDC.

6. Select Save and Continue to run the connection test. If the test succeeds, select Finish. The connection test confirms that your authentication and delegate selections are valid.

For private network connectivity options with Harness Cloud, see Private network connectivity options.

Troubleshoot GCP connector errors

If the connection test fails due to a credentials issue, use the GCP CLI or console to check the credentials of the GCP service account or delegate. The GCP Policy Simulator is useful for evaluating policies and access.

Due to the limited scope of the initial connection test, credentials can pass the connection test and then fail when you use the connector in a pipeline if the IAM role the connector is using does not have the roles and policies needed for the pipeline's operations. For example, if a pipeline has a Run step that references a GCP connector, the connector may need to have specific roles or policies to be able to execute the operations required by the Run step.

If you experience any errors with GCP connectors, verify that the IAM roles and policies it is using are correct.

For a list of roles and policies, go to the Google Cloud Platform (GCP) Connector Settings Reference.