ka2a · documentation

ka2a operator documentation

Developer preview. Not yet production ready. This page is rendered from docs/README.md of the ka2a repository at revision 96fb45e5e5f6693e779837998c3aa9581d6a37f2. It describes the behavior of that revision.

Contents

These documents are for operators who deploy and run ka2a. They describe the behavior of this revision. The acceptance ledger shows which behavior has automated evidence.

Document	Use it to
Production deployment	Plan the topology, the broker security, the keys, the catalog, the state directories, the backups and the retained-state budget. Set up health checks, the service unit, data protection and the go-live checklist.
Runbooks	Resolve held work, a quarantine after a restore, a broker outage, refused broker connections, a refused or expiring client certificate, a rotated SASL password, a catalog on disk that differs from the running digest, a missing broker ACL, a signing key that expires soon, a failed catalog check, storage pressure, `identity_conflict`, unknown outcomes and exit code 6, a `broker_ahead` quarantine, a lost or damaged state directory, a move to a new host, a full disk, clock drift and consumer restarts.
Configuration reference	Look up each command-line flag and each field of `ka2a.Config`. A test keeps this reference complete.
Metrics reference	Look up each metric family of `ka2a run --metrics-listen` with its labels, its meaning and what to alert on. Start from the example alert rules in examples/alerts.yml. A test keeps this reference complete.
Error reference	Look up each error code, broker failure class and hint, publish, rejection, hold and quarantine reason, and exit code, with the retry advice and the action. A test keeps this reference complete.
Output formats	Look up each versioned JSON document (`ka2a.*/1`) and its compatibility rule. A test keeps this reference complete.
Threat model	Understand the assets, the trust boundaries, the attackers, the mitigations and the residual risks.
Versioning	Understand the version numbers, the API stability of the preview, the deprecation policy and the supported Go versions.
Releasing	Follow the manual release procedure of the owner.
Upgrade notes	Upgrade a store from schema version 1 to 2, and roll back with a backup.
Release artifacts	Build the release binaries, SBOMs, checksums and the release evidence summary, and check that two builds are identical. Scan the Go code for known vulnerabilities before you publish (`make vulncheck`). Publishing is a manual step of the owner.

The documents use the stable exit codes of the ka2a command:

Code	Meaning
0	Success.
1	The command failed. The message names the error code.
2	Usage error: unknown command, flag or argument.
3	The checks found problems.
4	The command is not available in this build.
5	A running node owns the state directory.
6	A request is admitted, but its outcome is not known yet.