clusterctl init

The clusterctl init command installs the Cluster API components and transforms the Kubernetes cluster into a management cluster.

This document provides more detail on how clusterctl init works and on the supported options for customizing your management cluster.

Defining the management cluster

The clusterctl init command accepts in input a list of providers to install.

Automatically installed providers

The clusterctl init command automatically adds the cluster-api core provider, the kubeadm bootstrap provider, and the kubeadm control-plane provider to the list of providers to install. This allows users to use a concise command syntax for initializing a management cluster. For example, to get a fully operational management cluster with the aws infrastructure provider, the cluster-api core provider, the kubeadm bootstrap, and the kubeadm control-plane provider, use the command:

clusterctl init --infrastructure aws

Provider version

The clusterctl init command by default installs the latest version available for each selected provider.

Target namespace

The clusterctl init command by default installs each provider in the default target namespace defined by each provider, e.g. capi-system for the Cluster API core provider.

See the provider documentation for more details.

Watching namespace

The clusterctl init command by default installs each provider configured for watching objects in all namespaces.

Multi-tenancy

Multi-tenancy for Cluster API means a management cluster where multiple instances of the same provider are installed.

The user can achieve multi-tenancy configurations with clusterctl by a combination of:

  • Multiple calls to clusterctl init;
  • Usage of the --target-namespace flag;
  • Usage of the --watching-namespace flag;

The clusterctl command officially supports the following multi-tenancy configurations:

A management cluster with n (n>1) instances of an infrastructure provider, and only one instance of Cluster API core provider, bootstrap provider and control plane provider (optional).

For example:

  • Cluster API core provider installed in the capi-system namespace, watching objects in all namespaces;
  • The kubeadm bootstrap provider in capbpk-system, watching all namespaces;
  • The kubeadm control plane provider in cacpk-system, watching all namespaces;
  • The aws infrastructure provider in aws-system1, watching objects in aws-system1 only;
  • The aws infrastructure provider in aws-system2, watching objects in aws-system2 only;
  • etc. (more instances of the aws provider)
A management cluster with n (n>1) instances of the Cluster API core provider, each one with a dedicated instance of infrastructure provider, bootstrap provider, and control plane provider (optional).

For example:

  • A Cluster API core provider installed in the capi-system1 namespace, watching objects in capi-system1 only, and with:
    • The kubeadm bootstrap provider in capi-system1, watching capi-system1;
    • The kubeadm control plane provider in capi-system1, watching capi-system1;
    • The aws infrastructure provider in capi-system1, watching objects capi-system1;
  • A Cluster API core provider installed in the capi-system2 namespace, watching objects in capi-system2 only, and with:
    • The kubeadm bootstrap provider in capi-system2, watching capi-system2;
    • The kubeadm control plane provider in capi-system2, watching capi-system2;
    • The aws infrastructure provider in capi-system2, watching objects capi-system2;
  • etc. (more instances of the Cluster API core provider and the dedicated providers)

Provider repositories

To access provider specific information, such as the components YAML to be used for installing a provider, clusterctl init accesses the provider repositories, that are well-known places where the release assets for a provider are published.

See clusterctl configuration for more info about provider repository configurations.

Variable substitution

Providers can use variables in the components YAML published in the provider’s repository.

During clusterctl init, those variables are replaced with environment variables or with variables read from the clusterctl configuration.

Additional information

When installing a provider, the clusterctl init command executes a set of steps to simplify the lifecycle management of the provider’s components.

  • All the provider’s components are labeled, so they can be easily identified in subsequent moments of the provider’s lifecycle, e.g. upgrades. 
labels:
- clusterctl.cluster.x-k8s.io: ""
- cluster.x-k8s.io/provider: "<provider-name>"
  • An additional Provider object is created in the target namespace where the provider is installed. This object keeps track of the provider version, the watching namespace, and other useful information for the inventory of the providers currently installed in the management cluster.