Add a Kubernetes cluster connector

Connect Harness to your Kubernetes clusters on any platform.

Use a Harness Kubernetes cluster connector to connect Harness to a Kubernetes cluster on any platform. Use the connector to provision infrastructure, run a Continuous Integration (CI) build farm, and deploy microservices and other workloads to the cluster. This topic assumes you have some familiarity with Harness' key concepts.

To connect to a platform-specific Kubernetes cluster, such as Google Kubernetes Engine (GKE) or Amazon Elastic Kubernetes Service (EKS), you can use this platform-agnostic connector or a platform-specific connector, such as the GCP connector or the AWS connector.

What you will learn from this topic

How to add a Kubernetes cluster connector at the account, org, or project scope.
How to select a connectivity method for the connector.
How to configure the roles and policies required for deployments and builds.
How to use the connector with Amazon EKS and Azure Kubernetes Service (AKS) clusters.
How to define a Kubernetes cluster connector using a YAML example.

Before you begin

Kubernetes roles and policies: assign the Kubernetes service account or Harness Delegate that the connector will use the roles and policies required for how you use the connector in your Harness pipelines, such as deployments or Continuous Integration (CI) builds. Go to the Kubernetes cluster connector settings reference for the full list of roles and policies.
Amazon EKS clusters: for considerations specific to EKS, go to Connect to Amazon EKS.
Azure Kubernetes Service (AKS) clusters: for considerations specific to AKS, go to AKS clusters must have local accounts enabled.

Platform-specific considerations

Review the following considerations if your target cluster runs on Amazon EKS or Azure Kubernetes Service (AKS).

Connect to Amazon EKS

To connect Harness to Amazon EKS, you can use the platform-agnostic Kubernetes cluster connector or an AWS connector configured for EKS.

To use an EKS cluster for Kubernetes cluster build infrastructure in Harness CI, you must create a platform-agnostic Kubernetes cluster connector for the stage's build infrastructure, and then you can use either type of connector in individual steps in the stage.

For individual steps in a build stage, if your EKS clusters use IAM roles for service accounts (IRSA) or Fargate nodes in EKS clusters, use an AWS connector configured for EKS.

Switching IAM policies: if the IAM role used by your connector does not have the required policies, you can modify or switch the role assigned to the cluster or the Harness Delegate associated with your connector. It can take up to five minutes for IAM policy changes to take effect.

AKS clusters must have local accounts enabled

To use an AKS cluster for deployments, the AKS cluster must have local accounts enabled (AKS property disableLocalAccounts=false).

Create a Kubernetes cluster connector

Perform the following steps to create the Kubernetes cluster connector.

The connector wizard guides you through four steps: Overview, Details, Delegates Setup, and Connection Test.

Overview

Perform the following steps:

Go to Project Settings (or Account Settings or Organization Settings) -> Connectors.
Select New Connector -> Cloud Providers -> Kubernetes cluster.
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.
Optionally, add a Description and Tags.

Select Continue to proceed to Details.

Details

On the Details page, select how you want Harness to reach your Kubernetes cluster.

Specify master URL and credentials: authenticate using the Kubernetes master node URL and one of the supported authentication methods. For more information, go to Specify master URL and credentials in the Kubernetes cluster connector settings reference.
Use the credentials of a specific Harness Delegate (IAM role, service account, etc): allow the connector to inherit its authentication credentials from the Harness Delegate running in the target cluster. For more information, go to Use the credentials of a specific Harness Delegate in the Kubernetes cluster connector settings reference.

Select Continue to proceed to Delegates Setup.

Delegates Setup

Harness uses Kubernetes cluster connectors at pipeline runtime to authenticate and perform operations with Kubernetes. Authentications and operations are performed by Harness Delegates. Regardless of the authentication method selected in Details, you must select the Delegates this connector will use.

Use any available Delegate: Harness selects an available delegate at runtime. To learn how Harness selects a delegate when none is specified, go to Task assignment.
Only use Delegates with all of the following tags: use Tags to match one or more suitable delegates. Harness displays the matching delegates and their tags in the Test Delegate Connectivity table. 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 tests the credentials you provided using the delegates you selected and shows the delegate that executed the check. If the test succeeds, select Finish to complete the connector setup.

YAML examples

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

Specify master URL and credentials

The following YAML defines a Kubernetes cluster connector that uses the Specify master URL and credentials credential type with a service account token.

Kubernetes cluster connector YAML

connector:
  name: K8s-qa-target # Connector display name shown in the Harness UI
  identifier: K8sqatarget # Unique connector identifier, cannot be changed after creation
  description: ""
  accountIdentifier: <YOUR_ACCOUNT_ID> # Harness account identifier that owns the connector
  type: K8sCluster # Connector type
  spec:
    credential:
      type: ManualConfig # Use the Specify master URL and credentials credential type
      spec:
        masterUrl: <KUBERNETES_MASTER_URL> # Kubernetes master node URL, for example https://<cluster-api-server>
        auth:
          type: ServiceAccount # Authentication method used with the master URL
          spec:
            serviceAccountTokenRef: account.<YOUR_SECRET_ID> # Identifier of the Harness secret storing the service account token
    ignoreTestConnection: false # Run the connection test when the connector is saved

Use the credentials of a specific Harness Delegate (IAM role, service account, etc)

The following YAML defines a Kubernetes cluster connector that uses the Use the credentials of a specific Harness Delegate (IAM role, service account, etc) credential type, and selects a delegate by tag.

Kubernetes cluster connector YAML

connector:
  name: K8s-inherit-delegate # Connector display name shown in the Harness UI
  identifier: K8sinheritdelegate # Unique connector identifier, cannot be changed after creation
  description: ""
  accountIdentifier: <YOUR_ACCOUNT_ID> # Harness account identifier that owns the connector
  type: K8sCluster # 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
    ignoreTestConnection: false # Run the connection test when the connector is saved

Next steps

Kubernetes cluster connector settings reference: review Kubernetes cluster connector settings, credential options, required roles and permissions, and Amazon EKS and OpenShift support.
GCP connector: connect Harness to Google Cloud Platform, including GKE clusters and other GCP resources.
AWS connector: connect Harness to AWS, including EKS clusters and other AWS resources.

PreviousGoogle Cloud Platform (GCP) connector settings reference

NextKubernetes cluster connector settings reference

Last updated 12 days ago

Was this helpful?