How-To Deploy HCO on a Mirantis k0rdent Enterprise Environment#

This guide outlines the step-by-step process for using Mirantis k0rdent Enterprise to deploy the components of Mirantis k0rdent Virtualization on child clusters.

The first step in this process is to deploy the Hyperconverged Cluster Operator (HCO) on the target cluster. The HCO simplifies deployment of additional Mirantis k0rdent Virtualization components such as KubeVirt, CDI, networking, and kubevirt-manager, providing a unified method to manage virtual machine workloads on that child cluster.

Prerequisites#

Before proceeding, ensure you have the following in place:

A deployed k0rdent child cluster with CRDs enabled.
The kubectl utility installed and configured.
kubeconfig files for both the KCM (k0rdent Control Manager) and the child clusters.

cert-manager#

In order for the HCP webhook service to function properly, you need to have cert-manager deployed and enabled on the target child cluster.

To determine whether cert-manager is deployed, describe the ClusterDeployment, as in:

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

For example, if you've created a ClusterDeployment named ksi-managed-cluster in the kcm-system namespace, you'd use:

kubectl describe ClusterDeployment ksi-managed-cluster -n kcm-system

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

If you don't see the cert-manager service, you can go ahead and add it. Start by adding the new spec in a file called clusterdeployment-patch.yaml:

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

Then, with the KUBECONFIG pointing at the management cluster, apply the patch to the cluster to tell it to add this service to the ClusterDeployment:

kubectl patch clusterdeployment ksi-managed-cluster -n kcm-system --type=merge --patch-file clusterdeployment-patch.yaml

Wait for the ClusterDeployment to be ready:

kubectl get clusterdeployments -A

Manifests#

Deploying HCO in a Mirantis k0rdent Enterprise child environment relies on the HCO ServiceTemplate, which you can install from the Mirantis k0rdent Enterprise Catalog:

helm install hco-1-14-5-mira oci://registry.mirantis.com/k0rdent-enterprise/hco-service-template --version 1.14.5-mira -n kcm-system

Verify that the HCO ServiceTemplate has been added and is VALID:

kubectl -n kcm-system get servicetemplate

NAME                      VALID
cert-manager-1-17-1       true
dex-0-19-1                true
external-secrets-0-11-0   true
hco-1-14-5-mira           true
ingress-nginx-4-11-0      true
ingress-nginx-4-11-3      true
kyverno-3-2-6             true
velero-8-1-0              true

The ServiceTemplate manifest directs the deployment of HCO using the Helm chart:

apiVersion: k0rdent.mirantis.com/v1beta1
kind: ServiceTemplate
metadata:
  name: hco-1-14-5-mira
  namespace: kcm-system
spec:
  helm:
    chartSpec:
      chart: hco
      interval: 10m0s
      reconcileStrategy: ChartVersion
      sourceRef:
        kind: HelmRepository
        name: kubevirt-repo
      version: 1.14.5-mira

By specifying the chart version and the reconcile strategy, this template ensures that HCO remains up to date with minimal manual intervention.

Steps#

To deploy HCO, you will add the relevant templates and changes to the management cluster. These changes will then affect the relevant child cluster. To install and verify HCO, follow these steps:

Add HCO Service Definitions to the Clusterdeployment

Integrate HCO into your existing Mirantis k0rdent Enterprise child cluster or include it when creating a new Clusterdeployment object by updating the spec.serviceSpec.services array with the following definition:
```
spec:
  ...
  serviceSpec:
    services:
    - name: hco
      namespace: kubevirt
      template: hco-1-14-5-mira
      values: |
        admission:
          enabled: false
  ...
```
This step links the HCO service definition to the Mirantis k0rdent Enterprise cluster, instructing it to deploy the HCO operator in the kubevirt namespace on the child cluster represented by the ClusterDeployment.
Verify HCO Deployment on the Child Cluster

To verify the installation, switch your KUBECONFIG context to the Mirantis k0rdent Enterprise child cluster and verify the HCO deployment. For example, run:
```
kubectl -n kubevirt get pods
```
Wait until the pod named hyperconverged-cluster-operator-xxxxxxxxxx-xxxxx is in the Ready state.

Monitoring pod status on the child cluster is critical to ensure that the operator is running and ready to manage virtualization components.
Apply the HCO Custom Resource (CR)

Once the HCO operator is ready, apply the HCO CustomResource to the child cluster to activate Mirantis k0rdent Virtualization and its subcomponents (such as network and storage plugins):
```
apiVersion: hco.kubevirt.io/v1beta1
kind: HyperConverged
metadata:
  name: kubevirt-hyperconverged
  namespace: kubevirt
spec:
  featureGates:
    downwardMetrics: true
  infra:
    nodePlacement:
      nodeSelector:
        kubernetes.io/os: linux
  platform: mke4
```
Note

Currently, you must specify platform: mke4 in the HCO CR to properly set up the Mirantis k0rdent Virtualization component on a Mirantis k0rdent Enterprise environment. This option's value may be renamed in the future.

Applying the HCO CR is the final step that triggers the deployment of all virtualization components, ensuring that your cluster is fully equipped to handle VM workloads.