Adding a `Service` to a `ClusterDeployment`#

To add the service defined by this template to a cluster, you simply add it to the ClusterDeployment object when you create it, as in:

apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterDeployment
metadata:
  name: my-cluster-deployment
  namespace: tenant42
spec:
  config:
    clusterLabels: {}
  template: aws-standalone-cp-1-0-20
  credential: aws-credential
  serviceSpec:
    services:
      - template: project-ingress-nginx-4.11.0
        name: ingress-nginx
        namespace: tenant42
    priority: 100

As you can see, you're simply referencing the template in the .spec.serviceSpec.services[].template field of the ClusterDeployment to tell Mirantis k0rdent Enterprise that you want this service to be part of this cluster.

If you wanted to add this service to an existing cluster, you would simply patch the definition of the ClusterDeployment, as in:

kubectl patch clusterdeployment my-cluster-deployment -n tenant42 --type='merge' -p '
spec:
  serviceSpec:
    services:
      - template: project-ingress-nginx-4.11.0
        name: ingress-nginx
        namespace: tenant42

Let's look at a more complex case, involving deploying beach-head services on a single cluster.

Installing cert-manager on Child Clusters#

cert-manager is a common requirement for many services deployed on k0rdent child clusters. It provides automatic certificate management and is often required by services that use webhooks (such as HCO, Kyverno, and others). This section explains how to install cert-manager version 1.18.x on your child clusters.

Checking if cert-manager is Already Installed#

To determine whether cert-manager is already deployed on a cluster, check the ClusterDeployment:

kubectl describe ClusterDeployment <CLUSTER-NAME> -n <CLUSTER-NAMESPACE>

For example, if you've created a ClusterDeployment named my-cluster in the kcm-system namespace:

kubectl describe ClusterDeployment my-cluster -n kcm-system

Look for cert-manager in the services list:

...
      - name: cert-manager
        namespace: cert-manager
        template: cert-manager-1-18-1
        values: |
          cert-manager:
            crds:
              enabled: true
...

Adding cert-manager to a New ClusterDeployment#

When creating a new cluster, include cert-manager in the serviceSpec.services array:

apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterDeployment
metadata:
  name: my-cluster
  namespace: kcm-system
spec:
  template: <your-cluster-template>
  credential: <your-credential>
  serviceSpec:
    services:
      - name: cert-manager
        namespace: cert-manager
        template: cert-manager-1-18-1
        values: |
          cert-manager:
            crds:
              enabled: true

Important: The cert-manager.crds.enabled: true setting is required to ensure that cert-manager CRDs are properly installed.

Adding cert-manager to an Existing ClusterDeployment#

To add cert-manager to an existing cluster, you can either use the k0rdent Catalog or add it manually.

Option 1: Using the k0rdent Catalog#

You can add cert-manager from the k0rdent Catalog.

Option 2: Manual Installation via Patch#

Create a patch file called clusterdeployment-patch.yaml:

spec:
  serviceSpec:
    services:
      - name: cert-manager
        namespace: cert-manager
        template: cert-manager-1-18-1
        values: |
          cert-manager:
            crds:
              enabled: true
    # continueOnError: true  # uncomment for troubleshooting

Then, with your KUBECONFIG pointing at the management cluster, apply the patch:

For standard k0rdent child clusters:

kubectl patch clusterdeployment <CLUSTER-NAME> -n kcm-system --type=merge --patch-file clusterdeployment-patch.yaml

For MKE 4k: Services must be added through the MKE Config CR instead of patching ClusterDeployment directly. See the MKE 4k Installation section below.

Wait for the ClusterDeployment to be ready:

kubectl get clusterdeployments -A

MKE 4k Installation#

Important: For MKE 4k environments (self-adopted clusters), services must be added through the MKE Config CR (MkeConfig), not by directly patching the ClusterDeployment. The MKE Config CR is the source of truth for services on MKE 4k clusters.

Get the MKE Config:

kubectl get mkeconfigs.mke.mirantis.com -n mke

Edit the MKE Config to add cert-manager:
```
kubectl edit mkeconfig mke -n mke
```
Add cert-manager to the spec.services array:

apiVersion: mke.mirantis.com/v1alpha1
kind: MkeConfig
metadata:
  name: mke
  namespace: mke
spec:
  ...
  services:
    - name: cert-manager
      namespace: cert-manager
      template: cert-manager-1-18-1
      values: |
        cert-manager:
          crds:
            enabled: true
  ...

After saving the MKE Config, verify that cert-manager has been added to the ClusterDeployment:

kubectl get clusterdeployment <cluster-name> -n k0rdent -o jsonpath='{.spec.serviceSpec.services[*].name}' | tr ' ' '\n'

You should see cert-manager in the list.

Why this matters: Directly patching the ClusterDeployment with kubectl patch will be reverted by the Helm chart reconciliation process in MKE 4k. The Helm chart that manages adopted clusters reconciles periodically and resets the ClusterDeployment spec to match the MKE Config CR.

For more information on adding services in MKE 4k, refer to the MKE 4k Add Services Documentation.

Adding a Service to a ClusterDeployment#