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
clusterctl init command accepts in input a list of providers to install.
clusterctl init command automatically adds the
cluster-api core provider, the
kubeadm bootstrap provider, and
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
clusterctl init command by default installs the latest version available
for each selected provider.
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.
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.
clusterctl will use a go proxy to detect the available versions to prevent additional
API calls to the GitHub API. It is possible to configure the go proxy url using the
GOPROXY variable as
for go itself (defaults to
To immediately fallback to the GitHub client and not use a go proxy, the environment variable could get set to
If a provider does not follow Go’s semantic versioning,
clusterctl may fail when detecting the correct version.
In such cases, disabling the go proxy functionality via
GOPROXY=off should be considered.
See clusterctl configuration for more info about provider repository configurations.
Providers can use variables in the components YAML published in the provider’s repository.
clusterctl init, those variables are replaced with environment variables or with variables read from the
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
Providerobject is created in the target namespace where the provider is installed. This object keeps track of the provider version, and other useful information for the inventory of the providers currently installed in the management cluster.
Cluster API providers require a cert-manager version supporting the
cert-manager.io/v1 API to be installed in the cluster.
While doing init, clusterctl checks if there is a version of cert-manager already installed. If not, clusterctl will install a default version (currently cert-manager v1.13.1). See clusterctl configuration for available options to customize this operation.