generated from coulomb/repo-seed
WARDEN-WP-0005: OpenBao-first documentation alignment
Document OpenBao as the platform production secrets service while keeping the vault-compatible warden.yaml config shape. Update OpsWardenConfig, SCOPE, and CertCommandInterface cross-references.
This commit is contained in:
@@ -14,8 +14,9 @@ SSH certificate for a named actor. The caller passes the cert to the SSH process
|
||||
the actor's private key.
|
||||
|
||||
This interface is intentionally tool-agnostic: the caller (`ops-bridge`, a script, a CI
|
||||
pipeline) does not need to know whether the CA is a local file or HashiCorp Vault. Any
|
||||
command that writes a cert to stdout and exits 0 satisfies the contract.
|
||||
pipeline) does not need to know whether the CA is a local file, OpenBao, or another
|
||||
Vault-compatible SSH secrets engine. Any command that writes a cert to stdout and exits 0
|
||||
satisfies the contract.
|
||||
|
||||
---
|
||||
|
||||
@@ -30,7 +31,7 @@ warden sign <actor-name> --pubkey <path/to/actor.pub>
|
||||
Or any equivalent shell command:
|
||||
|
||||
```
|
||||
vault write -field=signed_key ssh/sign/agt-role public_key=@/tmp/key.pub
|
||||
bao write -field=signed_key ssh/sign/agt-role public_key=@/tmp/key.pub
|
||||
ssh-keygen -s /path/to/ca -I agt-test -n agt-task -V +24h /tmp/key.pub && cat /tmp/key-cert.pub
|
||||
```
|
||||
|
||||
|
||||
@@ -4,19 +4,36 @@ Config file: `~/.config/warden/warden.yaml` (override with `WARDEN_CONFIG` env v
|
||||
|
||||
---
|
||||
|
||||
## Local Backend (lab / non-Vault)
|
||||
## Backend overview
|
||||
|
||||
| Backend | Config value | Use when |
|
||||
|---------|--------------|----------|
|
||||
| Local CA | `backend: local` | Labs, CI, air-gapped dev, hosts without platform secrets access |
|
||||
| Platform CA | `backend: vault` | Production and shared ops environments |
|
||||
|
||||
**Platform standard:** Railiance S3 uses [OpenBao](https://openbao.org/) as the
|
||||
runtime platform secrets service (`RAIL-PL-WP-0002` in `railiance-platform`).
|
||||
OpenBao exposes a **Vault-compatible HTTP API**, so ops-warden keeps the config
|
||||
keys `backend: vault` and the `vault:` block — no separate OpenBao backend name
|
||||
is required. The same config works against OpenBao or HashiCorp Vault if you point
|
||||
`vault.addr` at either service.
|
||||
|
||||
ops-warden signs SSH certificates only. It does **not** deploy OpenBao, manage
|
||||
unseal keys, or store long-lived API secrets. Cluster bootstrap and custody live
|
||||
in `railiance-platform` and NetKingdom docs.
|
||||
|
||||
---
|
||||
|
||||
## Local backend (lab / offline)
|
||||
|
||||
```yaml
|
||||
# Backend selection. "local" uses ssh-keygen -s with a CA key on disk.
|
||||
# Uses ssh-keygen -s with a CA private key on disk.
|
||||
backend: local
|
||||
|
||||
# Path to the CA private key. Keep this file mode 600 and never commit it.
|
||||
ca_key: ~/.ssh/ops-ca-user
|
||||
|
||||
# Path to the principals inventory (default shown).
|
||||
inventory_path: ~/.config/warden/inventory.yaml
|
||||
|
||||
# Where to store signed certs and generated keypairs (default shown).
|
||||
state_dir: ~/.local/state/warden
|
||||
```
|
||||
|
||||
@@ -35,48 +52,126 @@ chmod 644 ~/.ssh/ops-ca-user.pub
|
||||
|
||||
---
|
||||
|
||||
## Vault Backend (production)
|
||||
## OpenBao / Vault-compatible backend (production)
|
||||
|
||||
Use this backend against the platform OpenBao instance or any other SSH secrets
|
||||
engine that implements the Vault signing API (`POST /v1/<mount>/sign/<role>`).
|
||||
|
||||
### Example — Railiance01 (browser / operator workstation)
|
||||
|
||||
```yaml
|
||||
backend: vault
|
||||
|
||||
vault:
|
||||
# Vault server address.
|
||||
addr: https://vault.example.com
|
||||
# OpenBao UI/API (KeyCape OIDC). Prefer short-lived tokens from policy, not root.
|
||||
addr: https://bao.coulomb.social
|
||||
|
||||
# Vault SSH secrets engine mount path (default: ssh).
|
||||
mount: ssh
|
||||
|
||||
# Map from ActorType to Vault signing role name.
|
||||
role_map:
|
||||
adm: adm-role
|
||||
agt: agt-role
|
||||
atm: atm-role
|
||||
|
||||
# Environment variable holding the Vault token (default: VAULT_TOKEN).
|
||||
# OpenBao accepts the same X-Vault-Token header name as Vault.
|
||||
token_env: VAULT_TOKEN
|
||||
|
||||
inventory_path: ~/.config/warden/inventory.yaml
|
||||
state_dir: ~/.local/state/warden
|
||||
```
|
||||
|
||||
### Vault setup snippet
|
||||
### Example — in-cluster caller (pod or trusted host)
|
||||
|
||||
```yaml
|
||||
backend: vault
|
||||
|
||||
vault:
|
||||
addr: http://openbao.openbao.svc.cluster.local:8200
|
||||
mount: ssh
|
||||
role_map:
|
||||
adm: adm-role
|
||||
agt: agt-role
|
||||
atm: atm-role
|
||||
token_env: VAULT_TOKEN
|
||||
```
|
||||
|
||||
Choose the `addr` that matches where `warden` runs: operators on a laptop use
|
||||
the external HTTPS endpoint; workloads inside the cluster use the internal
|
||||
service URL. See `railiance-platform/docs/openbao.md` for deployment and access
|
||||
paths.
|
||||
|
||||
### Authentication
|
||||
|
||||
Export a token with permission to sign against the mapped roles:
|
||||
|
||||
```bash
|
||||
vault secrets enable ssh
|
||||
vault write ssh/roles/agt-role \
|
||||
# After OIDC login or policy-issued token (OpenBao CLI)
|
||||
export VAULT_TOKEN="<short-lived-token>"
|
||||
|
||||
# Or HashiCorp Vault CLI against a Vault-compatible endpoint
|
||||
vault login
|
||||
```
|
||||
|
||||
`warden` reads the token from the env var named in `vault.token_env` (default
|
||||
`VAULT_TOKEN`). OpenBao uses the same header; you do not need a separate
|
||||
`BAO_TOKEN` unless you configure `token_env` that way.
|
||||
|
||||
On failure, `warden sign` suggests falling back to `--backend local` only for
|
||||
lab recovery — not as a production substitute.
|
||||
|
||||
### SSH secrets engine setup (OpenBao)
|
||||
|
||||
Run once per environment after OpenBao is initialized and unsealed. Adjust TTL
|
||||
limits to match `ActorType` policy in `wiki/AccessManagementDirective.md`
|
||||
(adm 48 h, agt 24 h, atm 8 h).
|
||||
|
||||
```bash
|
||||
# OpenBao CLI (bao) — preferred on Railiance
|
||||
bao secrets enable ssh
|
||||
|
||||
bao write ssh/roles/agt-role \
|
||||
key_type=ca \
|
||||
allowed_users="*" \
|
||||
allow_user_certificates=true \
|
||||
default_user="agt" \
|
||||
ttl=24h max_ttl=24h
|
||||
|
||||
export VAULT_TOKEN=$(vault token create -field=token)
|
||||
bao write ssh/roles/adm-role \
|
||||
key_type=ca \
|
||||
allowed_users="*" \
|
||||
allow_user_certificates=true \
|
||||
default_user="adm" \
|
||||
ttl=48h max_ttl=48h
|
||||
|
||||
bao write ssh/roles/atm-role \
|
||||
key_type=ca \
|
||||
allowed_users="*" \
|
||||
allow_user_certificates=true \
|
||||
default_user="atm" \
|
||||
ttl=8h max_ttl=8h
|
||||
```
|
||||
|
||||
HashiCorp Vault uses the same paths with the `vault` CLI:
|
||||
|
||||
```bash
|
||||
vault secrets enable ssh
|
||||
vault write ssh/roles/agt-role key_type=ca ... # same role parameters
|
||||
```
|
||||
|
||||
Mount path defaults to `ssh`; override with `vault.mount` in `warden.yaml` if
|
||||
your engine lives elsewhere.
|
||||
|
||||
### Platform references
|
||||
|
||||
| Topic | Location |
|
||||
|-------|----------|
|
||||
| OpenBao deploy, unseal, OIDC admin | `railiance-platform/docs/openbao.md` |
|
||||
| Host CA trust and principals | `railiance-infra` Ansible playbooks |
|
||||
| Signing contract for callers | `wiki/CertCommandInterface.md` |
|
||||
|
||||
---
|
||||
|
||||
## Principals Inventory (`inventory.yaml`)
|
||||
## Principals inventory (`inventory.yaml`)
|
||||
|
||||
```yaml
|
||||
actors:
|
||||
@@ -117,12 +212,12 @@ hosts:
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
## Environment variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|---|---|---|
|
||||
|----------|---------|-------------|
|
||||
| `WARDEN_CONFIG` | `~/.config/warden/warden.yaml` | Config file path |
|
||||
| `VAULT_TOKEN` | — | Vault token (vault backend only; env var name is configurable) |
|
||||
| `VAULT_TOKEN` | — | API token for `backend: vault` (OpenBao or Vault; name configurable via `vault.token_env`) |
|
||||
|
||||
---
|
||||
|
||||
@@ -144,4 +239,4 @@ tunnels:
|
||||
|
||||
`ops-bridge` runs `cert_command` before each SSH launch, captures stdout as the cert,
|
||||
and passes it alongside the private key via `ssh -i <key> -i <cert>`.
|
||||
See `wiki/CertCommandInterface.md` for the full contract.
|
||||
See `wiki/CertCommandInterface.md` for the full contract.
|
||||
Reference in New Issue
Block a user