Shaun Campbell
4256b7a50e
All checks were successful
Build and Push Image / docker-build-and-push (push) Successful in 6m2s
58 lines
3.5 KiB
Markdown
58 lines
3.5 KiB
Markdown
# TreatVault
|
|
|
|
TreatVault manages Barkstack's namespaced secrets. It keeps an age-encrypted source-of-truth file on disk, watches it for changes, and reconciles its contents with Docker Swarm secrets.
|
|
|
|
## Model
|
|
|
|
- The Barkfile `treatvault` block names the encrypted file (a bind-mounted path) and the bootstrap Docker secret holding the age X25519 identity (`barkstack_<reference>`).
|
|
- The encrypted file is safe to commit and back up: contents are age-encrypted with the X25519 identity; only the identity secret itself stays outside source control.
|
|
- Each logical secret is stored as a versioned record. Sync creates one immutable Docker secret per record revision, named `barkstack_tv_<vaultId>_<revision>`, labeled with the logical name and vault ID.
|
|
- Consumers mount secrets at the stable target path `barkstack_<name>`; rotations swap the mounted source and update the service, leaving a rollback path.
|
|
- Obsolete Barkstack-managed secret objects are deleted; objects still mounted by a managed service are reported in the sync status and refused for deletion via the API until their consumers are updated.
|
|
|
|
## Service image
|
|
|
|
TreatVault is a service, not a user CLI. `registry.campbellwireless.net/barkstack/treatvault:latest` runs its HTTP API on port `9090` inside the Barkstack overlay network. It accepts only service flags:
|
|
|
|
```sh
|
|
treatvault --file /var/lib/treatvault/secrets.age \
|
|
--identity /run/secrets/barkstack_treatvault_identity \
|
|
--listen :9090
|
|
```
|
|
|
|
On startup TreatVault creates the encrypted vault file when it is absent, using the mounted age identity. It then loads the file, reconciles Docker Swarm secrets, and exposes the API. The identity remains a Docker secret; TreatVault never exposes it through the API or UI.
|
|
|
|
## HTTP API
|
|
|
|
- `GET /barkstack/ui/manifest.json` - Barkstack plugin manifest (id `treatvault`, mount `/treatvault`).
|
|
- `GET /barkstack/api/secrets` - secret names, sync state, consumers; never returns values.
|
|
- `PUT /barkstack/api/secrets/{name}` - create or rotate (`{"value":"..."}`); triggers an immediate sync.
|
|
- `DELETE /barkstack/api/secrets/{name}` - delete; `409 Conflict` while a managed service still mounts the secret.
|
|
- `GET /healthz` - ready/degraded sync state.
|
|
|
|
## Barkstack deployment
|
|
|
|
Configure TreatVault in the Barkfile and run `barkstack init` on a Swarm manager:
|
|
|
|
```text
|
|
treatvault {
|
|
file ./secrets.age
|
|
identity_secret treatvault_identity
|
|
}
|
|
```
|
|
|
|
`barkstack init` creates `barkstack_treatvault_identity` if absent, provisions the manager-constrained `barkstack-treatvault` service, and bind-mounts the encrypted file read-write at its configured host path. The service receives only that file, the Docker socket, and its Docker-secret identity; it has no published ports. The console reaches it over the overlay network at `:9090`.
|
|
|
|
The encrypted file is safe to commit and back up. Keep its mounted Docker-secret identity outside source control. Use the TreatVault page in the Barkstack Console to create, rotate, and delete secret values; values are write-only and never returned.
|
|
|
|
Services that consume vault secrets carry the `io.barkstack.treatvault.secrets=true` label plus an `io.barkstack.treatvault.names` label listing the logical names they need; `barkstack init` labels the PawSQL service automatically. Each sync mounts the current revision at the stable `/run/secrets/barkstack_<name>` target, so consumers read the same path across rotations.
|
|
|
|
## Build
|
|
|
|
```sh
|
|
cd ui && bun install && bun run build && cd ..
|
|
go build -o treatvault ./cmd/treatvault
|
|
docker build -t treatvault .
|
|
```
|
|
|