External Kubernetes Clusters

This section describes how to add, create and manage Kubernetes clusters known as external clusters in KKP. You can create a new cluster or import/connect an existing cluster.

  • Import: You can import a cluster via credentials. Imported Cluster can be viewed and edited. Supported Providers:

    • Azure Kubernetes Service (AKS)
    • Amazon Elastic Kubernetes Service (EKS)
    • Google Kubernetes Engine (GKE)
  • Connect: You can also connect any cluster in the KKP via kubeconfig. Connected clusters can only be viewed, not edited.

The KKP platform uses the provided kubeconfig or generates a new one from the cloud provider API. The KKP backend takes advantage of this kubeconfig to retrieve the cluster’s information, nodes, metrics, and events. Every cluster update is performed only by the cloud provider client. There is no need to install any agent on the cloud provider side.


The following requirements must be met to add an external Kubernetes cluster:

  • The external Kubernetes cluster must already exist before you begin the import/connect process. Please refer to the cloud provider documentation for instructions.
  • The external Kubernetes cluster must be accessible using kubectl to get the information needed to add that cluster.
  • Make sure the cluster kubeconfig or provider credentials have sufficient rights to manage the cluster (get, list, upgrade,get kubeconfig)

Import External Cluster

KKP allows connecting any existing Kubernetes cluster as an external cluster to view the cluster’s current state.

  • To add a new external cluster go to External Clusters page and Click the Import External Cluster button.

Import External Cluster

  • Select the Kubernetes cloud provider. You can add or create the following external clusters:

  • To connect a cluster from any provider, click on Any Provider and provide the cluster name and kubeconfig.

It is important that the kubeconfig used to connect the cluster is using standard authentication mechanisms like certificates or ServiceAccount tokens. OIDC or provider-specific plugins are not supported.

Connect Cluster

If an existing kubeconfig uses custom authentication mechanisms, kubermatic-installer convert-kubeconfig can (optionally) be used to create a ServiceAccount on the external cluster and fetch its token into a new kubeconfig.

Provide kubeconfig

You can then see the details of the cluster.

Custom Cluster

Create External Cluster

KKP allows creating a Kubernetes cluster on AKS/GKE/EKS and import it as an External Cluster.

Create External Cluster

External Cluster List

Delete Cluster:

Delete operation is not allowed for imported clusters.

Cluster can be Deleted by clicking on the delete icon next to the cluster you want to delete or from the cluster details page, which will delete and disconnect the cluster from the provider.

Delete External Cluster

Delete External Cluster on Details Page

Cluster State

You can view the current state of your cluster by hovering the cursor over the small circle on the left of the cluster name.

Provisioning state depicts that the cluster is getting created: External Cluster Provisioning State

Reconciling state depicts that the cluster is getting upgraded: External Cluster Reconciling State

Running state depicts that the cluster is healthy: External Cluster Provisioning State

Deleting state depicts that the cluster is getting deleted:

External Cluster Delete State

Disconnect Cluster

Disconnect operation does not delete the cluster from the cloud provider.

You can Disconnect an external cluster by clicking on the disconnect icon next to the cluster you want to disconnect or from the cluster details page, which will delete internal cluster object in KKP.

Disconnect External Cluster

Disconnect External Cluster on Details Page

Disconnect Dialog

Delete Cluster

Delete Cluster displays information in case nodes are attached

Delete External Cluster