vault: mount arrstack engine + config + roles (3/3) (#127)

## Why

Creates the arrstack secrets engine itself: the mount + config and the per-scope roles that mint arrproxy API keys. **PR 3 of 3 (resources)**, stacked on #126 (policy). Final step of the register -> policy -> resources split (was #124).

## Change

- Adds `config/arrstack_secret_backend/arrstack.yaml`: mounts the engine at `arrstack` and writes its config (`base_url`, timeout). The arrproxy admin token stays out of git and is read from KV by the module.
- Adds `config/arrstack_secret_backend_role/arrstack/{all,sonarr,radarr,prowlarr}.yaml`: roles scoped to each arr app (plus one covering all three). Default `ttl` is **60s** (short-lived, renewed on demand); `max_ttl` 86400 mirrors the litellm sibling convention. The engine additionally caps renewal at the arrproxy admin token's fixed mint expiry.
- Adds `modules/vault_cluster/modules/arrstack_secret_backend{,_role}` and wires them in: `config/config.hcl` maps, `modules/vault_cluster/main.tf`, `variables.tf`, the environment inputs, and the root provider block.
- Provider source is `artifactapi.k8s.syd1.au.unkin.net/terraform-unkin/vault-secrets-arrstack` (repo `terraform-provider-vault-secrets-arrstack`), local name `arrstack`.

## Apply order

Apply **after PR #126 (policy) AND after `terraform-provider-vault-secrets-arrstack` v0.1.0 is published** to the artifactapi terraform registry. Until the provider is published, `tofu init` cannot resolve it, so **CI/plan on this PR is red by design** — that is expected, not a regression.

Note **plan-green != apply-green**: the KV-sourced `admin_token` is only fetched at apply time, so a green plan does not prove the seeded token is readable.

## Stack

1. register -> #125
2. policy -> #126
3. **resources (this PR)** -> `benvin/arrstack-resources` off `benvin/arrstack-policy`

Supersedes #124.

---------

Co-authored-by: unkin-agent <unkin-agent@git.unkin.net>
Co-authored-by: BenVincent <benvin@main.unkin.net>
Reviewed-on: #127
Co-authored-by: unkin-agent <unkin-agent@unkin.net>
Co-committed-by: unkin-agent <unkin-agent@unkin.net>

config/arrstack_secret_backend/arrstack.yaml

@@ -0,0 +1,9 @@
+# Mounts the arrstack dynamic secrets engine at "arrstack" and writes its config.
+# The arrproxy admin token is sensitive and read from KV, not stored here:
+#   kv/kubernetes/namespace/arrstack/default/arrproxy-admin-token -> key "token"
+# (seeded by argocd-apps #384). arrstack.unkin.net terminates on traefik-external
+# with an internal-CA cert the OpenBao nodes already trust, so ca_cert is omitted
+# (system trust store), mirroring the gitea engine against git.unkin.net.
+description: "arrstack dynamic arrproxy API keys"
+base_url: "https://arrstack.unkin.net"
+request_timeout_seconds: 30

config/arrstack_secret_backend_role/arrstack/all.yaml

@@ -0,0 +1,9 @@
+---
+# Mints an arrproxy API key scoped to all three arr apps.
+apps:
+  - sonarr
+  - radarr
+  - prowlarr
+ttl: 60        # seconds (1m); short-lived by design, renewed on demand
+max_ttl: 86400 # seconds (24h); the engine additionally caps renewal at the
+               # arrproxy admin token's fixed mint expiry.

config/arrstack_secret_backend_role/arrstack/prowlarr.yaml

@@ -0,0 +1,7 @@
+---
+# Mints an arrproxy API key scoped to Prowlarr only.
+apps:
+  - prowlarr
+ttl: 60        # seconds (1m); short-lived by design, renewed on demand
+max_ttl: 86400 # seconds (24h); the engine additionally caps renewal at the
+               # arrproxy admin token's fixed mint expiry.

config/arrstack_secret_backend_role/arrstack/radarr.yaml

@@ -0,0 +1,7 @@
+---
+# Mints an arrproxy API key scoped to Radarr only.
+apps:
+  - radarr
+ttl: 60        # seconds (1m); short-lived by design, renewed on demand
+max_ttl: 86400 # seconds (24h); the engine additionally caps renewal at the
+               # arrproxy admin token's fixed mint expiry.

config/arrstack_secret_backend_role/arrstack/sonarr.yaml

@@ -0,0 +1,7 @@
+---
+# Mints an arrproxy API key scoped to Sonarr only.
+apps:
+  - sonarr
+ttl: 60        # seconds (1m); short-lived by design, renewed on demand
+max_ttl: 86400 # seconds (24h); the engine additionally caps renewal at the
+               # arrproxy admin token's fixed mint expiry.

config/config.hcl

@@ -198,6 +198,19 @@ locals {
       })
       if startswith(file_path, "litellm_secret_backend_role/")
     }
