Flux Operator Bootstrap Module for Terraform and OpenTofu

[matheuscscp]

🚀 New on the Flux blog: bootstrapping Flux with Terraform, the right way.

If you've ever fought Terraform and Flux over who owns what after a cluster comes up, this one is
for you.

We just released a new Terraform module (also fully compatible with OpenTofu) that bootstraps Flux
Operator into a Kubernetes cluster — and then gracefully steps aside, letting Flux take over
steady-state reconciliation. No more drift loops, no more two-phase applies.

A few things it solves out of the box:

✅ Clean ownership handoff — Terraform owns the bootstrap, Flux owns everything after
✅ Same GitOps repo for Terraform inputs and Flux manifests
✅ Same root module as the cluster — no provider chicken-and-egg
✅ Secrets never land in Terraform state
✅ Prerequisites like CNI plugins and CSI drivers can be installed before Flux

Plus some groundwork for a SPIFFE/SPIRE integration coming in upcoming releases. 👀

Read it here 👉 https://fluxcd.io/blog/2026/04/terraform-flux-operator-bootstrap/

[bozho]

Hi @matheuscscp,

This is extremely useful, thank you both for this! Bootstrapping FluxOperator manually is not a huge task, but this makes it really easy.

I have a question about TF states for cluster instances: what's the intended process? Since the module is only used for bootstrapping clusters, are there any disadvantages to simply deleting the TF state after it's done? Would it be useful to keep it around, maybe to be able to force-override some values on a running cluster?

If we wanted to keep TF state around, I guess the D2 repo example should be altered to support handling multiple cluster instances, where each one would have a small TF root module, referencing the module in d2-fleet/terraform.

[bozho]

@matheuscscp Sorry to bother you, but could I ask about your fleet repo organisation?

Originally, my fleet repo included root TF modules for each cluster instance, so my directory tree looked like this:

fleet/
└── clusters/
    ├── cluster-1/
    │   ├── k8s/
    │   │   ├── flux-system/
    │   │   └── tenants.yaml
    │   └── terraform/
    │       ├── main.tf
    |       └── <other TF files>
    ├── cluster-2/
    │   ├── k8s/
    │   └── terraform/
    └── tenants/

This meant that if I was making any changes on a production cluster's TF configuration, or if I was adding another production cluster instance, I'd commit and push the changes, which would build a new OCI artefact, tag it with the latest tag and have no functional effect, since the latest OCI tag is only tracked by staging clusters.

It felt kind of weird to have TF changes create new OCI artefacts, so I moved all TF root modules to a separate repository. I guess I'll have to move them back now, if I want to use the bootstrap module and be able to reference flux-runtime.yaml and FluxOperator helm values files 😄

[matheuscscp]

My fleet repo organization is this one: https://github.com/controlplaneio-fluxcd/d2-fleet

I have an internal fork with the AWS terraform

[matheuscscp]

Ah, I see you were already looking at D2. I see you're interested in the k8s/tf org, here it goes:

.aws
├── clusters.yaml
├── main
│   ├── ci.tf
│   ├── ecr.tf
│   ├── kms.tf
│   ├── main.tf
│   ├── outputs.tf
│   ├── route_53.tf
│   ├── s3.tf
│   ├── spot.tf
│   └── .terraform.lock.hcl
├── preview
│   ├── main.tf
│   └── .terraform.lock.hcl
├── prod-eu
│   ├── main.tf
│   └── .terraform.lock.hcl
├── prod-us
│   ├── main.tf
│   └── .terraform.lock.hcl
├── staging
│   ├── main.tf
│   └── .terraform.lock.hcl
├── tenants.yaml
└── webhook
    ├── main.tf
    └── .terraform.lock.hcl
clusters
├── preview
│   ├── eks-addons.yaml
│   ├── flux-mcp-enterprise.yaml
│   ├── flux-system
│   │   ├── flux-instance.yaml
│   │   ├── flux-operator-values.yaml
│   │   ├── flux-operator.yaml
│   │   └── kustomization.yaml
│   ├── policies.yaml
│   ├── preview.yaml
│   └── tenants.yaml
├── prod-eu
│   ├── eks-addons.yaml
│   ├── flux-mcp-enterprise.yaml
│   ├── flux-system
│   │   ├── flux-instance.yaml
│   │   ├── flux-operator-values.yaml
│   │   ├── flux-operator.yaml
│   │   └── kustomization.yaml
│   ├── policies.yaml
│   └── tenants.yaml
├── prod-us
│   ├── eks-addons.yaml
│   ├── flux-mcp-enterprise.yaml
│   ├── flux-system
│   │   ├── flux-instance.yaml
│   │   ├── flux-operator-values.yaml
│   │   ├── flux-operator.yaml
│   │   └── kustomization.yaml
│   ├── policies.yaml
│   └── tenants.yaml
├── staging
│   ├── eks-addons.yaml
│   ├── flux-mcp-enterprise.yaml
│   ├── flux-system
│   │   ├── flux-instance.yaml
│   │   ├── flux-operator-values.yaml
│   │   ├── flux-operator.yaml
│   │   └── kustomization.yaml
│   ├── policies.yaml
│   ├── preview.yaml
│   └── tenants.yaml
└── update
    ├── automation.yaml
    └── flux-system
        ├── flux-instance.yaml
        ├── flux-operator.yaml
        └── runtime-info.yaml
terraform-modules
└── aws
    ├── bootstrap
    │   └── v1
    │       └── main.tf
    └── cluster
        └── v1
            ├── eks.tf
            ├── iam.tf
            ├── kms.tf
            ├── main.tf
            ├── notifications.tf
            ├── outputs.tf
            ├── route_53.tf
            ├── sso.tf
            ├── variables.tf
            └── vpc.tf

[bozho]

Ah, this is a better organisation. This way, we can set up the GH action that build OCI artifacts to ignore changes on paths that contain TF configurations/modules, since those are not relevant to flux.

Thank you!

[matheuscscp]

Yep, we do that too!