101 lines
4.2 KiB
Markdown
101 lines
4.2 KiB
Markdown
# S5 App Onboarding Checklist
|
|
|
|
Use this checklist when adding a new user-facing Railiance workload to
|
|
`railiance-apps`. It turns the `vergabe-teilnahme` lessons into a repeatable
|
|
starting point so new app releases do not have to read the historical
|
|
workplans first.
|
|
|
|
## Scope And Planning
|
|
|
|
- [ ] Create or update a repo-local workplan under `workplans/`.
|
|
- [ ] Confirm the work is S5 app release wiring, not application source code,
|
|
forge runtime operation, platform service provisioning, or cluster addon work.
|
|
- [ ] Name the source application repo and the owning package/image release
|
|
path.
|
|
- [ ] Record upstream dependencies on `railiance-platform`, `railiance-forge`,
|
|
or `railiance-enablement` instead of hiding them in app values.
|
|
- [ ] Run State Hub consistency sync after task-status edits.
|
|
|
|
## Release Files
|
|
|
|
- [ ] Add a Helm chart under `charts/<app>/`.
|
|
- [ ] Add non-secret production values under `helm/<app>-values.yaml`.
|
|
- [ ] Add app-specific manifests under `manifests/` only when they do not fit
|
|
cleanly in the chart.
|
|
- [ ] Keep `image.tag` pinned by git SHA or immutable version.
|
|
- [ ] Keep committed values non-secret. Runtime secrets must come from
|
|
Kubernetes Secrets, approved SOPS files, or a platform secret-delivery path.
|
|
- [ ] Add Makefile targets for render, deploy, status, logs, migrations, and
|
|
any app-specific secret rebuild helpers.
|
|
|
|
## Image And Artifact Consumption
|
|
|
|
- [ ] Use a forge-owned image or package registry path.
|
|
- [ ] Link to source-repo publish instructions instead of duplicating build
|
|
pipelines here.
|
|
- [ ] Record the source commit, image tag, package version, and evidence needed
|
|
by the app runbook.
|
|
- [ ] For private images or packages, name the consuming Secret or approved
|
|
secret-delivery path without storing tokenized URLs.
|
|
- [ ] Verify a cluster can pull the image before promoting the release beyond
|
|
smoke-test use.
|
|
|
|
## Database And Runtime Secrets
|
|
|
|
- [ ] Request app database, role, and Secret handoff through
|
|
`railiance-platform` when using shared platform databases.
|
|
- [ ] Use an app-scoped database and role, for example `<app>_db` and `<app>`.
|
|
- [ ] Mirror only the app role credential into the app namespace.
|
|
- [ ] If the app consumes `DATABASE_URL`, URL-encode generated passwords before
|
|
writing the env Secret.
|
|
- [ ] Prefer separate PostgreSQL env vars when a framework does not require a
|
|
single DSN string.
|
|
- [ ] Document secret rotation commands without printing or committing secret
|
|
values.
|
|
|
|
## Ingress, TLS, And Probes
|
|
|
|
- [ ] Name the public host, namespace, Helm release, ingress, and TLS Secret in
|
|
the app runbook.
|
|
- [ ] Confirm ingress class and cert-manager issuer ownership with
|
|
`railiance-cluster`.
|
|
- [ ] Keep certificate lifecycle in cert-manager, not in app scripts.
|
|
- [ ] For framework apps with strict host validation, set HTTP probe `Host`
|
|
headers to a value included in the app's allowed hosts.
|
|
- [ ] Keep readiness and liveness paths stable and unauthenticated.
|
|
|
|
## Validation And Smoke Tests
|
|
|
|
- [ ] Run `make check-tools`.
|
|
- [ ] Run `make <app>-dry-run` or the equivalent Helm render before deploy.
|
|
- [ ] Run `make k8s-server-dry-run` against a representative cluster before
|
|
enforcing PR checks.
|
|
- [ ] Use the persistent-pod plus `kubectl exec` smoke pattern from
|
|
`docs/operator-recipes.md`.
|
|
- [ ] Capture app-level deployment evidence: dry-run result, rollout status,
|
|
HTTPS or service smoke check, migration result when applicable, and rollback
|
|
note.
|
|
|
|
## Runbook Baseline
|
|
|
|
Each S5 app runbook should include:
|
|
|
|
- identity table with URL, namespace, release, chart, values, ingress, image,
|
|
database, and TLS Secret;
|
|
- secrets and rotation section;
|
|
- day-to-day operator commands;
|
|
- image promotion steps;
|
|
- rollback behavior and migration warning;
|
|
- troubleshooting for probes, database URLs, TLS, and app-specific failure
|
|
modes;
|
|
- backup and restore readiness gate;
|
|
- cross-references to source repo, platform handoff docs, forge artifact docs,
|
|
and common S5 recipes.
|
|
|
|
## Done Gate
|
|
|
|
A new app is ready for routine S5 operation when an operator can deploy, verify,
|
|
roll back, inspect logs, rotate app-owned runtime secrets, understand upstream
|
|
data durability gates, and sync the workplan without reading old app-specific
|
|
history.
|