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.
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.
Per default 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 https://proxy.golang.org).
To immediately fallback to the GitHub client and not use a go proxy, the environment variable could get set to
GOPROXY=off or GOPROXY=direct.
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.
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
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.
Cert-manager
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.12.2). See clusterctl configuration for available options to customize this operation.
Avoiding GitHub rate limiting
Follow this