Skip to content

Custom CAPI provider template creation in the airgapped environment#

Sometimes you need to use a CAPI provider that is not part of official Mirantis k0rdent Enterprise release in the airgapped environment.

For general the process regarding creating your own templates, you can follow the Bring Your Own templates guide.

This is a more in-depth guide to creating a custom provider template, specific to an airgapped environment.

Implementing your own custom provider template typically involves the following steps:

  • Helm chart creation
  • Providing dependencies
  • Creation of k0rdent specific objects

This guide will use the Vsphere infrastructure provider as a concrete example, even though it's included in the default Mirantis k0rdent Enterprise installation.

Helm chart creation#

A Helm chart can contain the provider resources directly, or it can use CAPI Operator objects. It is a convention in Mirantis k0rdent Enterprise to use CAPI Operator resources for ease of maintenance and more concise definitions.

Chart.yaml and values conventions#

For provider templates, the global.registry value is used by the system to pass global custom registry configuration, and Mirantis k0rdent Enterprise expects that all provider templates support it.

For example, here is the infrastructure provider definition: 

{{- $global := .Values.global | default dict }}
{{- $version := .Chart.AppVersion }}
apiVersion: operator.cluster.x-k8s.io/v1alpha2
kind: InfrastructureProvider
metadata:
  name: vsphere
spec:
  version: {{ $version }}
  fetchConfig:
    oci: {{ $global.registry }}/capi/cluster-api-provider-vsphere-components:{{ $version }}
  deployment:
    containers:
      - name: manager
        imageUrl: {{ $global.registry }}/capi/cluster-api-vsphere-controller:{{ $version }}

Chart.yaml must include annotations for Compatibility Attributes. For example:

apiVersion: v2
name: cluster-api-provider-vsphere
description: A Helm chart for Cluster API provider vSphere
type: application
version: 1.0.0
appVersion: "v1.13.0"
annotations:
  cluster.x-k8s.io/provider: infrastructure-vsphere
  cluster.x-k8s.io/v1beta1: v1beta1

After the chart is created, you can package it using:

helm package cluster-api-provider-vsphere

The resulting file cluster-api-provider-vsphere-1.0.0.tgz should be transferred to the airgapped environment.

After it's transferred, upload it to the registry where all the rest of artifacts are uploaded (e.g. registry.local/k0rdent-enterprise):

export REGISTRY="registry.local/k0rdent-enterprise"
helm push cluster-api-provider-vsphere-1.0.0.tgz oci://${REGISTRY}/charts

Providing dependencies#

To install a new provider in the airgapped environment, its dependencies must also be present in the airgapped environment. In our case it's a vsphere controller image and CAPI Provider components.

The controller image can be copied in any convenient way, but the CAPI components require a separate process which is explained in the following section.

Preparing CAPI components image#

The CAPI Operator expects to find the provider's components in several places but the OCI images are used conventionally in Mirantis k0rdent Enterprise.

To prepare the image you must download provider components (such as infrastructure-components.yaml) and metadata.yaml. You can download these from the official provider release page.

After downloading, these files must be transferred to the airgapped environment, where they can be uploaded to the registry using oras.

Note

In the following example we have a directory called vsphere-components that contains only infrastructure-components.yaml and metadata.yaml, which were downloaded from vsphere provider releases page Also note that path matches the one defined in the chart.

cd vsphere-components
oras push ${REGISTRY}/capi/cluster-api-provider-vsphere-components:v1.13.0 *

Creation of k0rdent-specific objects#

Several k0rdent objects must be edited/created before you can use the custom provider template can be used.

Provider template#

When all charts and components are uploaded, you can create the ProviderTemplate object:

apiVersion: k0rdent.mirantis.com/v1beta1
kind: ProviderTemplate
metadata:
  name: cluster-api-provider-vsphere-1-0-0
  namespace: kcm-system
spec:
  helm:
    chartSpec:
      chart: cluster-api-provider-vsphere
      interval: 10m0s
      reconcileStrategy: ChartVersion
      sourceRef:
        kind: HelmRepository
        name: kcm-templates
      version: 1.0.0

After you apply the ProviderTemplate object, check that it is valid:

kubectl -n kcm-system get providertemplate cluster-api-provider-vsphere-1-0-0
NAME                                 VALID
cluster-api-provider-vsphere-1-0-0   true

Management#

When the template is ready, edit the Management object to tell Mirantis k0rdent Enterprise to use the custom provider template instead of the one pre-defined in the Release. To do that, edit the Management object using:

kubectl edit mgmt kcm

Then, under .spec.providers, edit the provider represented by the custom template and add the new template name:

apiVersion: k0rdent.mirantis.com/v1beta1
kind: Management
metadata:
  name: kcm
spec:
  providers:
  - name: cluster-api-provider-vsphere
    template: cluster-api-provider-vsphere-1-0-0

Finally, make sure that the Management object has transitioned to Ready status:

kubectl get mgmt
NAME   READY   RELEASE                    AGE
kcm    True    k0rdent-enterprise-1-1-0   53m