KKP KubeOne Integration

This section describes how to import and manage KubeOne clusters in KKP. We can import/connect an existing KubeOne cluster. Imported Cluster can be viewed and edited.

Currently Supported Providers:


The following requirements must be met to import a KubeOne cluster:

  • The KubeOne cluster must already exist before we begin the import/connect process.
  • KubeOne configuration manifest: YAML manifest file that describes the KubeOne cluster configuration. If you don’t have the manifest of your cluster, it can be generated by running kubeone config dump -m kubeone.yaml -t tf.json from your KubeOne terraform directory.
  • Private SSH Key used to create the KubeOne cluster: KubeOne connects to instances over SSH to perform any management operation.
  • Provider Specific Credentials used to create the cluster.

For more information on the KubeOne configuration for different environments, checkout the Creating the Kubernetes Cluster using KubeOne documentation.

Import KubeOne Cluster

KKP allows connecting any existing KubeOne cluster of supported provider to view and edit the cluster’s current state.

  • To import a KubeOne cluster go to KubeOne Clusters page and Click the Import KubeOne Cluster button.

Import KubeOne Cluster

  • Select the KubeOne cloud provider.

Select Provider

After the cluster has been imported, we can see the details of the cluster in the dashboard.

Cluster Details

KubeOne Cluster List

Cluster Details Page

After the cluster is imported, the KKP controller retrieves the cluster kubeconfig to display all necessary information. A healthy cluster has Running state. Move the mouse cursor over the state indicator to get more details.

Update Cluster

KKP supports latest KubeOne code hence supported Kubernetes version has to be ‘>= 1.24’. If your cluster is running an older Kubernetes version, an older KubeOne version has to be used to upgrade your cluster to a supported version first. Please refer to the KubeOne Compatibility section docs for more details.

Upgrade Cluster Version

When an upgrade for the cluster is available, a little dropdown arrow will be shown beside the Control Plane Version on the cluster’s page. To start the upgrade, choose the desired version from the list of available upgrade versions and click on Change Version.

Upgrade Cluster

If the version upgrade is valid, the cluster state will change to Reconciling.

Update the Machine Deployment Version

Kubelet version on the worker nodes managed by Machine Deployments can be updated as follows:

  • Navigate to the cluster overview, scroll down to machine deployments.

  • Click on the edit icon next to the machine deployment we want to edit.

Update Machine Deployment Version

  • Upgrade Kubelet Version. Select the Kubelet Version from the dropdown to upgrade the machine deployment.

Select Version

Disconnect Cluster

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

We can Disconnect a KubeOne cluster by clicking on the disconnect icon next to the cluster we want to disconnect or from the cluster details page.

Disconnect KubeOne Cluster

Disconnect KubeOne Cluster on Details Page

Disconnect Dialog


To Troubleshoot a failing imported cluster we can Pause cluster by editing the external cluster CR.

# set externalcluster.spec.pause=true
kubectl edit externalcluster xxxxxxxxxx

Once we are done, we can reset the pause flag on the externalcluster:

# set externalcluster.spec.pause=false
kubectl edit externalcluster xxxxxxxxxx