Add Railiance staged-promotion overlay for flex-auth
FLEX-WP-0011 T01/T02: railiance.app.v1 contract, independently pinned Helm values for tenant-engine and user-engine, isolated canary cycle (deploy/observe/promote/rollback), and emergency kubectl path retained. T03 waits on the custodian drain-plan row.
This commit is contained in:
parent
804251514c
commit
1d58f13eb8
19 changed files with 634 additions and 14 deletions
82
railiance/README.md
Normal file
82
railiance/README.md
Normal file
|
|
@ -0,0 +1,82 @@
|
|||
# flex-auth Railiance overlay
|
||||
|
||||
Canonical staged-promotion contract for flex-auth (`RAIL-BS-WP-0006`,
|
||||
`FLEX-WP-0011`). The recovered `deploy/*.yaml` files remain as an emergency
|
||||
kubectl path; this overlay is the sanctioned shape.
|
||||
|
||||
## Layout
|
||||
|
||||
| Path | Role |
|
||||
| --- | --- |
|
||||
| `railiance/app.toml` | `railiance.app.v1` contract |
|
||||
| `charts/flex-auth/` | One Deployment + Service + NetworkPolicy per release |
|
||||
| `values/tenant-engine.yaml` | Production pin for `flex-auth-tenant-engine` |
|
||||
| `values/user-engine.yaml` | Production pin for `flex-auth-user-engine` |
|
||||
| `values/stage2-canary.yaml` | Isolated canary `flex-auth-canary` (no consumer ingress) |
|
||||
| `values/stage3-production.yaml` | Stage 3 values for that same isolated canary release |
|
||||
| `tests/stage1.sh` | Local render of every values file |
|
||||
|
||||
The two production consumers stay independently pinned and independently
|
||||
rollable. Do not collapse them into one Helm release. The official
|
||||
`bin/railiance deploy|observe|promote|rollback` cycle operates on the
|
||||
**isolated canary** so it cannot move a production pin by accident.
|
||||
|
||||
## Stage 1
|
||||
|
||||
```bash
|
||||
tests/stage1.sh
|
||||
# or
|
||||
/home/worsch/railiance-bootstrap/bin/railiance run . --pretty
|
||||
```
|
||||
|
||||
## Stage 2 / Stage 3 (isolated canary)
|
||||
|
||||
```bash
|
||||
RAILIANCE=/home/worsch/railiance-bootstrap/bin/railiance
|
||||
$RAILIANCE deploy --stage 2 . --plan
|
||||
$RAILIANCE deploy --stage 2 . --server-dry-run --pretty
|
||||
$RAILIANCE deploy --stage 2 . --apply --approval-id <state-hub-id>
|
||||
$RAILIANCE observe --stage 2 . --live --pretty
|
||||
$RAILIANCE promote . --plan
|
||||
$RAILIANCE promote . --apply --approval-id <state-hub-id>
|
||||
$RAILIANCE rollback . --apply --approval-id <state-hub-id> --revision <helm-rev>
|
||||
```
|
||||
|
||||
The canary Service is `flex-auth-canary.flex-auth.svc.cluster.local:8080`.
|
||||
Production consumers keep calling their own Service names.
|
||||
|
||||
## Rolling a production pin
|
||||
|
||||
Policy is baked into the image. Do not build images on a workstation.
|
||||
`.forgejo/workflows/image.yaml` publishes `:latest` and `:main-<short-sha>`;
|
||||
deploy by digest.
|
||||
|
||||
```bash
|
||||
# 1. Edit the digest in values/<consumer>.yaml
|
||||
# 2. Record the previous digest as the rollback target
|
||||
# 3. Apply only that release
|
||||
helm upgrade --install flex-auth-<consumer> charts/flex-auth \
|
||||
--namespace flex-auth -f values/<consumer>.yaml --wait --timeout 2m
|
||||
|
||||
# 4. Prove the new policy, not just that the pod started
|
||||
kubectl -n flex-auth port-forward svc/flex-auth-<consumer> 19099:8080
|
||||
curl -s -X POST http://127.0.0.1:19099/v1/check \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d @examples/<consumer>/<request that exercises the change>.json
|
||||
```
|
||||
|
||||
Emergency kubectl path (no Helm history): `kubectl apply -f deploy/flex-auth-<consumer>.yaml`.
|
||||
|
||||
## Rollback
|
||||
|
||||
Preferred: `helm rollback flex-auth-<consumer> <revision> -n flex-auth --wait`.
|
||||
|
||||
If Helm history is missing: `kubectl -n flex-auth rollout undo deploy/flex-auth-<consumer>`,
|
||||
or re-apply the last-known-good digest in `deploy/README.md`.
|
||||
|
||||
| Deployment | Last-known-good digest | Policy state |
|
||||
| --- | --- | --- |
|
||||
| `flex-auth-tenant-engine` | `sha256:c25fc34a6cd7e64d955f8723ec70e176a583d5ae71d76280c4e2d89fba0fe0aa` | **live 2026-08-16** — four-action policy; lifecycle actions deny `unknown_action` |
|
||||
| `flex-auth-tenant-engine` *(FLEX-WP-0010 image, scaled to 0)* | `sha256:9320df394a642eff24da8af4a0ee8886a7bb78b0f14d8ee1deeb30ea8eeeaba7` | seven-action policy, previously live 2026-08-11 |
|
||||
| `flex-auth-user-engine` | `sha256:1f5290376dc5fcf456dc7a785e394d8b90949dabecd1d3e856f38557149bb5f4` | FLEX-WP-0009-T04, nine fixtures, live 2026-08-16 |
|
||||
| `flex-auth-user-engine` *(previous)* | `sha256:a31961c45215aa6baf3bc748c6741ab703c2c8325e61aa7983a355026195e51b` | FLEX-WP-0009-T03, six fixtures |
|
||||
188
railiance/app.toml
Normal file
188
railiance/app.toml
Normal file
|
|
@ -0,0 +1,188 @@
|
|||
schema_version = "railiance.app.v1"
|
||||
|
||||
[app]
|
||||
id = "flex-auth"
|
||||
name = "flex-auth"
|
||||
repo = "flex-auth"
|
||||
owner = "platform-security"
|
||||
criticality = "high"
|
||||
description = "Policy-as-code authorization PDP. Two independently pinned production Deployments (tenant-engine, user-engine). Outage fails closed: consumers receive deny/403 rather than an unauthorized allow, but write paths block."
|
||||
|
||||
[source]
|
||||
revision = "git:main"
|
||||
artifact = "image"
|
||||
digest_policy = "required"
|
||||
|
||||
[rollback]
|
||||
strategy = "helm-revision"
|
||||
command = "helm rollback <release> <revision> --namespace flex-auth --wait"
|
||||
verification = "Both Services' /healthz return 200 and the rolled-back Deployment image digest matches the recorded previous_stable pin."
|
||||
|
||||
[[platform.dependencies]]
|
||||
name = "railiance01-k3s"
|
||||
kind = "network"
|
||||
required = true
|
||||
stage = "stage2"
|
||||
evidence = "kubectl -n flex-auth get ns reports Active on railiance01."
|
||||
|
||||
[[platform.dependencies]]
|
||||
name = "forgejo-oci"
|
||||
kind = "other"
|
||||
required = true
|
||||
stage = "stage2"
|
||||
evidence = "Image forgejo.coulomb.social/coulomb/flex-auth is pullable by digest."
|
||||
|
||||
[secrets]
|
||||
references = []
|
||||
|
||||
[[observability.health_endpoints]]
|
||||
name = "local-health"
|
||||
url = "http://127.0.0.1:8080/healthz"
|
||||
stage = "stage1"
|
||||
expected_status = 200
|
||||
|
||||
[[observability.health_endpoints]]
|
||||
name = "tenant-engine-health"
|
||||
url = "http://flex-auth-tenant-engine.flex-auth.svc.cluster.local:8080/healthz"
|
||||
stage = "stage2"
|
||||
expected_status = 200
|
||||
|
||||
[[observability.health_endpoints]]
|
||||
name = "user-engine-health"
|
||||
url = "http://flex-auth-user-engine.flex-auth.svc.cluster.local:8080/healthz"
|
||||
stage = "stage2"
|
||||
expected_status = 200
|
||||
|
||||
[[observability.health_endpoints]]
|
||||
name = "canary-health"
|
||||
url = "http://flex-auth-canary.flex-auth.svc.cluster.local:8080/healthz"
|
||||
stage = "stage2"
|
||||
expected_status = 200
|
||||
|
||||
[[observability.logs]]
|
||||
name = "canary-pods"
|
||||
reference = "kubectl -n flex-auth logs deploy/flex-auth-canary --tail=50"
|
||||
stage = "stage2"
|
||||
|
||||
[stages.stage1]
|
||||
enabled = true
|
||||
namespace = "local"
|
||||
release = "flex-auth-local"
|
||||
commands = ["make test", "tests/stage1.sh"]
|
||||
checks = ["unit-tests", "helm-template", "contract-schema"]
|
||||
evidence = ["go test output", "helm template of tenant-engine, user-engine, and canary values", "app.toml schema validation"]
|
||||
requires_approval = false
|
||||
|
||||
[stages.stage2]
|
||||
enabled = true
|
||||
namespace = "flex-auth"
|
||||
release = "flex-auth-canary"
|
||||
commands = ["bin/railiance deploy --stage 2 . --plan", "bin/railiance observe --stage 2 . --plan"]
|
||||
checks = ["server-dry-run", "canary-ready", "canary-health", "operator-approval"]
|
||||
evidence = ["isolated canary release name", "pod Available", "canary /healthz 200", "State Hub approval id"]
|
||||
requires_approval = true
|
||||
canary_mode = "isolated"
|
||||
observation_minutes = 15
|
||||
|
||||
[stages.stage3]
|
||||
enabled = true
|
||||
namespace = "flex-auth"
|
||||
release = "flex-auth-canary"
|
||||
commands = ["bin/railiance promote . --plan", "bin/railiance rollback . --plan"]
|
||||
checks = ["stage2-accepted", "rollback-target", "operator-approval"]
|
||||
evidence = ["promotion command id", "recorded previous_stable digests", "post-promotion canary /healthz 200"]
|
||||
requires_approval = true
|
||||
promotion_mode = "release-replace"
|
||||
previous_stable = "flex-auth-user-engine@sha256:1f5290376dc5fcf456dc7a785e394d8b90949dabecd1d3e856f38557149bb5f4;flex-auth-tenant-engine@sha256:c25fc34a6cd7e64d955f8723ec70e176a583d5ae71d76280c4e2d89fba0fe0aa"
|
||||
|
||||
[[checks]]
|
||||
id = "unit-tests"
|
||||
type = "command"
|
||||
stage = "stage1"
|
||||
description = "Run repository Go tests."
|
||||
required = true
|
||||
run = "make test"
|
||||
timeout_seconds = 600
|
||||
|
||||
[[checks]]
|
||||
id = "helm-template"
|
||||
type = "helm"
|
||||
stage = "stage1"
|
||||
description = "Render the isolated canary chart locally."
|
||||
required = true
|
||||
chart = "charts/flex-auth"
|
||||
values = "values/stage2-canary.yaml"
|
||||
mode = "template"
|
||||
|
||||
[[checks]]
|
||||
id = "contract-schema"
|
||||
type = "command"
|
||||
stage = "stage1"
|
||||
description = "Validate railiance/app.toml against railiance.app.v1."
|
||||
required = true
|
||||
run = "python3 tests/validate_app_toml.py"
|
||||
timeout_seconds = 60
|
||||
|
||||
[[checks]]
|
||||
id = "local-health"
|
||||
type = "http"
|
||||
stage = "stage1"
|
||||
description = "Confirm a locally served flex-auth /healthz when one is running."
|
||||
required = false
|
||||
url = "http://127.0.0.1:8080/healthz"
|
||||
expected_status = 200
|
||||
timeout_seconds = 10
|
||||
|
||||
[[checks]]
|
||||
id = "server-dry-run"
|
||||
type = "helm"
|
||||
stage = "stage2"
|
||||
description = "Server-side dry run of the isolated canary before apply."
|
||||
required = true
|
||||
chart = "charts/flex-auth"
|
||||
values = "values/stage2-canary.yaml"
|
||||
mode = "server-dry-run"
|
||||
|
||||
[[checks]]
|
||||
id = "canary-ready"
|
||||
type = "kubernetes"
|
||||
stage = "stage2"
|
||||
description = "Isolated canary Deployment reaches Available."
|
||||
required = true
|
||||
namespace = "flex-auth"
|
||||
resource = "deploy/flex-auth-canary"
|
||||
condition = "Available"
|
||||
|
||||
[[checks]]
|
||||
id = "canary-health"
|
||||
type = "http"
|
||||
stage = "stage2"
|
||||
description = "Isolated canary Service /healthz returns 200."
|
||||
required = true
|
||||
url = "http://flex-auth-canary.flex-auth.svc.cluster.local:8080/healthz"
|
||||
expected_status = 200
|
||||
timeout_seconds = 10
|
||||
|
||||
[[checks]]
|
||||
id = "operator-approval"
|
||||
type = "manual"
|
||||
stage = "stage2"
|
||||
description = "Human approval recorded before the isolated canary is applied and before any production pin is moved."
|
||||
required = true
|
||||
evidence_required = "State Hub approval note id, candidate digest, rollback target (both production pins)."
|
||||
|
||||
[[checks]]
|
||||
id = "stage2-accepted"
|
||||
type = "manual"
|
||||
stage = "stage3"
|
||||
description = "Stage 2 gates passed for the same candidate artifact."
|
||||
required = true
|
||||
evidence_required = "State Hub Stage 2 acceptance progress id."
|
||||
|
||||
[[checks]]
|
||||
id = "rollback-target"
|
||||
type = "manual"
|
||||
stage = "stage3"
|
||||
description = "Previous stable digest of each independently rollable Deployment is recorded before promotion."
|
||||
required = true
|
||||
evidence_required = "flex-auth-user-engine and flex-auth-tenant-engine image digests."
|
||||
Loading…
Add table
Add a link
Reference in a new issue