diff --git a/docs/decisions/006-terraform.md b/docs/decisions/006-terraform.md index 16eeff3..9a866c2 100644 --- a/docs/decisions/006-terraform.md +++ b/docs/decisions/006-terraform.md @@ -44,16 +44,18 @@ Terraform manages its own provider dependencies via `required_providers` and ## State backend -**Choice**: Forgejo HTTP backend (self-hosted at forgejo.nyumbani.baobab.band) +**Choice**: Local state on the control node. -Keeps all state on the same self-hosted stack without additional services. -Authentication uses a Forgejo personal access token via `TF_HTTP_USERNAME` and -`TF_HTTP_PASSWORD` environment variables. +Forgejo (Gitea-based) has no usable Terraform HTTP state backend — its API `/raw/` +endpoint is read-only, so state cannot be written there. State therefore lives +locally as `terraform.tfstate` (gitignored) on the control node, which is persistent +and backed up with the rest of the node. -**Note**: The backend URL in `backend.tf` is a placeholder — confirm the exact -endpoint path against your running Forgejo instance's API documentation before -running `terraform init`. If Forgejo's HTTP state is unavailable, remove the -`backend` block from `backend.tf` to fall back to local state on the control node. +At this scale (solo operator, a handful of VMs) local state is sufficient: no +concurrent applies, so no remote locking is needed. If a remote backend with locking +becomes worthwhile later, add a `backend` block to `backend.tf` pointing at a real +backend such as MinIO/S3 — Forgejo is not an option. See ADR-010 for the Forgejo +integration boundary. --- diff --git a/terraform/environments/production/backend.tf b/terraform/environments/production/backend.tf index b9abdd8..d83f06b 100644 --- a/terraform/environments/production/backend.tf +++ b/terraform/environments/production/backend.tf @@ -1,17 +1,9 @@ -terraform { - backend "http" { - # Forgejo HTTP state backend. - # Replace and with your Forgejo organisation and repository name. - # Verify the exact path format against your running Forgejo instance's API docs. - # Authentication: set TF_HTTP_USERNAME (Forgejo username) and - # TF_HTTP_PASSWORD (Forgejo personal access token) as environment variables. - # - # If Forgejo's HTTP state endpoint is unavailable, remove this block entirely - # to fall back to local state on the control node. - address = "https://forgejo.nyumbani.baobab.band/api/v1/repos///raw/terraform/state/production.tfstate" - lock_address = "https://forgejo.nyumbani.baobab.band/api/v1/repos///raw/terraform/state/production.tfstate/lock" - unlock_address = "https://forgejo.nyumbani.baobab.band/api/v1/repos///raw/terraform/state/production.tfstate/lock" - lock_method = "POST" - unlock_method = "DELETE" - } -} +# Terraform state: LOCAL, on the control node. +# +# Forgejo (Gitea-based) has no usable Terraform HTTP state backend — its API +# `/raw/` endpoint is read-only, so state cannot be written there. State therefore +# lives locally as `terraform.tfstate` (gitignored); back it up with the control +# node. See ADR-006. +# +# To adopt a real remote backend later (e.g. MinIO/S3), add a +# `terraform { backend "..." {} }` block here. diff --git a/terraform/environments/production/terraform.tfvars.example b/terraform/environments/production/terraform.tfvars.example index 7501906..8de1116 100644 --- a/terraform/environments/production/terraform.tfvars.example +++ b/terraform/environments/production/terraform.tfvars.example @@ -4,9 +4,7 @@ # Secrets must be exported as environment variables before running Terraform: # export TF_VAR_proxmox_api_token="terraform@pve!tokenid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # -# Forgejo backend credentials: -# export TF_HTTP_USERNAME="your-forgejo-username" -# export TF_HTTP_PASSWORD="your-forgejo-personal-access-token" +# State is local (see backend.tf) — no Forgejo backend credentials needed. proxmox_endpoint = "https://pve01.baobab.band:8006/" proxmox_insecure = false diff --git a/terraform/environments/staging/backend.tf b/terraform/environments/staging/backend.tf index 1facab4..d83f06b 100644 --- a/terraform/environments/staging/backend.tf +++ b/terraform/environments/staging/backend.tf @@ -1,17 +1,9 @@ -terraform { - backend "http" { - # Forgejo HTTP state backend. - # Replace and with your Forgejo organisation and repository name. - # Verify the exact path format against your running Forgejo instance's API docs. - # Authentication: set TF_HTTP_USERNAME (Forgejo username) and - # TF_HTTP_PASSWORD (Forgejo personal access token) as environment variables. - # - # If Forgejo's HTTP state endpoint is unavailable, remove this block entirely - # to fall back to local state on the control node. - address = "https://forgejo.nyumbani.baobab.band/api/v1/repos///raw/terraform/state/staging.tfstate" - lock_address = "https://forgejo.nyumbani.baobab.band/api/v1/repos///raw/terraform/state/staging.tfstate/lock" - unlock_address = "https://forgejo.nyumbani.baobab.band/api/v1/repos///raw/terraform/state/staging.tfstate/lock" - lock_method = "POST" - unlock_method = "DELETE" - } -} +# Terraform state: LOCAL, on the control node. +# +# Forgejo (Gitea-based) has no usable Terraform HTTP state backend — its API +# `/raw/` endpoint is read-only, so state cannot be written there. State therefore +# lives locally as `terraform.tfstate` (gitignored); back it up with the control +# node. See ADR-006. +# +# To adopt a real remote backend later (e.g. MinIO/S3), add a +# `terraform { backend "..." {} }` block here. diff --git a/terraform/environments/staging/terraform.tfvars.example b/terraform/environments/staging/terraform.tfvars.example index 898a374..454120c 100644 --- a/terraform/environments/staging/terraform.tfvars.example +++ b/terraform/environments/staging/terraform.tfvars.example @@ -4,9 +4,7 @@ # Secrets must be exported as environment variables before running Terraform: # export TF_VAR_proxmox_api_token="terraform@pve!tokenid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # -# Forgejo backend credentials: -# export TF_HTTP_USERNAME="your-forgejo-username" -# export TF_HTTP_PASSWORD="your-forgejo-personal-access-token" +# State is local (see backend.tf) — no Forgejo backend credentials needed. proxmox_endpoint = "https://pve01.baobab.band:8006/" proxmox_insecure = true # set false once a valid TLS cert is in place