modules: add env/envs parameter to app_roles + app_policy (multi-env)

Phase A of the multi-environment evolution agreed in the erp repo design
thread. Both modules gain an optional env coordinate that defaults to
"prod"; by the elision rule, env=prod produces the existing single-env
derived names character-for-character, so every existing app's tofu plan
is a no-op.

app_roles (per-instance module — caller iterates over envs):
- variables.tf: add optional env = "prod"
- main.tf: compute local.instance via elision rule + local.owner_role
  (snake-case <name>_<env>_role for the Postgres owner). The name/env/
  database locals are grouped so fmt keeps the existing `name` alignment
  (no whitespace churn on unchanged keys).
- main.tf: substitute local.name -> local.instance / local.owner_role in
  the dynamic role name, k8s role name, SA bindings, token_policies
- outputs.tf: add env + instance outputs; kvv2_path_prefix derives from
  local.instance (== local.name when env=prod → backwards-compat)

app_policy (per-repo module — accepts list of envs):
- variables.tf: add optional envs = ["prod"]
- main.tf: compute local.instances + local.non_prod_instances; remove the
  now-dead bound_service_account_* alias locals (the allowed_parameter
  blocks build their values from per_instance_sa_* maps instead)
- main.tf: kvv2 ops rules become dynamic blocks iterating local.instances
  in the original order (data, delete, undelete, destroy, metadata), so a
  prod-only app renders a byte-identical policy document
- main.tf: allowed_parameter for bound_service_account_* + token_policies
  use comprehensions over local.instances (1-element → identical to old
  static values for prod-only apps)
- main.tf: keep vault_policy.app (env=prod runtime policy) at its original
  address; add vault_policy.app_non_prod via for_each over non_prod_instances
  (empty set for prod-only apps → no new resources)

Top-level wiring:
- iac/variables.tf: add envs = optional(list(string), ["prod"]) to the
  applications set(object) type
- iac/main.tf: pass envs = each.value.envs to app_policies

Verified: `tofu fmt -check` clean on all touched files, `tofu validate`
passes. Backwards-compat reasoning for the no-op plan is in the PR body.

Phase B (factory postgres iac + argocd + runbook docs) and Phase D
(erp iac/main.tf for_each + activate sandbox) follow in their own PRs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

hashicorp-vault/iac/main.tf

@@ -75,11 +75,12 @@ resource "vault_kubernetes_auth_backend_role" "vso" {
 }
 
 module "app_policies" {
-  source       = "./modules/app_policy"
+  source                     = "./modules/app_policy"
-  for_each     = { for app in var.applications : app.name => app }
+  for_each                   = { for app in var.applications : app.name => app }
-  name         = each.value.name
+  name                       = each.value.name
-  ops_policies     = each.value.policies
+  envs                       = each.value.envs
-  service_account_names = each.value.service_account_names
+  ops_policies               = each.value.policies
-  service_account_namespaces =  each.value.service_account_namespaces
+  service_account_names      = each.value.service_account_names
-  gitea_app_id = var.gitea_app_id
+  service_account_namespaces = each.value.service_account_namespaces
+  gitea_app_id               = var.gitea_app_id
 }

hashicorp-vault/iac/modules/app_policy/main.tf

@@ -6,9 +6,16 @@
 # - postgres role
 
 locals {
-  name                             = lower(var.name)
+  name = lower(var.name)
-  bound_service_account_names      = concat([var.name], var.service_account_names)
+  envs = [for e in var.envs : lower(e)]
-  bound_service_account_namespaces = concat([var.name], var.service_account_namespaces)
+
+  # Elision rule: env=prod → bare name; else <name>-<env>
+  instances          = [for e in local.envs : e == "prod" ? local.name : "${local.name}-${e}"]
+  non_prod_instances = [for e in local.envs : "${local.name}-${e}" if e != "prod"]
+
+  # Per-instance SA name/namespace sets used by the CI policy's allowed_parameter blocks.
+  per_instance_sa_names      = { for inst in local.instances : inst => concat([inst], var.service_account_names) }
+  per_instance_sa_namespaces = { for inst in local.instances : inst => concat([inst], var.service_account_namespaces) }
 }
 
 data "vault_policy_document" "ops" {
@@ -60,41 +67,61 @@ data "vault_policy_document" "ops" {
     }
     allowed_parameter {
       key   = "bound_service_account_names"
-      value = [jsonencode(local.bound_service_account_names)]
+      value = [for inst in local.instances : jsonencode(local.per_instance_sa_names[inst])]
     }
     allowed_parameter {
       key   = "bound_service_account_namespaces"
-      value = [jsonencode(local.bound_service_account_namespaces)]
+      value = [for inst in local.instances : jsonencode(local.per_instance_sa_namespaces[inst])]
     }
     allowed_parameter {
       key = "token_policies"
-      value = [
+      value = flatten([
-        jsonencode(["default", local.name]),
+        for inst in local.instances : [
-        jsonencode([local.name, "default"])
+          jsonencode(["default", inst]),
-      ]
+          jsonencode([inst, "default"])
+        ]
+      ])
     }
 
   }
