In-Depth Guide to Cluster API Operator Provider Specification

Concise Class Diagram for https://github.com/kubernetes-sigs/cluster-api-operator/tree/main/api/v1alpha2

In the last article, we explored different types of Providers supported by Cluster API Operator, In this article, we will deep dive into ProviderSpec which acts as a single way to qualify for Provider Specification. All Providers

• CoreProvider

• BootstrapProvider

• ControlplaneProvider

• InfrastructureProvider

• IPAMProvider

• AddonProvider

via their respective composition extend ProviderSpec and implement GenericProvider interface.

Let’s dive into ProviderSpec further

Version

a valid release version for the provider complaint to semver.

Manager

ManagerSpec Class Diagram

ManagerSpec allows users to specify various ControllerManager options. basically these options let user control almost all the command line arguments which are passed down to manager reconcile to be used by ControllerRuntime initialization. These specs are excellent way fine tune ControllerRuntime properties for your manager.

Sample ManagerSpec Object

Deployment

DeploymentSpec Class Diagram

What ManagerSpec is to ControllerRuntime options, DeploymentSpec is for Kubernetes Deployment options for the Provider Deployment. It allows management of deployment scale, NodeSelector and other options.

Sample DeploymentSpec Object

ConfigSecret — & — AdditionalManifestRef

Class Diagram SecretReference & ConfigmapReference

ConfigSecret

ConfigSecret is a secret-backed store for provider values. It is an immutable property store, if changes are required the secret name must change. ConfigSecret namespace must match the Provider namespace.

AdditionalManifestRef

AdditionalManifestRef is a configmap-backed store for additional manifest which we might want to install along with our provider. AdditionalManifestRef content is applied only when there is a Provider install or upgrade operation. AdditionalManifestRef is treated opaque by Cluster API Operator no validation is performed on the content. Contents of AdditionalManifestRef configmap must be under manifests key [sample].

FetchConfiguration

FetchConfiguration Class Diagram

FetchConfiguration allows users to specify a location for provider artefacts from two locations online | URL and offline | Selector

• [Online | URL ]— allows users to mention a URL in the form of https://github.com/{owner}/{repository}/releases. The release version is picked up from ProviderSpec.Version and must be set when the URL is specified.

• [Offline | Selector] — allows users to specify components and metadata for a provider to be stored within a configmap and fetched from the same. Configmap name must be equal to the version of the Provider e.g. v1.4.3 or a label must be present on the configmap provider.cluster.x-k8s.io/version=v1.4.3 . The cluster API Operator book provides an excellent way to specify and create these configmaps here.

ManifestPatches

Patch customization allows us to tag/modify Provider Custom Resource to our need

ManifestPatches are additional patch capabilities that are allowed to inject or modify rendered Provider manifest with JSON merge patches array.

Sample CoreProvider with ManifestPatches

There are a couple of rules for the patch to match a manifest: [Source]

• Each patch is applied in the same order specified in the array

• The kind field must match the target object.

• If apiVersion is specified it will only be applied to matching objects.

• If metadata.name and metadata.namespace not specified, the patch will be applied to all objects of the specified kind.

• If metadata.name is specified, the patch will be applied to the object with the specified name. This is for cluster-scoped objects.

• If both metadata.name and metadata.namespace are specified, the patch will be applied to the object with the specified name and namespace.

AdditionalDeployments

AdditionalDeployments Class Diagram

Cluster API Operator allows the management of extra deployments like the primary Provider manager, deployments are specified by name and AdditionalDeploymentSpec allows users to provideControllerManager and Kubernetes Deployment changes.

This concludes our third article, we now have a good enough understanding of how the ProviderSpec is laid out and some sample inputs. We will explore Provider lifecycle events such as installation, upgrade and deletion. How to update ConfigSecret? Will the Cluster API Operator take care of restarting my manager when ConfigSecret is rotated? Answers to that are in the next article.