+    arrstack_secret_backend = {
+      for file_path, content in local.all_configs :
+      trimsuffix(basename(file_path), ".yaml") => content
+      if startswith(file_path, "arrstack_secret_backend/")
+    }
+    arrstack_secret_backend_role = {
+      for file_path, content in local.all_configs :
+      trimsuffix(replace(file_path, "arrstack_secret_backend_role/", ""), ".yaml") => merge(content, {
+        name    = trimsuffix(basename(file_path), ".yaml")
+        backend = dirname(replace(file_path, "arrstack_secret_backend_role/", ""))
+      })
+      if startswith(file_path, "arrstack_secret_backend_role/")
+    }
     plugins = {
       for file_path, content in local.all_configs :
       trimsuffix(basename(file_path), ".yaml") => merge(content, {

environments/au/syd1/terragrunt.hcl

@@ -76,6 +76,8 @@ inputs = {
   pki_mount_only                 = local.config.pki_mount_only
   litellm_secret_backend         = local.config.litellm_secret_backend
   litellm_secret_backend_role    = local.config.litellm_secret_backend_role
+  arrstack_secret_backend        = local.config.arrstack_secret_backend
+  arrstack_secret_backend_role   = local.config.arrstack_secret_backend_role
   plugins                        = local.config.plugins
   gpg_secret_backend             = local.config.gpg_secret_backend
   gpg_key                        = local.config.gpg_key

environments/root.hcl

@@ -29,6 +29,12 @@ provider "rancher" {
   address = local.vault_addr
 }
 
+# The arrstack (arrproxy API key) secrets engine is managed through its own
+# provider (same Vault server; token falls back to VAULT_TOKEN).
+provider "arrstack" {
+  address = local.vault_addr
+}
+
 terraform {
   backend "consul" {
     address = "https://consul.service.consul"
@@ -59,6 +65,10 @@ terraform {
       source  = "artifactapi.k8s.syd1.au.unkin.net/terraform-unkin/ranchervaultsecret"
       version = "0.1.0"
     }
+    arrstack = {
+      source  = "artifactapi.k8s.syd1.au.unkin.net/terraform-unkin/vault-secrets-arrstack"
+      version = "0.1.0"
+    }
   }
 }
 EOF

modules/vault_cluster/main.tf

@@ -347,6 +347,35 @@ module "plugin" {
   plugin_version = each.value.version
 }
 
+module "arrstack_secret_backend" {
+  source = "./modules/arrstack_secret_backend"
+
+  for_each = var.arrstack_secret_backend
+
+  path                    = each.key
+  plugin                  = each.value.plugin
+  description             = each.value.description
+  base_url                = each.value.base_url
+  ca_cert                 = each.value.ca_cert
+  request_timeout_seconds = each.value.request_timeout_seconds
+
+  depends_on = [module.plugin]
+}
+
+module "arrstack_secret_backend_role" {
+  source = "./modules/arrstack_secret_backend_role"
+
+  for_each = var.arrstack_secret_backend_role
+
+  name    = each.value.name
+  backend = each.value.backend
+  apps    = each.value.apps
+  ttl     = each.value.ttl
+  max_ttl = each.value.max_ttl
+
+  depends_on = [module.arrstack_secret_backend]
+}
+
 module "gpg_secret_backend" {
   source = "./modules/gpg_secret_backend"
 

modules/vault_cluster/modules/arrstack_secret_backend/main.tf

@@ -0,0 +1,20 @@
+# Mounts the arrstack dynamic secrets engine and writes its config via the
+# vault-secrets-arrstack provider. The plugin is registered in the catalog
+# separately (config/plugins/vault-plugin-secrets-arrstack.yaml). The arrproxy
+# admin token is sensitive and read from KV, not stored in git:
+#   kv/kubernetes/namespace/arrstack/default/arrproxy-admin-token -> key "token"
+# (seeded by argocd-apps #384).
+data "vault_kv_secret_v2" "admin_token" {
+  mount = "kv"
+  name  = var.admin_token_kv_name
+}
+
+resource "arrstack_secret_backend" "this" {
+  path                    = var.path
+  plugin                  = var.plugin
+  description             = var.description
+  base_url                = var.base_url
+  admin_token             = data.vault_kv_secret_v2.admin_token.data[var.admin_token_kv_key]
+  ca_cert                 = var.ca_cert
+  request_timeout_seconds = var.request_timeout_seconds
+}

modules/vault_cluster/modules/arrstack_secret_backend/terraform.tf

@@ -0,0 +1,13 @@
+terraform {
+  required_version = ">= 1.10"
+  required_providers {
+    vault = {
+      source  = "hashicorp/vault"
+      version = "5.6.0"
+    }
+    arrstack = {
+      source  = "artifactapi.k8s.syd1.au.unkin.net/terraform-unkin/vault-secrets-arrstack"
+      version = "0.1.0"
+    }
+  }
+}

modules/vault_cluster/modules/arrstack_secret_backend/variables.tf

@@ -0,0 +1,45 @@
+variable "path" {
+  description = "Mount path of the arrstack secrets engine (e.g. \"arrstack\")"
+  type        = string
+}
+
+variable "plugin" {
+  description = "Registered plugin name/type to mount (the catalog name = mount type)"
+  type        = string
+  default     = "vault-plugin-secrets-arrstack"
+}
+
+variable "description" {
+  description = "Human-friendly description of the mount"
+  type        = string
+  default     = null
+}
+
+variable "base_url" {
+  description = "Base URL of the arrproxy front door (e.g. https://arrstack.unkin.net)"
+  type        = string
+}
+
+variable "admin_token_kv_name" {
+  description = "kv-v2 secret name (relative to the \"kv\" mount) holding the seeded arrproxy admin token"
+  type        = string
+  default     = "kubernetes/namespace/arrstack/default/arrproxy-admin-token"
+}
+
+variable "admin_token_kv_key" {
+  description = "Key within the KV secret that holds the arrproxy admin token"
+  type        = string
+  default     = "token"
+}
+
+variable "ca_cert" {
+  description = "PEM CA certificate that signed the arrproxy server's TLS cert (optional; omit to use the system trust store)"
+  type        = string
+  default     = null
+}
+
+variable "request_timeout_seconds" {
+  description = "HTTP timeout in seconds for calls from the plugin to arrproxy"
+  type        = number
+  default     = 30
+}

modules/vault_cluster/modules/arrstack_secret_backend_role/main.tf

@@ -0,0 +1,7 @@
+resource "arrstack_secret_backend_role" "this" {
+  backend = var.backend
+  name    = var.name
+  apps    = var.apps
+  ttl     = var.ttl
+  max_ttl = var.max_ttl
+}

modules/vault_cluster/modules/arrstack_secret_backend_role/terraform.tf

@@ -0,0 +1,9 @@
+terraform {
+  required_version = ">= 1.10"
+  required_providers {
+    arrstack = {
+      source  = "artifactapi.k8s.syd1.au.unkin.net/terraform-unkin/vault-secrets-arrstack"
+      version = "0.1.0"
+    }
+  }
+}

modules/vault_cluster/modules/arrstack_secret_backend_role/variables.tf

@@ -0,0 +1,26 @@
+variable "name" {
+  description = "Name of the role"
+  type        = string
+}
+
+variable "backend" {
+  description = "Mount path of the arrstack secrets engine this role belongs to"
+  type        = string
+}
+
+variable "apps" {
+  description = "arr apps a generated key may access (subset of sonarr, radarr, prowlarr)"
+  type        = list(string)
+}
+
+variable "ttl" {
+  description = "Default lease TTL in seconds for keys generated from this role"
+  type        = number
+  default     = null
+}
+
+variable "max_ttl" {
+  description = "Maximum lease TTL in seconds for keys generated from this role"
+  type        = number
+  default     = null
+}

modules/vault_cluster/variables.tf

@@ -316,6 +316,30 @@ variable "litellm_secret_backend_role" {
   default = {}
 }
 
+variable "arrstack_secret_backend" {
+  description = "Map of arrstack secret engines to create (mount + config). The arrproxy admin token is read from KV"
+  type = map(object({
+    plugin                  = optional(string, "vault-plugin-secrets-arrstack")
+    description             = optional(string)
+    base_url                = string
+    ca_cert                 = optional(string)
+    request_timeout_seconds = optional(number, 30)
+  }))
+  default = {}
+}
+
+variable "arrstack_secret_backend_role" {
+  description = "Map of arrstack roles to create"
+  type = map(object({
+    name    = string
+    backend = string
+    apps    = list(string)
+    ttl     = optional(number)
+    max_ttl = optional(number)
+  }))
+  default = {}
+}
+
 variable "plugins" {
   description = "Map of plugins to import (register) in the catalog, keyed by catalog name"
   type = map(object({