CAPTF v0.1 is released¶

Cluster API Provider Terraform has its first releases. v0.1.0 was tagged on October 5, and v0.1.1 followed a day later. Together they put every part of the project into a versioned, installable form: the provider, the two runtime base images, the 17 reference modules on the Terraform Registry, and a module image for each of them, on both runtimes.

You can install it with clusterctl today and bring up a cluster with the no-op modules on any management cluster. This post covers what shipped, why it is 0.1 and not 1.0, and how every artifact is built, signed and checked, so you can verify it yourself.

Quick Start Release notes

At a glance¶

What shipped¶

v0.1.1 is v0.1.0 plus the linter’s container image and GitHub Action, and two release-pipeline fixes. The manager did not change. If you build or maintain modules, the action is the reason to take it; it has a post of its own.

The modules move on their own schedule. All 17 started at v0.1.0, and the first round of updates landed the next day:

• v0.1.1 of the AWS, Azure and OCI machine pool modules adds autoscaler = "external", which hands a pool to the Kubernetes Cluster Autoscaler; see The Cluster Autoscaler on CAPTF machine pools.
• v0.2.0 of five modules tightens defaults. The AWS, Azure and Google cluster modules reject a /0 in api_allowed_cidrs, the Azure cluster denies the kubelet ports to the rest of the VNet on workers, and the Azure machine and machine pool modules turn boot diagnostics off by default, since the serial console log can include the kubeadm join command.

Install it¶

Register the provider with clusterctl and initialize a management cluster:

providers:
- name: terraform
  type: InfrastructureProvider
  url: https://github.com/captf-io/cluster-api-provider-terraform/releases/download/v0.1.1/infrastructure-components.yaml

clusterctl init --config clusterctl.yaml --infrastructure terraform:v0.1.1

CLUSTER_TOPOLOGY=true clusterctl init --config clusterctl.yaml --infrastructure terraform:v0.1.1

clusterctl init also installs Cluster API’s core, bootstrap and control-plane providers, and cert-manager if it is not there yet. From there the Quick Start brings up a TerraformCluster and a control-plane TerraformMachine with the no-op modules, which need no cloud account.

Why 0.1, not 1.0¶

The version says what has been proven, and what has not:

• The API and the contract are v1alpha1. Every kind and the module contract may still change, and the contract is provisional.
• End-to-end testing is opt-in. Two suites run on a local kind cluster: a foundation suite that installs and checks the stack, and a no-op suite that drives the published no-op modules through real Cluster API objects. They are not part of CI yet.
• Some operations are unexercised. clusterctl upgrade and clusterctl move have not been run against CAPTF.

Known Limitations lists everything else, with a workaround for each where one exists. If you try CAPTF, that page is the one to read first.

How a release is built¶

Releases are built in CI, and every step on the way refuses to go on when the one before it did not finish cleanly. For the provider, as the pipeline now stands on main:

flowchart TD
    T["signed tag vX.Y.Z"] --> G{"green CI run<br/>on that commit?"}
    G -- "no, after 30 min" --> X["stop"]
    G -- yes --> P[release preflight]
    P --> I["build amd64 + arm64,<br/>push manager and tfcapi-lint images"]
    I --> S["cosign sign, SLSA provenance,<br/>SPDX SBOM attestation"]
    S --> C{"both images tagged vX.Y.Z<br/>at the pushed digests?"}
    C -- no --> X
    C -- yes --> A["build assets pinned to the manager digest,<br/>attest them"]
    A --> R["GitHub Release with curated notes"]

Two of these gates are new since v0.1.0, and both came from looking at what the first releases actually did:

• Publish only what CI passed. Publishing used to run on every push to main alongside CI, not after it. Images were published and signed for three commits in a row whose CI failed, and a tag published without checking CI at all. Publishing now runs from a successful CI run on main, builds that run’s exact commit, and moves :edge only while that commit is still main’s head. A tag waits up to 30 minutes for a green run on its commit.
• Check the release before creating it. v0.1.0 shipped without a tfcapi-lint image. The release job now fails, before it creates the Release, unless both images carry :vX.Y.Z at the digests it pushed, and it refuses to build assets without the manager’s digest.

The release notes are no longer a raw git log either: they open with the API and contract versions, the install commands, the image digests and the commands to verify them.

The module repositories release the same way, by tag. A release is a signed, annotated vX.Y.Z tag on main. The Terraform Registry picks it up within about a minute, and once the repository’s checks pass, CI creates the GitHub Release, refusing a lightweight tag, a tag that is not on main and a tag whose signature GitHub cannot verify. Then module-images takes over:

flowchart TD
    R["module release<br/>vX.Y.Z"] --> D["Dependabot bumps<br/>sources/versions.tf"]
    D --> F["fetch the tag,<br/>git verify-tag"]
    F --> B["build and smoke-test,<br/>both runtimes"]
    B --> M[merge to main]
    M --> P["publish and sign<br/>IMAGE:vX.Y.Z-RUNTIME"]

The build fetches each module’s release tag and checks it before using it: it must be an annotated tag, signed by a key in the repository’s hack/allowed_signers, and pointing at the commit being built. An unsigned or wrongly signed tag fails the build.

Verify it yourself¶

Every signature is keyless cosign, issued through GitHub’s OIDC token to the workflow that built the artifact, so you check which workflow signed it rather than holding a key:

cosign verify ghcr.io/captf-io/cluster-api-provider-terraform:vX.Y.Z \
  --certificate-identity https://github.com/captf-io/cluster-api-provider-terraform/.github/workflows/publish.yaml@refs/tags/vX.Y.Z \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
gh attestation verify oci://ghcr.io/captf-io/cluster-api-provider-terraform:vX.Y.Z \
  -R captf-io/cluster-api-provider-terraform

gh release download vX.Y.Z -R captf-io/cluster-api-provider-terraform \
  -p infrastructure-components.yaml
gh attestation verify infrastructure-components.yaml \
  -R captf-io/cluster-api-provider-terraform

cosign verify ghcr.io/captf-io/module-images/aws-machine:v0.1.0-opentofu@sha256:<digest> \
  --certificate-identity-regexp '^https://github.com/captf-io/module-images/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

cosign verify ghcr.io/captf-io/opentofu-base:<version>@sha256:<digest> \
  --certificate-identity-regexp '^https://github.com/captf-io/opentofu-base/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com