Connect your cluster

This page is a chapter of the Quickstart learning path. Make sure to progress through the chapters in the order set in the main navigation. To start out, go to Introduction .

Overview #

Connecting your cluster effectively means preparing the right level of access to the cluster for the Platform Orchestrator, and then instructing the Orchestrator how to find your cluster.

The details of all pre-scripted steps are described on the Kubernetes page in the developer docs. You don’t have to read through them now, we will walk you through them one by one.

Create a Cloud Account #

Skip this step if you are using a generic cluster, and proceed to creating a Resource Definition .

A Cloud Account allows you to store credentials for cloud infrastructure which the Platform Orchestrator needs to connect to at a central place in your Humanitec Organization.

Those credentials are bound to a principal you create in your cloud’s identity system. There is also a choice of temporary, short-lived credentials, and static, long-lived ones. We will be using the temporary variants which offer superior security.

To prepare the required principal and create your Cloud Account, execute the respective script for your cloud:

. ./scripts/connect-your-cluster/cloudaccount-${CLOUD}.sh

The script creates all the required objects on your cloud and finally the actual Cloud Account in the Platform Orchestrator.

The scripts reiterate the exact instructions available in our developer docs for AWS , Azure , and GCP .

If you wish to maintain a future setup for your IDP using Terraform, this is possible using your cloud’s Terraform provider together with the Humanitec Terraform Provider . Note that Cloud Accounts are named humanitec_resource_account.

Inspect the newly created Cloud Account object:

humctl get resource-account quickstart-${CLOUD} -o yaml

You will see that the Cloud Account has a value of is_used: false. This will change soon when you utilize the Account for your cluster definition in an upcoming step.

Test the Cloud Account to ensure that the Platform Orchestrator can use the credential:

humctl resources check-account quickstart-${CLOUD}

Configure cluster access in your cloud #

Skip this step if you are using a generic cluster, and proceed to creating a Resource Definition .

The principal used for the Cloud Account needs to be granted appropriate permissions on the target cluster so that the Platform Orchestrator can perform the required actions using the Account. Here, we want the Orchestrator being able to access your Kubernetes cluster and perform elevated actions like creating namespaces, Deployments, and more.

Each cloud provider defines their own mechanism for managing cluster access. Please make sure that your cluster supports the authz flavor stated in the prerequisites . You can then execute the next script to assign the required permissions. The script executes the instructions available in the developer docs for AKS , EKS , and GKE , applying the most simple solution in each case

. ./scripts/connect-your-cluster/clusteraccess-${CLOUD}.sh

Create a cluster Resource Definition #

Now that we have the cluster access prepared, let’s look at how to connect it to the Platform Orchestrator. What we need is called a Resource Definition . It defines WHAT (Resource Type) is deployed HOW (Driver and possibly IaC) and WHEN (matching criteria).

Create your Resource Definition for the cluster and then apply it to the Orchestrator using humctl.

. ./scripts/connect-your-cluster/create-resdef-${CLOUD}.sh

The command creates the Resource Definition in a new YAML file. Output its contents and quickly look at some key elements:

cat resdef-${CLOUD}.yaml

• The WHAT is defined through the Resource Type : type: k8s-cluster
• The HOW is defined through the Driver built into the Platform Orchestrator: driver_type: humanitec/k8s-cluster<-cloud>
• The WHEN is defined through the matching Criteria of app_id: quickstart (the id of the Application you are going to create next)
• The driver_account references the Cloud Account you created earlier
• The driver_inputs contain all the data to locate your target cluster

Install the Resource Definition into your Organization:

humctl apply -f resdef-${CLOUD}.yaml

You can find the examples for these Resource Definitions, and much more, in our Example Library .

Recap #

And that concludes this chapter. You have:

• ✅ Created a Cloud Account providing access to your cloud via a new principal
• ✅ Assigned the required permissions to that principal
• ✅ Provided a Resource Definition instructing the Platform Orchestrator how to access your target cluster

Note that those steps are a one-time effort. You can now deploy any number of Workloads onto your cluster going forward. Continue to make your first deployment in the next chapter.

Your setup now looks like this:

flowchart LR
  subgraph platformOrchestrator[Platform Orchestrator]
    cloudAccount(Cloud Account) -.- resDefCluster(Resource Definition\nCluster)
  end
  subgraph cloudInfrastructure[Cloud Infrastructure]
    k8sCluster(Kubernetes Cluster)
  end
  resDefCluster -.- k8sCluster

Continue to deploy your first Application .