pal-e-docs

Review: Keycloak realm config via Terraform provider

review-270-2026-03-27 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — discovered scope from PR #130
  • [x] Repo — forgejo_admin/pal-e-platform
  • [x] User Story — platform operator wants declarative Keycloak config
  • [x] Context — explains the gap (theme files in TF but realm config is not)
  • [x] File Targets — main.tf, providers.tf, and exclusion list
  • [x] Acceptance Criteria — 3 criteria
  • [x] Test Expectations — includes tofu plan command
  • [x] Constraints — 3 constraints including import safety
  • [x] Checklist
  • [x] Related

Traceability

  • [ ] story:X label — missing. Board item #270 has labels type:feature,scope:platform-hardening,discovered-scope but no story label. Foundational IaC work — acceptable if intentional, but should be explicit (e.g., story:superuser-deploy or story:platform-reliability)
  • [ ] arch:X label — missing. Should be arch:keycloak or arch:terraform. Keycloak module already exists at terraform/modules/keycloak/
  • [x] Forgejo issue — pal-e-platform#142, open

File Targets

  • [x] terraform/main.tf — verified exists. Contains module "keycloak" at line 95 with 6 moved blocks for Keycloak resources. Accurate target.
  • [x] terraform/providers.tf — verified exists. Currently has kubernetes, helm, tailscale, minio providers. No Keycloak provider yet. Accurate target.
  • [x] keycloak/themes/ — verified exists at keycloak/themes/westside/login/. Correctly excluded from scope.

Repo Placement

Correct repo — pal-e-platform is where all Terraform lives. However, Phase 28 (Keycloak Declarative Onboarding, board item #276) is DONE, with issues #277 (import Keycloak realms/clients into Terraform) and #278 (update SOP) both done in pal-e-services. This ticket may overlap with completed Phase 28 work. Must verify whether Phase 28 already covers this scope.

Dependencies

  • Phase 28 overlap — board items #276/#277/#278 (done) imported Keycloak realms/clients into Terraform. Scope overlap must be clarified.
  • Keycloak admin credentials — confirmed in Salt pillar at salt/pillar/secrets_registry.sls:91. Dependency satisfied.
  • Terraform state splitting — board item #436 (done) already split main.tf into modules. Keycloak module exists at terraform/modules/keycloak/.

Acceptance Criteria

Partially testable. "Client configurations managed in Terraform" is vague — which clients, how many? The constraint "may warrant its own plan phase" indicates the ticket author recognized this is too large for a single agent pass.

Blast Radius

  • Keycloak import is destructive-risk — if import misses a field, next apply could modify production Keycloak config.
  • Multiple realms x multiple clients — not a single-agent, single-PR scope.
  • State ownership conflict — if Phase 28 already manages Keycloak via Terraform in pal-e-services, adding a second Keycloak provider in pal-e-platform creates dual-ownership of the same resources.

Recommendation

  • Clarify Phase 28 overlap — check what pal-e-services#23/#27 delivered. If Keycloak provider is already there, this ticket may be redundant or scope changes fundamentally.
  • Add traceability labels — add story:superuser-deploy and arch:keycloak to board item #270.
  • Decompose if not redundant — create sub-items: (a) add provider + import master realm, (b) import westside-basketball realm + clients, (c) import mcd-tracker realm + clients, (d) verify no drift.
  • Resolve state ownership — decide: does pal-e-platform or pal-e-services own Keycloak Terraform resources?