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:
Prerequisites
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.jsonfrom 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.
- The Kubernetes version of the cluster must be supported by the KubeOne version bundled with KKP, see Supported Kubernetes Versions.
- The KKP master cluster must be able to reach the control plane nodes of the KubeOne cluster, or its bastion host, over SSH.
- The control plane hosts must be listed in the manifest. If the manifest sets
sshPrivateKeyFile, it must be~/.ssh/id_rsa, where KKP mounts the uploaded private key, or be removed.
For more information on the KubeOne configuration for different environments, checkout the Creating the Kubernetes Cluster using KubeOne documentation.
Supported Kubernetes Versions
KKP imports and upgrades KubeOne clusters by running KubeOne in jobs on the KKP master cluster, using the KubeOne version bundled with KKP. Only KubeOne clusters on Kubernetes versions supported by that KubeOne version can be imported and upgraded; upgrades are additionally limited to the Kubernetes versions offered by KKP. Clusters on other versions have to be upgraded with the KubeOne CLI first.
This KKP version bundles KubeOne v1.14.3, which supports Kubernetes 1.34 to 1.36.
See the KubeOne Compatibility section for the Kubernetes versions supported by each KubeOne version.
For offline setups, the image quay.io/kubermatic/kubeone:<version> of the bundled KubeOne version has to be available in the registry configured via overwriteRegistry.
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 Clusterspage and Click theImport KubeOne Clusterbutton.
- Select the KubeOne cloud provider.
- See AWS / Google Cloud Provider/Azure/DigitalOcean/Hetzner/OpenStack/vSphere specific documentation for detailed cluster import steps.
After the cluster has been imported, we can see the details of the cluster in the dashboard.
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
Upgrades are performed with the KubeOne version bundled with KKP, see Supported Kubernetes Versions. KubeOne also updates the cluster components, such as the CNI, CCM and CSI, to the defaults of that version. If you also manage the cluster with the KubeOne CLI, use the same KubeOne minor version.
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.
If the version upgrade is valid, the cluster state will change to Reconciling.
All Machine Deployments must run the same Kubernetes minor version as the control plane before the control plane can be upgraded to the next minor version.
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.
- Upgrade Kubelet Version. Select the Kubelet Version from the dropdown to upgrade the machine deployment.
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.
Troubleshoot
Move the mouse cursor over the state indicator of the cluster to see its status message.
KKP runs KubeOne in jobs in the kubeone-<cluster-id> namespace of the master cluster. Check the jobs and the exit code of the failed kubeone container:
kubectl -n kubeone-<cluster-id> get jobs,pods
kubectl -n kubeone-<cluster-id> describe pod <pod-name>
| Exit code | Meaning |
|---|---|
| 13 | SSH error, e.g. the control plane nodes are not reachable over SSH or the SSH key is not accepted |
| 14 | Connection error |
| 15 | Configuration error, e.g. a Kubernetes version that is not supported by the bundled KubeOne version |
The logs of the import job are empty, because the output of kubeone kubeconfig is used as the cluster kubeconfig.
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