cluster-bootstrap Operations

Operational guide for the tf/cluster-bootstrap Terraform module — core cluster infrastructure (cert-manager, External Secrets, Longhorn, MetalLB, ArgoCD).

Quick Reference

Property	Value
Module	tf/cluster-bootstrap/
HCP workspace	main-cluster-bootstrap
Execution	Local — NOT auto-applied on PR merge
Auth	kube provider: ~/.kube/configs/fzymgc-house-admin.yml; vault provider: VAULT_TOKEN

Apply workflow

Because this workspace is Local execution, merging a PR does not apply it. Apply deliberately:

cd tf/cluster-bootstrap
terraform init            # use init -upgrade after a provider bump
terraform plan -out=tfplan
terraform apply tfplan

If the kubernetes provider returns Unauthorized, the admin client cert in ~/.kube/configs/fzymgc-house-admin.yml has likely expired — re-fetch it:

ansible-playbook ansible/k3s-playbook.yml --tags k3s-kubeconfig

State migrations

Provider deprecations that rename resources to new addresses (e.g. the kubernetes provider 3.x rename kubernetes_namespace -> kubernetes_namespace_v1) are migrated with declarative import + removed blocks (Terraform 1.7+) rather than manual terraform state surgery:

• resources are renamed to the new type and all references updated
• import blocks adopt the live objects into the new addresses
• removed { ... lifecycle { destroy = false } } blocks drop the old addresses from state without deleting the live objects

Mandatory safety gate: the pre-apply terraform plan MUST show 0 to destroy before applying a state migration. A non-zero destroy count means an address or import ID is wrong — abort and fix. Once the migration has applied, the spent import/removed blocks (kept in a dedicated migration-*.tf file) become no-ops and should be deleted in a follow-up commit — but only after confirming the plan against the live workspace shows 0 to destroy without them.