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, and deploy microservices and 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.
This topic explains how to set up a GCP connector.
Auth Provider API and TokenRequest API options
Harness provides the option of using the Auth Provider API or TokenRequest API for authentication.
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
RHEL 7 OS
tee -a /etc/yum.repos.d/google-cloud-sdk.repo << EOM
name=Google Cloud CLI
# 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
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
Before you begin
Before you begin, you must:
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'll use with Harness and which operations you'll 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 doesn't 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 a list of roles and policies, 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
If you use a GCP connector that inherits credentials from a delegate, which 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_PROXYlist. To verify the IP address, go to Understanding the GKE metadata server in the GCP docs. To add the IP address to your
NO_PROXYlist, do the following:
harness-delegate.yamlyou used to create the delegate, and add the GKE metadata server IP address to the
NO_PROXYsetting in the
- name: NO_PROXY
harness-delegate.yamlagain to restart the Kubernetes delegate (
kubectl apply -f harness-delegate.yaml).
Add a GCP connector and configure credentials
- Open a Harness project, and select Connectors under Project Setup.
- Select New Connector, and then select GCP under Cloud Providers.
- 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.
- Select Continue to configure credentials. Select one of the following authentication options:
- Select Specify credentials here to use a GCP service account key.
- Select Use the credentials of a specific Harness Delegate to allow the connector to inherit its authentication credentials from the Harness Delegate that is running in GCP.
- Select Continue to proceed to Select Connectivity Mode.
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). Ensure the delegate has the IAM roles that your connector needs to perform the necessary operations.
- GCP workload identity: If you installed the Harness Kubernetes delegate in a Kubernetes cluster in GKE that has GCP Workload Identity enabled and uses the same service account and node pool annotation, then the Google Cloud Platform (GCP) connector inherits these credentials if it uses that delegate.
- Role and policy changes: If you find that the IAM role associated with your GCP connector doesn't 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:
Select connectivity mode
Harness uses GCP connectors during pipeline runs to authenticate and perform operations with GCP.
- Select how you want Harness to connect to GCP:
- Connect through Harness Platform: Use a direct, secure communication between Harness and GCP.
- 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 connecting through a Harness Delegate, select either:
- 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.
- Select Install new Delegate to add a delegate without exiting connector configuration. For guidance on installing delegates, go to Delegate installation overview.
- Select Save and Continue to run the connection test, and then, if the test succeeds, select Finish. The connection test confirms that your authentication and delegate selections are valid.
GCP connector errors
If the connection test fails due to a credentials issue, use the GCP CLI or console to check the GCP service account or delegate's credentials. 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 doesn't 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.