72 lines
4.0 KiB
Markdown
72 lines
4.0 KiB
Markdown
# Federated Tier Setup Guide
|
|
|
|
> **KBN-101 N-1 hold:** This page is **non-operative** until KBN-101-08 activates a
|
|
> reviewed release. It does not authorize a deployment operation, initialization artifacts,
|
|
> implicit extension/schema/migration creation, raw `CREATE`, direct database initialization, or
|
|
> a Gateway against an unverified database. The prior direct-start wording is retired; its
|
|
> regression fixture is owned by KBN-101-06.
|
|
|
|
## Activation-only sequence
|
|
|
|
The deployment control plane—not an operator shell or deployment lifecycle hook—performs this
|
|
exact sequence after activation authorization:
|
|
|
|
1. External privileged bootstrap provisions the approved database/extension prerequisites.
|
|
2. The renderer installs the generation-pinned verified-TLS materials and roles.
|
|
3. The dedicated one-shot runner executes `mosaic-db-migrator --run`.
|
|
4. The same runner executes `mosaic-db-migrator --verify`, including readiness and the
|
|
importer-target attestation where that route is enabled.
|
|
5. Only after successful verification may Gateway reach its independent verified-TLS Gateway
|
|
readiness gate.
|
|
|
|
No step may be reordered, skipped, replaced by a raw SQL command, or delegated to an initialization
|
|
hook.
|
|
A missing extension, schema, migration, role, secret generation, or readiness proof is a failed
|
|
control-plane precondition; it is not an instruction to start Compose, retry startup, or create
|
|
anything directly.
|
|
|
|
## N-1 status and required disposition
|
|
|
|
The current branch retains historical federation artifacts, but they are not a deployable
|
|
procedure. `docs/federation/TASKS.md` records their shipped status only. KBN-101-02 retires
|
|
runtime/init DDL; KBN-101-05 owns the renderer/deployment handoff; KBN-101-06 verifies the
|
|
finite scanner and command matrix; and KBN-101-07 owns this operator route. A path named in an
|
|
inventory, a historical-status label, or a normative requirement cannot suppress the semantic
|
|
checks above.
|
|
|
|
Until the activation certificate names an exact release, use no database startup or recovery
|
|
command from this document. For the produced importer interface, see
|
|
[the federated tier migration contract](../guides/migrate-tier.md); it is likewise non-operative
|
|
until activation.
|
|
|
|
## Federation and Step-CA reference
|
|
|
|
Federation uses PostgreSQL 17 with pgvector, Valkey, and a shared configuration across multiple
|
|
Gateway instances. Step-CA issues federation peer X.509 certificates whose custom OIDs carry a
|
|
grant and subject identity. The following facts are reference material only; provisioning and
|
|
secret delivery remain deployment-control-plane work under the activation sequence.
|
|
|
|
| OID | Name | Description |
|
|
| ------------------- | ------------------------ | --------------------- |
|
|
| 1.3.6.1.4.1.99999.1 | `mosaic_grant_id` | Federation grant UUID |
|
|
| 1.3.6.1.4.1.99999.2 | `mosaic_subject_user_id` | Subject user UUID |
|
|
|
|
The internal arc `1.3.6.1.4.1.99999` is development-only. Before an externally reachable
|
|
production deployment, register an IANA Private Enterprise Number and version the assignments.
|
|
Each value is DER-encoded as an ASN.1 UTF8String containing the UUID.
|
|
|
|
The future activated Gateway requires `STEP_CA_URL`, `STEP_CA_PROVISIONER_PASSWORD`,
|
|
`STEP_CA_PROVISIONER_KEY_JSON`, `STEP_CA_ROOT_CERT_PATH`, and `BETTER_AUTH_SECRET` through the
|
|
reviewed secret mechanism. These names do not authorize shell exports, copied credential files,
|
|
or an ad hoc service start.
|
|
|
|
## Failure disposition
|
|
|
|
- A TLS, CA, SAN, role, runner, or readiness failure is a control-plane incident. Preserve only
|
|
sanitized evidence and follow the approved rollback/repair record.
|
|
- A pgvector/extension failure is a failed external-bootstrap or runner precondition. Do not use
|
|
direct extension SQL, init artifacts, or a startup retry as remediation.
|
|
- A port, container, or Valkey problem does not permit bypassing the activation sequence.
|
|
- Federation peer-key rotation remains deferred until its separately approved migration plan;
|
|
do not rotate `BETTER_AUTH_SECRET` without that plan.
|