-  # allow editing app secrets
+  # allow editing app secrets — one rule per (capability × instance) preserves the
-  rule {
+  # original rule order (data, delete, undelete, destroy, metadata) so prod-only apps
-    path         = "kvv2/data/${local.name}/*"
+  # render a byte-identical policy document (no Vault state diff). Multi-env apps add
-    capabilities = ["create", "update", "read", "delete"]
+  # extra rules per non-prod instance.
+  dynamic "rule" {
+    for_each = local.instances
+    content {
+      path         = "kvv2/data/${rule.value}/*"
+      capabilities = ["create", "update", "read", "delete"]
+    }
   }
-  rule {
+  dynamic "rule" {
-    path         = "kvv2/delete/${local.name}/*"
+    for_each = local.instances
-    capabilities = ["update"]
+    content {
+      path         = "kvv2/delete/${rule.value}/*"
+      capabilities = ["update"]
+    }
   }
-  rule {
+  dynamic "rule" {
-    path         = "kvv2/undelete/${local.name}/*"
+    for_each = local.instances
-    capabilities = ["update"]
+    content {
+      path         = "kvv2/undelete/${rule.value}/*"
+      capabilities = ["update"]
+    }
   }
-  rule {
+  dynamic "rule" {
-    path         = "kvv2/destroy/${local.name}/*"
+    for_each = local.instances
-    capabilities = ["update"]
+    content {
+      path         = "kvv2/destroy/${rule.value}/*"
+      capabilities = ["update"]
+    }
   }
-  rule {
+  dynamic "rule" {
-    path         = "kvv2/metadata/${local.name}/*"
+    for_each = local.instances
-    capabilities = ["read", "list", "delete"]
+    content {
+      path         = "kvv2/metadata/${rule.value}/*"
+      capabilities = ["read", "list", "delete"]
+    }
   }
   # allow edit vault role (risky ?)
 }
@@ -139,6 +166,9 @@ resource "vault_jwt_auth_backend_role" "gitea_jwt_cicd" {
   role_type  = "jwt"
 }
 
+# Runtime policy for the env=prod instance — kept at its single-env address
+# (data.vault_policy_document.app, vault_policy.app, name = local.name) so existing
+# state isn't disturbed when this module is upgraded.
 data "vault_policy_document" "app" {
   rule {
     path         = "kvv2/data/${local.name}/*"
@@ -152,4 +182,23 @@ data "vault_policy_document" "app" {
 resource "vault_policy" "app" {
   name   = local.name
   policy = data.vault_policy_document.app.hcl
+}
+
+# Runtime policies for non-prod envs. Each one is named <name>-<env> and reads
+# only its own kvv2 + postgres creds paths.
+data "vault_policy_document" "app_non_prod" {
+  for_each = toset(local.non_prod_instances)
+  rule {
+    path         = "kvv2/data/${each.key}/*"
+    capabilities = ["read", "list"]
+  }
+  rule {
+    path         = "postgres/creds/${each.key}*"
+    capabilities = ["read"]
+  }
+}
+resource "vault_policy" "app_non_prod" {
+  for_each = toset(local.non_prod_instances)
+  name     = each.key
+  policy   = data.vault_policy_document.app_non_prod[each.key].hcl
 }

hashicorp-vault/iac/modules/app_policy/variables.tf

@@ -1,6 +1,11 @@
 variable "name" {
   type = string
 }
+variable "envs" {
+  type        = list(string)
+  default     = ["prod"]
+  description = "List of environments this app deploys to. The CI policy + JWT role + identity group are created ONCE per repo regardless. One runtime policy is created per env; the env=prod runtime policy keeps its single-env address for backwards compatibility (no state move)."
+}
 variable "gitea_app_id" {
   type = string
 }

hashicorp-vault/iac/modules/app_roles/main.tf

@@ -4,10 +4,18 @@ data "vault_auth_backend" "kubernetes" {
 
 locals {
   name     = lower(var.name)
-  database = var.database == null ? local.name : var.database
+  env      = lower(var.env)
+  database = var.database == null ? local.instance : var.database
 
-  bound_service_account_names      = concat([var.name], var.service_account_names)
+  # Elision rule (factory runbook conventions.md):
-  bound_service_account_namespaces = concat([var.name], var.service_account_namespaces)
+  #   env == prod → identical to the single-env baseline (no suffix)
+  #   else        → kebab-case "<name>-<env>" for K8s/Vault paths.
+  # Postgres owner role stays snake-case for consistency with the existing "_role" suffix.
+  instance   = local.env == "prod" ? local.name : "${local.name}-${local.env}"
+  owner_role = local.env == "prod" ? "${local.name}_role" : "${local.name}_${local.env}_role"
+
+  bound_service_account_names      = concat([local.instance], var.service_account_names)
+  bound_service_account_namespaces = concat([local.instance], var.service_account_namespaces)
 
   vault_mount_postgres = { path = "postgres" }
   vault_mount_kvv2     = { path = "kvv2" }
@@ -20,14 +28,14 @@ moved {
 resource "vault_database_secret_backend_role" "role" {
   count   = var.disable_database ? 0 : 1
   backend = local.vault_mount_postgres.path
-  name    = local.name
+  name    = local.instance
   db_name = "postgres"
   creation_statements = [
     "CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}';",
-    "GRANT ${local.name}_role TO \"{{name}}\";",
+    "GRANT ${local.owner_role} TO \"{{name}}\";",
   ]
   revocation_statements = [
-    "REASSIGN OWNED BY \"{{name}}\" TO ${local.name}_role;", # reassign must be executed in the database where the reassgined objects are - TODO (one connection per database/app)
+    "REASSIGN OWNED BY \"{{name}}\" TO ${local.owner_role};",       # reassign must be executed in the database where the reassgined objects are - TODO (one connection per database/app)
     "REVOKE ALL ON DATABASE ${local.database} FROM  \"{{name}}\";", # should we drop the role ? -> YES after fixing reassign
   ]
   renew_statements    = []
@@ -36,11 +44,11 @@ resource "vault_database_secret_backend_role" "role" {
 
 resource "vault_kubernetes_auth_backend_role" "role" {
   backend                          = data.vault_auth_backend.kubernetes.path
-  role_name                        = local.name
+  role_name                        = local.instance
   bound_service_account_names      = local.bound_service_account_names
   bound_service_account_namespaces = local.bound_service_account_namespaces
   token_ttl                        = 3600
-  token_policies                   = ["default", local.name]
+  token_policies                   = ["default", local.instance]
   audience                         = "vault"
   alias_name_source                = "serviceaccount_name"
 }

hashicorp-vault/iac/modules/app_roles/outputs.tf

@@ -1,6 +1,13 @@
 output "name" {
   value = local.name
 }
+output "env" {
+  value = local.env
+}
+output "instance" {
+  value       = local.instance
+  description = "Derived id by the elision rule: equals name when env=prod, else <name>-<env>."
+}
 output "database" {
   value = local.database
 }
@@ -12,5 +19,6 @@ output "mount_paths" {
   }
 }
 output "kvv2_path_prefix" {
-  value = format("%s/", local.name)
+  # Identical to format("%s/", local.name) when env=prod (backwards compat).
+  value = format("%s/", local.instance)
 }

hashicorp-vault/iac/modules/app_roles/variables.tf

@@ -1,6 +1,11 @@
 variable "name" {
   type = string
 }
+variable "env" {
+  type        = string
+  default     = "prod"
+  description = "Deployment environment. By the elision rule (factory runbook conventions.md), env=prod produces names identical to the single-env baseline; non-prod values produce <name>-<env> kebab-case and <name>_<env>_role for the Postgres owner role."
+}
 variable "database" {
   type     = string
   nullable = true

hashicorp-vault/iac/variables.tf

@@ -11,9 +11,13 @@ variable "POSTGRES_CREDENTIALS_EDITOR_PASSWORD" {
 }
 variable "applications" {
   type = set(object({
-    name     = string
+    name                       = string
-    policies = optional(list(string), [])
+    policies                   = optional(list(string), [])
-    service_account_names = optional(list(string), [])
+    service_account_names      = optional(list(string), [])
     service_account_namespaces = optional(list(string), [])
+    # Multi-env extension: list of envs this app deploys to. Defaults to ["prod"] for
+    # every existing app — backwards compatible by the elision rule. Non-prod envs
+    # produce additional runtime policies named "<name>-<env>".
+    envs = optional(list(string), ["prod"])
   }))
 }