Repositories and Images¶

CAPTF lives in eleven repositories in the captf-io GitHub organization. This page lists what each one holds, what it publishes, which container images exist and how they are tagged, and how the pieces fit together.

How the pieces fit¶

A module image is built FROM a base image that supplies the runtime. The module image is what a Terraform* resource names in spec.source.image. The provider runs it as a Kubernetes Job: an init container started from the provider’s own image copies the /runner binary into a shared volume, and the main container runs your module image with that runner as its command.

flowchart LR
    base["opentofu-base / terraform-base<br/>runtime at /captf/runtime"]
    mod["module image<br/>module + provider mirror"]
    prov["cluster-api-provider-terraform image<br/>manager + /runner"]
    res["TerraformCluster, TerraformMachine,<br/>TerraformMachinePool<br/>spec.source.image"]
    job["Job"]
    init["init container: copies /runner<br/>from the provider image"]
    main["main container: your module image<br/>runs /captf/bin/runner run"]

    base -->|FROM| mod
    mod -->|referenced by| res
    res -->|reconciled by manager in| prov
    prov -->|creates| job
    job --> init
    job --> main
    prov -.->|image of| init
    mod -.->|image of| main

The init container, the /captf/bin/runner path and the rule that the image’s own ENTRYPOINT never runs are described in Job Environment. The runner image defaults to the manager’s own image and can be overridden with --runner-image; see Manager Flags and The manager image and the runner image. The module image half of the contract is in Image Contract.

Repositories¶

The module repositories are described together in Cloud Modules; their layout is in Module Repository Layout.

Images¶

All images are in GitHub Container Registry under ghcr.io/captf-io/.

What exists today follows from those triggers:

• The provider image is published by the publish workflow on every push to main (:edge and :sha-<commit>) and on every release tag (:vX.Y.Z); workflow_dispatch republishes :edge. No release has been made yet, so no :vX.Y.Z tag exists. Until one does, use :edge or pin a :sha-<commit> tag or a digest. To build your own, use make docker-build and make docker-push IMG=.... A maintainer can fall back to make release when CI cannot run; see Releasing.
• The base images are published on every push to main and weekly, so they exist now. See Base Images for how to pin them.
• The module images publish edge-<runtime> from every push to main. The vX.Y.Z-<runtime> and <runtime> tags appear only when a vX.Y.Z tag is pushed, so before the first module release only the edge- tags are available. Pin a release tag or a digest in anything you keep.

Every pushed module and base image carries an SBOM and provenance attestations (mode=max), and the manifests carry the org.opencontainers.image.* title, description and licence annotations. The provider image has its own scheme: every pushed digest gets a keyless cosign signature, a SLSA provenance attestation and an SPDX SBOM attestation, and its manifests carry the org.opencontainers.image.* source, revision, version, licenses and description annotations and labels. See Releasing for the verification commands.

Release assets¶

A provider release, created by the publish workflow when a release tag is pushed, attaches these files to the GitHub release:

The publish workflow runs make release-assets and make release-github on the tag push; make release is the manual fallback. The steps and the checklist are in Releasing. The module and base repositories attach no release assets: their output is the images above.

Versioning at a glance¶

Which provider, Cluster API and runtime versions are tested together is in Compatibility.

Shared across repositories¶

Every repository carries the same CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md and LICENSE.md, and every source file is Apache-2.0 licensed with a license header that CI checks. The provider also has a SECURITY_CONTACTS file. The .github repository holds the organization’s community health files, and its make readme target keeps the banner, status note and footer of each repository’s README identical. See Working Across Repositories for changes that span repositories, and Contributing for how to contribute.