Deploy Hosted Control Plane Components in an External cluster#

Warning

This feature is supported starting with k0smotron v1.7.0 and k0rdent Enterprise v1.2.0.

Mirantis k0rdent Enterprise supports deploying hosted control plane components into an external Kubernetes cluster.

By default, k0smotron deploys control plane components into the management cluster or the regional cluster (when deployed in a Region). But when the spec.kubeconfigRef field is specified in a K0smotronControlPlane object, the control plane components are instead deployed into the cluster referenced by the provided kubeconfig.

Prerequisites#

To deploy hosted control plane components in an external cluster, you need:

An existing Kubernetes cluster where the control plane components will be deployed. This cluster must meet the following requirements:
- Be accessible from the management or regional cluster.
- Have a CSI provider installed to support persistent storage for managed clusters (optional when using an external database).
- Have a LoadBalancer provider to ensure high availability of the control plane (optional when using an API server Service type other than LoadBalancer).
- The namespace where the control plane components will be deployed (where the K0smotronControlPlane object will be created) must exist in the external cluster before creating the ClusterDeployment.
A Kubernetes Secret containing the kubeconfig for that cluster, created in the management cluster or regional cluster (when deployed in a Region). The identity associated with that kubeconfig must have sufficient RBAC permissions to allow k0smotron to create and manage control plane resources in the target cluster. You can review the RBAC roles required by k0smotron here.
A ClusterTemplate used by the ClusterDeployment that references a Helm chart configured to set the K0smotronControlPlane spec.kubeconfigRef field correctly.

ClusterTemplate and Helm Chart Configuration#

The K0smotronControlPlane spec.kubeconfigRef field contains the following subfields:

name - Name of the Secret containing the kubeconfig. Required.
namespace - Namespace of the Secret containing the kubeconfig. Required.
key - Key within the Secret where the kubeconfig is stored. Defaults to value.

The helm chart must be adapted to consume kubeconfigRef values in order to properly configure the K0smotronControlPlane object. See examples below for details.

Example: K0smotronControlPlane `spec.kubeconfigRef` Configuration#

apiVersion: controlplane.cluster.x-k8s.io/v1beta1
kind: K0smotronControlPlane
metadata:
  name: {{ include "k0smotroncontrolplane.name" . }}
spec:
  kubeconfigRef:
    name: {{ .Values.kubeconfigRef.name }}
    key: {{ .Values.kubeconfigRef.key }}
    namespace: {{ .Values.kubeconfigRef.namespace }}
  ...

Example: ClusterTemplate `kubeconfigRef` Configuration in values.yaml#

  kubeconfigRef:
    name: ""
    namespace: ""
    key: ""

Note

The parameter name in values.yaml is not significant. However, the values must be correctly mapped to the corresponding fields in K0smotronControlPlane spec.kubeconfigRef.

Example: Secret with the kubeconfig of the External Cluster#

apiVersion: v1
kind: Secret
metadata:
  name: external-cluster-kubeconfig
  namespace: test-namespace
type: Opaque
data:
  kubeconfig: <BASE64_ENCODED_KUBECONFIG>

Example: ClusterDeployment configuration with the External Cluster used to hosted Control Plane components#

Warning

The example below assumes that the referenced ClusterTemplate is configured to set the K0smotronControlPlane spec.kubeconfigRef field based on the values provided in the ClusterDeployment spec.config.kubeconfigRef field. Please ensure that your ClusterTemplate is configured accordingly.

apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterDeployment
metadata:
  name: test-cluster
  namespace: kcm-system
spec:
  template: custom-hosted-cp-1-0-22
  credential: test-credential
  config:
    kubeconfigRef:
      name: external-cluster-kubeconfig
      namespace: test-namespace
      key: kubeconfig