## Context
New service `payslip-ingest` (code lives in `/home/wizard/code/payslip-ingest/`)
needs in-cluster deployment, its own Postgres DB + rotating user, a Grafana
datasource, a dashboard, and a Claude agent definition for PDF extraction.
Cluster-internal only — webhook fires from Paperless-ngx in a sibling namespace.
No ingress, no TLS cert, no DNS record.
## What
### New stack `stacks/payslip-ingest/`
- `kubernetes_namespace` payslip-ingest, tier=aux.
- ExternalSecret (vault-kv) projects PAPERLESS_API_TOKEN, CLAUDE_AGENT_BEARER_TOKEN,
WEBHOOK_BEARER_TOKEN into `payslip-ingest-secrets`.
- ExternalSecret (vault-database) reads rotating password from
`static-creds/pg-payslip-ingest` and templates `DATABASE_URL` into
`payslip-ingest-db-creds` with `reloader.stakater.com/match=true`.
- Deployment: single replica, Recreate strategy (matches single-worker queue
design), `wait-for postgresql.dbaas:5432` annotation, init container runs
`alembic upgrade head`, main container serves FastAPI on 8080, Kyverno
dns_config lifecycle ignore.
- ClusterIP Service :8080.
- Grafana datasource ConfigMap in `monitoring` ns (label `grafana_datasource=1`,
uid `payslips-pg`) reading password from the db-creds K8s Secret.
### Grafana dashboard `uk-payslip.json` (4 panels)
- Monthly gross/net/tax/NI (timeseries, currencyGBP).
- YTD tax-band progression with threshold lines at £12,570 / £50,270 / £125,140.
- Deductions breakdown (stacked bars).
- Effective rate + take-home % (timeseries, percent).
### Vault DB role `pg-payslip-ingest`
- Added to `allowed_roles` in `vault_database_secret_backend_connection.postgresql`.
- New `vault_database_secret_backend_static_role.pg_payslip_ingest`
(username `payslip_ingest`, 7d rotation).
### DBaaS — DB + role creation
- New `null_resource.pg_payslip_ingest_db` mirrors `pg_terraform_state_db`:
idempotent CREATE ROLE + CREATE DATABASE + GRANT ALL via `kubectl exec` into
`pg-cluster-1`.
### Claude agent `.claude/agents/payslip-extractor.md`
- Haiku-backed agent invoked by `claude-agent-service`.
- Decodes base64 PDF from prompt, tries pdftotext → pypdf fallback, emits a single
JSON object matching the schema to stdout. No network, no file writes outside /tmp,
no markdown fences.
## Trade-offs / decisions
- Own DB per service (convention), NOT a schema in a shared `app` DB as the plan
initially described. The Alembic migration still creates a `payslip_ingest`
schema inside the `payslip_ingest` DB for table organisation.
- Paperless URL uses port 80 (the Service port), not 8000 (the pod target port).
- Grafana datasource uses the primary RW user — separate `_ro` role is aspirational
and not yet a pattern in this repo.
- No ingress — webhook is cluster-internal; external exposure is unnecessary attack
surface.
- No Uptime Kuma monitor yet: the internal-monitor list is a static block in
`stacks/uptime-kuma/`; will add in a follow-up tied to code-z29 (internal monitor
auto-creator).
## Test Plan
### Automated
```
terraform init -backend=false && terraform validate
Success! The configuration is valid.
terraform fmt -check -recursive
(exit 0)
python3 -c "import json; json.load(open('uk-payslip.json'))"
(exit 0)
```
### Manual Verification (post-merge)
Prerequisites:
1. Seed Vault: `vault kv put secret/payslip-ingest webhook_bearer_token=$(openssl rand -hex 32)`.
2. Seed Vault: `vault kv patch secret/paperless-ngx api_token=<paperless token>`.
Apply:
3. `scripts/tg apply vault` → creates pg-payslip-ingest static role.
4. `scripts/tg apply dbaas` → creates payslip_ingest DB + role.
5. `cd stacks/payslip-ingest && ../../scripts/tg apply -target=kubernetes_manifest.db_external_secret`
(first-apply ESO bootstrap).
6. `scripts/tg apply payslip-ingest` (full).
7. `kubectl -n payslip-ingest get pods` → Running 1/1.
8. `kubectl -n payslip-ingest port-forward svc/payslip-ingest 8080:8080 && curl localhost:8080/healthz` → 200.
End-to-end:
9. Configure Paperless workflow (README in code repo has steps).
10. Upload sample payslip tagged `payslip` → row in `payslip_ingest.payslip` within 60s.
11. Grafana → Dashboards → UK Payslip → 4 panels render.
Closes: code-do7
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
330 lines
8.2 KiB
HCL
330 lines
8.2 KiB
HCL
variable "image_tag" {
|
|
type = string
|
|
default = "latest"
|
|
description = "payslip-ingest image tag. Use 8-char git SHA in CI; :latest only for local trials."
|
|
}
|
|
|
|
variable "postgresql_host" { type = string }
|
|
|
|
locals {
|
|
namespace = "payslip-ingest"
|
|
image = "registry.viktorbarzin.me/payslip-ingest:${var.image_tag}"
|
|
labels = {
|
|
app = "payslip-ingest"
|
|
}
|
|
}
|
|
|
|
resource "kubernetes_namespace" "payslip_ingest" {
|
|
metadata {
|
|
name = local.namespace
|
|
labels = {
|
|
tier = local.tiers.aux
|
|
"istio-injection" = "disabled"
|
|
}
|
|
}
|
|
}
|
|
|
|
# App secrets sourced from multiple Vault KV keys.
|
|
# Seed these manually in Vault before applying:
|
|
# secret/paperless-ngx -> property `api_token`
|
|
# secret/claude-agent-service -> property `api_bearer_token`
|
|
# secret/payslip-ingest -> property `webhook_bearer_token`
|
|
resource "kubernetes_manifest" "external_secret" {
|
|
manifest = {
|
|
apiVersion = "external-secrets.io/v1beta1"
|
|
kind = "ExternalSecret"
|
|
metadata = {
|
|
name = "payslip-ingest-secrets"
|
|
namespace = local.namespace
|
|
}
|
|
spec = {
|
|
refreshInterval = "15m"
|
|
secretStoreRef = {
|
|
name = "vault-kv"
|
|
kind = "ClusterSecretStore"
|
|
}
|
|
target = {
|
|
name = "payslip-ingest-secrets"
|
|
template = {
|
|
metadata = {
|
|
annotations = {
|
|
"reloader.stakater.com/match" = "true"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
data = [
|
|
{
|
|
secretKey = "PAPERLESS_API_TOKEN"
|
|
remoteRef = {
|
|
key = "paperless-ngx"
|
|
property = "api_token"
|
|
}
|
|
},
|
|
{
|
|
secretKey = "CLAUDE_AGENT_BEARER_TOKEN"
|
|
remoteRef = {
|
|
key = "claude-agent-service"
|
|
property = "api_bearer_token"
|
|
}
|
|
},
|
|
{
|
|
secretKey = "WEBHOOK_BEARER_TOKEN"
|
|
remoteRef = {
|
|
key = "payslip-ingest"
|
|
property = "webhook_bearer_token"
|
|
}
|
|
},
|
|
]
|
|
}
|
|
}
|
|
depends_on = [kubernetes_namespace.payslip_ingest]
|
|
}
|
|
|
|
# DB credentials from Vault database engine (rotated every 7 days).
|
|
# Template builds the asyncpg DSN consumed by the FastAPI app as DB_CONNECTION_STRING.
|
|
resource "kubernetes_manifest" "db_external_secret" {
|
|
manifest = {
|
|
apiVersion = "external-secrets.io/v1beta1"
|
|
kind = "ExternalSecret"
|
|
metadata = {
|
|
name = "payslip-ingest-db-creds"
|
|
namespace = local.namespace
|
|
}
|
|
spec = {
|
|
refreshInterval = "15m"
|
|
secretStoreRef = {
|
|
name = "vault-database"
|
|
kind = "ClusterSecretStore"
|
|
}
|
|
target = {
|
|
name = "payslip-ingest-db-creds"
|
|
template = {
|
|
metadata = {
|
|
annotations = {
|
|
"reloader.stakater.com/match" = "true"
|
|
}
|
|
}
|
|
data = {
|
|
DB_CONNECTION_STRING = "postgresql+asyncpg://payslip_ingest:{{ .password }}@${var.postgresql_host}:5432/payslip_ingest"
|
|
DB_PASSWORD = "{{ .password }}"
|
|
}
|
|
}
|
|
}
|
|
data = [{
|
|
secretKey = "password"
|
|
remoteRef = {
|
|
key = "static-creds/pg-payslip-ingest"
|
|
property = "password"
|
|
}
|
|
}]
|
|
}
|
|
}
|
|
depends_on = [kubernetes_namespace.payslip_ingest]
|
|
}
|
|
|
|
resource "kubernetes_deployment" "payslip_ingest" {
|
|
metadata {
|
|
name = "payslip-ingest"
|
|
namespace = kubernetes_namespace.payslip_ingest.metadata[0].name
|
|
labels = merge(local.labels, {
|
|
tier = local.tiers.aux
|
|
})
|
|
annotations = {
|
|
"reloader.stakater.com/search" = "true"
|
|
}
|
|
}
|
|
|
|
spec {
|
|
replicas = 1
|
|
strategy {
|
|
type = "Recreate"
|
|
}
|
|
|
|
selector {
|
|
match_labels = local.labels
|
|
}
|
|
|
|
template {
|
|
metadata {
|
|
labels = local.labels
|
|
annotations = {
|
|
"dependency.kyverno.io/wait-for" = "postgresql.dbaas:5432"
|
|
}
|
|
}
|
|
|
|
spec {
|
|
image_pull_secrets {
|
|
name = "registry-credentials"
|
|
}
|
|
|
|
init_container {
|
|
name = "alembic-migrate"
|
|
image = local.image
|
|
command = ["python", "-m", "payslip_ingest", "migrate"]
|
|
|
|
env_from {
|
|
secret_ref {
|
|
name = "payslip-ingest-secrets"
|
|
}
|
|
}
|
|
env_from {
|
|
secret_ref {
|
|
name = "payslip-ingest-db-creds"
|
|
}
|
|
}
|
|
|
|
env {
|
|
name = "PAPERLESS_URL"
|
|
value = "http://paperless-ngx.paperless-ngx.svc.cluster.local"
|
|
}
|
|
env {
|
|
name = "CLAUDE_AGENT_URL"
|
|
value = "http://claude-agent-service.claude-agent.svc.cluster.local:8080"
|
|
}
|
|
|
|
resources {
|
|
requests = {
|
|
cpu = "50m"
|
|
memory = "256Mi"
|
|
}
|
|
limits = {
|
|
memory = "512Mi"
|
|
}
|
|
}
|
|
}
|
|
|
|
container {
|
|
name = "payslip-ingest"
|
|
image = local.image
|
|
|
|
port {
|
|
container_port = 8080
|
|
}
|
|
|
|
env_from {
|
|
secret_ref {
|
|
name = "payslip-ingest-secrets"
|
|
}
|
|
}
|
|
env_from {
|
|
secret_ref {
|
|
name = "payslip-ingest-db-creds"
|
|
}
|
|
}
|
|
|
|
env {
|
|
name = "PAPERLESS_URL"
|
|
value = "http://paperless-ngx.paperless-ngx.svc.cluster.local"
|
|
}
|
|
env {
|
|
name = "CLAUDE_AGENT_URL"
|
|
value = "http://claude-agent-service.claude-agent.svc.cluster.local:8080"
|
|
}
|
|
|
|
readiness_probe {
|
|
http_get {
|
|
path = "/healthz"
|
|
port = 8080
|
|
}
|
|
initial_delay_seconds = 5
|
|
period_seconds = 10
|
|
}
|
|
|
|
liveness_probe {
|
|
http_get {
|
|
path = "/healthz"
|
|
port = 8080
|
|
}
|
|
initial_delay_seconds = 5
|
|
period_seconds = 10
|
|
}
|
|
|
|
resources {
|
|
requests = {
|
|
cpu = "50m"
|
|
memory = "256Mi"
|
|
}
|
|
limits = {
|
|
memory = "512Mi"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
lifecycle {
|
|
ignore_changes = [spec[0].template[0].spec[0].dns_config] # KYVERNO_LIFECYCLE_V1
|
|
}
|
|
|
|
depends_on = [
|
|
kubernetes_manifest.external_secret,
|
|
kubernetes_manifest.db_external_secret,
|
|
]
|
|
}
|
|
|
|
# ClusterIP-only — webhook is cluster-internal (paperless-ngx -> payslip-ingest).
|
|
resource "kubernetes_service" "payslip_ingest" {
|
|
metadata {
|
|
name = "payslip-ingest"
|
|
namespace = kubernetes_namespace.payslip_ingest.metadata[0].name
|
|
labels = local.labels
|
|
}
|
|
|
|
spec {
|
|
type = "ClusterIP"
|
|
selector = local.labels
|
|
|
|
port {
|
|
name = "http"
|
|
port = 8080
|
|
target_port = 8080
|
|
}
|
|
}
|
|
}
|
|
|
|
# Plan-time read of the ESO-created K8s Secret for Grafana datasource password.
|
|
# First apply: -target=kubernetes_manifest.db_external_secret first so the Secret exists.
|
|
data "kubernetes_secret" "payslip_ingest_db_creds" {
|
|
metadata {
|
|
name = "payslip-ingest-db-creds"
|
|
namespace = kubernetes_namespace.payslip_ingest.metadata[0].name
|
|
}
|
|
depends_on = [kubernetes_manifest.db_external_secret]
|
|
}
|
|
|
|
# Grafana datasource for payslip_ingest PostgreSQL DB.
|
|
# Lives in the monitoring namespace so the grafana sidecar (label grafana_datasource=1) picks it up.
|
|
resource "kubernetes_config_map" "grafana_payslips_datasource" {
|
|
metadata {
|
|
name = "grafana-payslips-datasource"
|
|
namespace = "monitoring"
|
|
labels = {
|
|
grafana_datasource = "1"
|
|
}
|
|
}
|
|
data = {
|
|
"payslips-datasource.yaml" = yamlencode({
|
|
apiVersion = 1
|
|
datasources = [{
|
|
name = "Payslips"
|
|
type = "postgres"
|
|
access = "proxy"
|
|
url = "${var.postgresql_host}:5432"
|
|
database = "payslip_ingest"
|
|
user = "payslip_ingest"
|
|
uid = "payslips-pg"
|
|
jsonData = {
|
|
sslmode = "disable"
|
|
postgresVersion = 1600
|
|
timescaledb = false
|
|
}
|
|
secureJsonData = {
|
|
password = data.kubernetes_secret.payslip_ingest_db_creds.data["DB_PASSWORD"]
|
|
}
|
|
editable = true
|
|
}]
|
|
})
|
|
}
|
|
}
|