Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.

Tip

Which providers can I use?

You can use the clusterctl config repositories command to get a list of supported providers and their repository configuration.

If the provider of your choice is missing, you can customize the list of supported providers by using the clusterctl configuration file.

Important! The Cluster API project supports ecosystem growth and extensibility. The clusterctl CLI carries a list of predefined providers sponsored by SIG Cluster Lifecycle, and out-of-organization third party open-source repositories. Each repository is the responsibility of the respective maintainers, including their quality standards and support.

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

Tip

Is it possible to skip automatic install?

To skip automatic provider installation use --bootstrap "-" or --control-plane "-". Note it is not possible to skip automatic installation of the cluster-api core provider.

Warning

The cluster-api core provider, the kubeadm bootstrap provider, and the kubeadm control-plane provider are automatically installed only if:

  • The user doesn’t explicitly require to install a core/bootstrap/control-plane provider using the --core flag, the --bootstrap flag or the --control-plane flags;
  • There is not an instance of a CoreProvider already installed in the cluster;

Please note that the second rule allows to execute clusterctl init more times: the first call actually initializes the management cluster, while the subsequent calls can be used to add more providers.

Provider version

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

Tip

Is it possible to install a specific version of a provider?

You can specify the provider version by appending a version tag to the provider name, e.g. aws:v0.4.1.

Pinning the version provides better control over what clusterctl chooses to install (usually required in an enterprise environment). Version pinning should always be used when using image overrides, or when relying on internal repositories with a separated software supply chain, or a custom versioning schema.

Warning

Pre-release provider versions

clusterctl init does not install pre-release versions by default. For example, if a provider has releases v0.7.0-alpha.0 and v0.6.6, the latest release installed will be v0.6.6.

You can specify the provider version by appending a version tag to the provider name, e.g. vsphere:v0.7.0-alpha.0.

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.

Tip

Is it possible to change the target namespace ?

You can specify the target namespace by using the --target-namespace flag.

Please, note that the --target-namespace flag applies to all the providers to be installed during a clusterctl init operation.

Warning

The clusterctl init command forbids users from installing two instances of the same provider in the same target namespace.

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.

Tip

Is it possible to override files read from a provider repository?

If, for any reasons, the user wants to replace the assets available on a provider repository with a locally available asset, the user is required to save the file under $XDG_CONFIG_HOME/cluster-api/overrides/<provider-label>/<version>/<file-name.yaml>.

$XDG_CONFIG_HOME/cluster-api/overrides/infrastructure-aws/v0.5.2/infrastructure-components.yaml

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.

Important

The user should ensure the variables required by a provider are set in advance.

Tip

How can I know which variables a provider requires?

Users can refer to the provider documentation for the list of variables to be set or use the clusterctl generate provider --<provider-type> <provider-name> --describe command to get a list of expected variable names.

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, and other useful information for the inventory of the providers currently installed in the management cluster.

Caution

The clusterctl.cluster.x-k8s.io labels, the cluster.x-k8s.io/provider labels and the Provider objects MUST NOT be altered. If this happens, there are no guarantees about the proper functioning of clusterctl.

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.21.2). See clusterctl configuration for available options to customize this operation.

Note

Please note that, if clusterctl installs cert-manager, it will take care of its lifecycle, eventually upgrading it during clusterctl upgrade. Instead, if cert-manager is provided by the users, the user is responsible for upgrading this component when required.

Avoiding GitHub rate limiting

Follow this