Skip to content

External DataBase Support for Hosted Control Plane Clusters#

Mirantis k0rdent Enterprise supports using a custom data store for hosted control plane clusters.

Typically, a Kubernetes control plane uses only etcd as the datastore. k0rdent Enterprise, however, supports additional datastore options alongside etcd by leveraging kine, which is supported by k0s. Kine enables the use of a wide variety of backend data stores. In k0rdent, this is configured via the DataSource custom resource.

DataSource Resource#

DataSource Example#

apiVersion: k0rdent.mirantis.com/v1beta1
kind: DataSource
metadata:
  name: example-postgresql
  namespace: kcm-system
spec:
  type: postgresql
  endpoints:
  - 172.19.115.87:5432
  auth:
    username:
      namespace: kcm-system
      name: auth-secret
      key: username
    password:
      namespace: kcm-system
      name: auth-secret
      key: password
  certificateAuthority:
    namespace: kcm-system
    name: db-ca-secret
    key: ca.crt

Auth Secret Example#

apiVersion: v1
kind: Secret
metadata:
  name: auth-secret
  namespace: kcm-system
data:
  password: <BASE64_ENCODED_PASSWORD>
  username: <BASE64_ENCODED_USERNAME>

CA Certificate Secret Example#

apiVersion: v1
data:
  ca.crt: <BASE64_ENCODED_CA_CERT>
kind: Secret
metadata:
  name: db-ca-secret
  namespace: kcm-system
type: Opaque

Supported Fields#

  • spec.type - The database type used by the data source. Currently, the only supported value is postgresql. Required.

  • spec.endpoints - One or more host/port pairs that clients use to connect to the data source. Required.

  • spec.auth - Authentication configuration for accessing the data source. This section contains references to Secret(s) that store the credentials (username and password) used to establish a connection to the external data source. Each field is a reference to a Secret key containing the admin username or password for the data source. Required.

  • spec.certificateAuthority - Optional reference to a Secret containing the certificate authority (CA) certificate used to verify the data source’s server certificate during the TLS handshake. For endpoints whose certificates are issued by a trusted CA already present in the system trust store, this field can be omitted.

Note

If spec.certificateAuthority is omitted in the DataSource and the endpoint's certificate is self-signed, it is the user’s responsibility to add this certificate to the system’s root CAs. k0rdent will not perform this action.

Configuring an External DataSource for Hosted ClusterDeployments#

To use a custom DataSource for a hosted ClusterDeployment, set the spec.dataSource field to the name of an existing DataSource object in the same namespace. For example:

apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterDeployment
metadata:
  name: cluster-name
  namespace: kcm-system
spec:
  template: openstack-hosted-cp-1-0-12
  credential: openstack-cluster-identity-cred
  dataSource: example-postgresql

Data Source Processing#

When spec.dataSource is configured in the ClusterDeployment and the referenced DataSource exists, the k0rdent Enterprise controllers performs the following:

  1. KCM controller generates a schema name in the format:

    kine_<cldNamespace>_<cldName>_<randomHash>

    where cldNamespace is the namespace of the ClusterDeployment and cldName is the name of the ClusterDeployment.

  2. Creates a custom ClusterDataSource object in the cluster's namespace. The ClusterDataSource has the same name as the ClusterDeployment and the KCM controller waits for the ClusterDataSource controller to reconcile it. Example:

    apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterDataSource
metadata:
  creationTimestamp: "2025-12-01T20:28:14Z"
  finalizers:
  - k0rdent.mirantis.com/cluster-data-source
  generation: 1
  labels:
    k0rdent.mirantis.com/component: kcm
    k0rdent.mirantis.com/managed: "true"
  name: cluster-name
  namespace: kcm-system
  ownerReferences:
  - apiVersion: k0rdent.mirantis.com/v1beta1
    blockOwnerDeletion: true
    controller: true
    kind: ClusterDeployment
    name: cluster-name
    uid: 173e6e6b-4dcb-4308-9fec-6a4b839653d1
  resourceVersion: "12416"
  uid: 650fa8e3-608a-493d-b15a-ce04c5204faf
spec:
  dataSource: example-postgresql
  schema: kcm_system_cluster-name_9fvwr
status:
  caSecret: cluster-name-kine-ca
  kineDataSourceSecret: cluster-name-kine
  observedGeneration: 1
  ready: true

  3. The ClusterDataSources controller performs all required operations on the database. For details see Integration with the Data Source.

  4. Once the ClusterDataSource status is ready, the KCM controller proceeds with cluster deployment as usual, automatically passing the kine configuration parameters to the HelmRelease values used by the ClusterTemplate. The Helm chart of the ClusterTemplate must be adapted to consume these values in order to properly configure the control plane objects. See Integration with ClusterTemplates for details.

