Deploy CloudNativePG operator + Cluster to k3s

forgejo_admin commented

2026-03-02 21:11:52 +00:00

Owner

Plan

plan-2026-02-26-tf-modularize-postgres -- Phase 2

Repo

forgejo_admin/pal-e-platform

User Story

As a platform operator
I want CloudNativePG deployed to k3s with a shared PostgreSQL cluster
So that platform services can use managed Postgres instead of embedded SQLite

Context

Platform services (pal-e-docs, future apps) need a shared PostgreSQL instance. CloudNativePG (CNPG) is a Kubernetes operator that manages PostgreSQL clusters declaratively. This phase deploys the CNPG operator via Helm and creates a single-instance Cluster CRD via kubernetes_manifest.

Key decision: CNPG's admission webhook injects default PostgreSQL parameters (wal_receiver_timeout and wal_sender_timeout both set to 5min) into the Cluster spec. If these are not present in the Terraform manifest, every tofu apply produces a provider drift error. These must be pinned in the manifest.

File Targets

Files the agent should modify or create:

terraform/main.tf -- add CNPG namespace, Helm release, and Cluster kubernetes_manifest
terraform/versions.tf -- no changes expected (kubernetes provider already present)
terraform/variables.tf -- add CNPG-related variables if needed
terraform/outputs.tf -- add CNPG cluster outputs

Files the agent should NOT touch:

salt/ -- host-level config, not relevant

Acceptance Criteria

CNPG operator deployed via helm_release
CNPG Cluster manifest created via kubernetes_manifest with single instance
PostgreSQL parameters include wal_receiver_timeout = "5min" and wal_sender_timeout = "5min"
tofu fmt passes
tofu validate passes

Test Expectations

tofu fmt -check exits 0
tofu validate exits 0
Run command: cd terraform && tofu fmt -check && tofu validate

Constraints

IaC is OpenTofu (tofu not terraform)
Follow existing patterns in main.tf: namespace -> helm_release -> kubernetes_manifest -> ingress
Use local-path storageClass consistent with other resources
Single-instance cluster (no HA needed for bootstrap platform)
Pin CNPG Helm chart version for reproducibility

Checklist

PR opened
Tests pass (tofu fmt, tofu validate)
No unrelated changes

plan-2026-02-26-tf-modularize-postgres -- parent plan

### Plan `plan-2026-02-26-tf-modularize-postgres` -- Phase 2 ### Repo `forgejo_admin/pal-e-platform` ### User Story As a platform operator I want CloudNativePG deployed to k3s with a shared PostgreSQL cluster So that platform services can use managed Postgres instead of embedded SQLite ### Context Platform services (pal-e-docs, future apps) need a shared PostgreSQL instance. CloudNativePG (CNPG) is a Kubernetes operator that manages PostgreSQL clusters declaratively. This phase deploys the CNPG operator via Helm and creates a single-instance Cluster CRD via `kubernetes_manifest`. Key decision: CNPG's admission webhook injects default PostgreSQL parameters (`wal_receiver_timeout` and `wal_sender_timeout` both set to `5min`) into the Cluster spec. If these are not present in the Terraform manifest, every `tofu apply` produces a provider drift error. These must be pinned in the manifest. ### File Targets Files the agent should modify or create: - `terraform/main.tf` -- add CNPG namespace, Helm release, and Cluster kubernetes_manifest - `terraform/versions.tf` -- no changes expected (kubernetes provider already present) - `terraform/variables.tf` -- add CNPG-related variables if needed - `terraform/outputs.tf` -- add CNPG cluster outputs Files the agent should NOT touch: - `salt/` -- host-level config, not relevant ### Acceptance Criteria - [ ] CNPG operator deployed via `helm_release` - [ ] CNPG `Cluster` manifest created via `kubernetes_manifest` with single instance - [ ] PostgreSQL parameters include `wal_receiver_timeout = "5min"` and `wal_sender_timeout = "5min"` - [ ] `tofu fmt` passes - [ ] `tofu validate` passes ### Test Expectations - [ ] `tofu fmt -check` exits 0 - [ ] `tofu validate` exits 0 - Run command: `cd terraform && tofu fmt -check && tofu validate` ### Constraints - IaC is OpenTofu (`tofu` not `terraform`) - Follow existing patterns in main.tf: namespace -> helm_release -> kubernetes_manifest -> ingress - Use `local-path` storageClass consistent with other resources - Single-instance cluster (no HA needed for bootstrap platform) - Pin CNPG Helm chart version for reproducibility ### Checklist - [ ] PR opened - [ ] Tests pass (`tofu fmt`, `tofu validate`) - [ ] No unrelated changes ### Related - `plan-2026-02-26-tf-modularize-postgres` -- parent plan