clusterctl Variables¶

clusterctl replaces shell-style ${NAME} and ${NAME:=default} references in the CAPTF templates with environment variables. A variable with no default and no value makes clusterctl generate fail, so a missing name never deploys something you did not ask for.

The provider ships three templates:

Both cluster flavors read the same variables, so the first table covers them. The identity template reads two. See Templates and ClusterClass for what each flavor creates and Quick Start for a full walkthrough.

Cluster flavors: default and clusterclass¶

Both templates read every variable below. Variables marked as set by a clusterctl generate cluster option need no export.

Identity and module images¶

Cluster shape¶

Health check timeouts¶

Each timeout is in seconds. They tune the two MachineHealthChecks: one for the control plane and one for workers. In the clusterclass flavor they set the same fields on the Cluster topology.

Identity template¶

identity.yaml is not a flavor. An admin applies it once per set of credentials, with clusterctl generate yaml:

The generated Secret holds placeholder keys. Replace them with the environment variables your module’s providers read. See Identities and Credentials.

export TERRAFORM_IDENTITY_NAME=<identity-name> NAMESPACE=<namespace>
clusterctl generate yaml --from templates/identity.yaml | kubectl apply -f -

Replace <identity-name> with the name clusters reference, and <namespace> with the namespace they live in.

Generate a cluster¶

Export the required variables that no option sets, then generate. This example uses the default flavor and overrides two optional values:

export TERRAFORM_IDENTITY_NAME=<identity-name> \
  TERRAFORM_CLUSTER_IMAGE=<cluster-module-image> \
  TERRAFORM_MACHINE_IMAGE=<machine-module-image> \
  POD_CIDR=<pod-cidr> \
  TERRAFORM_UNHEALTHY_TIMEOUT=<seconds>

clusterctl generate cluster <cluster-name> --infrastructure terraform \
  --target-namespace <namespace> \
  --kubernetes-version <version> \
  --control-plane-machine-count 3 --worker-machine-count 2 \
  | kubectl apply -f -

Placeholders:

• <identity-name>: an existing TerraformClusterIdentity that allows <namespace>.
• <cluster-module-image> and <machine-module-image>: the module images, for example a tag you built for the cluster and machine roles.
• <pod-cidr> and <seconds>: optional. Leave them out to use the defaults in the tables above.
• <cluster-name>, <namespace> and <version>: the name, the target namespace and the Kubernetes version, such as v1.36.3.

--infrastructure terraform needs the provider registered with clusterctl. To render a template file directly instead, replace it with --from templates/cluster-template.yaml.

To use the clusterclass flavor, apply the class to the namespace once, enable the ClusterTopology feature gate when you register the provider, and add --flavor clusterclass:

kubectl apply -n <namespace> -f templates/clusterclass-noop.yaml
clusterctl generate cluster <cluster-name> --infrastructure terraform \
  --flavor clusterclass --target-namespace <namespace> \
  --kubernetes-version <version> \
  --control-plane-machine-count 3 --worker-machine-count 2 \
  | kubectl apply -f -

clusterclass-noop.yaml has no clusterctl variables and no namespace, so apply it to every namespace that generates clusters from it.

ClusterClass topology variables¶

The noop ClusterClass declares three topology variables. The clusterclass flavor fills them from the clusterctl variables above, in Cluster.spec.topology.variables. To change one later, edit the value on the Cluster; you do not edit the class or its templates.

spec:
  topology:
    classRef:
      name: noop
    variables:
    - name: identityName
      value: <identity-name>
    - name: clusterImage
      value: <cluster-module-image>
    - name: machineImage
      value: <machine-module-image>

A *Template kind is immutable once created, so the topology controller rolls a new machineImage out by creating a new TerraformMachineTemplate. See Template immutability and rolling out a change and The noop ClusterClass.