Integration with the Data Source#

Creation Flow#

When spec.dataSource is configured in the ClusterDeployment and the referenced DataSource exists, the k0rdent Enterprise ClusterDataSource controller performs the following:

  1. Generates the name of the user that will be used by kine in the format kine_<cldNamespace>_<cldName>_<randomHash> where cldNamespace is the namespace of the ClusterDeployment, the cldName is the name of the ClusterDeployment.

  2. Generates a secure password for the user.

  3. Using the admin credentials provided in the DataSource object, the ClusterDataSource controller creates the database, creates the user generated in step 1 and grants all required privileges on the database, schemas and tables to this user.

  4. Creates a Secret with name <cldName>-kine that contains the kine data source URL, where <cldName> is the name of the ClusterDeployment.

The format of the kine datasource URL is:

postgres://<USERNAME>:<PASSWORD>@<ADDRESS>:<PORT>/<DATABASE_NAME>?sslmode=verify-full&sslrootcert=/var/lib/k0s/kine-ca/ca.crt

If a CA certificate was not provided, the URL is:

postgres://<USERNAME>:<PASSWORD>@<ADDRESS>:<PORT>/<DATABASE_NAME>?sslmode=verify-full

Note

If spec.certificateAuthority is omitted in the DataSource and the endpoint's certificate is self-signed, it is the user’s responsibility to add this certificate to the system’s root CAs. k0rdent will not perform this action.

Example:

postgres://kine_kcm_system_cluster-name_9fvwr:8w86f9c9pbp9nsjz9chbbj8z8khkqd5b@172.19.115.87:5432/kcm_system_cluster-name_9fvwr?sslmode=verify-full&sslrootcert=/var/lib/k0s/kine-ca/ca.crt

Deletion Flow#

When the ClusterDeployment is deleted, the ClusterDataSource controller revokes all privileges from the kine user and deletes the user. The database itself is not deleted.

Integration with ClusterTemplates#

When spec.dataSource is defined in the ClusterDeployment, the referenced DataSource exists, and the ClusterDataSource controller has successfully configured the database, the KCM controller automatically passes the required dataSource values to the HelmRelease responsible for deploying the cluster:

dataSource:
  kineDataSourceSecretName: <KINE_DATASOURCE_SECRET_NAME>
  caSecret:
    name: <KINE_DATASOURCE_CA_SECRET_NAME>
    key: <KINE_DATASOURCE_CA_SECRET_KEY>

for example:

dataSource:
  kineDataSourceSecretName: "cluster-name-kine"
  caSecret:
    name: "cluster-name-kine-ca"
    key: "ca.crt"
  • dataSource.kineDataSourceSecretName - Name of the Secret containing the kine data source URL. This Secret is created automatically.
  • dataSource.caSecret.name - Name of the Secret that stores the CA certificate.
  • dataSource.caSecret.key - Key within the Secret where the CA certificate is stored.

The ClusterTemplate must consume these values to configure the control plane components correctly. In particular, the K0smotronControlPlane must:

  1. Mount the CA certificate Secret into the control plane pods at /var/lib/k0s/kine-ca/ca.crt, and
  2. Set the kineDataSourceSecretName parameter to the name of the Secret that contains the kine data source URL.

Example: K0smotronControlPlane Data Source Configuration#

spec:
  k0sConfig:
    apiVersion: k0s.k0sproject.io/v1beta1
    kind: ClusterConfig
    metadata:
      name: k0s
    spec:
      mounts:
      {{- if .Values.dataSource.caSecret.name }}
      - path: /var/lib/k0s/kine-ca
        secret:
          defaultMode: 420
          items:
            - key: {{ .Values.dataSource.caSecret.key }}
              path: ca.crt
          secretName: {{ .Values.dataSource.caSecret.name }}
      {{- end }}
      {{- if .Values.dataSource.kineDataSourceSecretName }}
      kineDataSourceSecretName: {{ .Values.dataSource.kineDataSourceSecretName }}
      {{- end }}

Troubleshooting#

If you attempt to delete a cluster with the wrong database password, the cluster deletion will get stuck on the step Waiting for clusterdatasource to be deleted.

To solve this problem, delete the finalizers in the ClusterDataSource. Once the finalizers are deleted the object should be removed, and the cluster will continue deleting.