Runbooks for Alerts and Error Codes
Docs version v1 (main)Nauthera is pre-1.0, in a design-partner programUpdated
Every alert nauthera-server's Helm chart raises, and every error code the server or its operator answers with, has a runbook. Each one says:
| Section | What it answers |
|---|---|
| Meaning | What happened, and every cause that leads to it |
| Impact | Who is affected and how badly: users signing in, relying parties, administrators, auditors |
| Diagnosis | Steps to find which cause it is, with the commands, queries, log keys and audit records to read |
| Mitigation | What to do about each cause, for each audience |
| Escalation | When it is not expected, who to involve, and what to attach to an issue |
| Catalog | Reached from |
|---|---|
| Alerts | The runbook_url annotation of every alert in the chart's PrometheusRule, the operator's group included |
| Problem codes | The type of an RFC 9457 problem response, https: |
| OAuth errors | The error_uri of an OAuth error response or authorization error redirect |
| Operator failure reasons | The reason on a resource's Ready condition, as kubectl describe shows it |
Where the links point
The links that alerts and responses carry are stable and do not name a docs version:
| URL | Redirects to |
|---|---|
https: | / |
https: | / |
A problem's type is its identifier (RFC 9457 §3.1.1) as well as a link, so branch on
code or type, never on the text of the page. A client should not fetch the URL on its
own; it is for the developer reading the response.
To link alerts to runbooks of your own instead, set the chart's
metrics.: each alert then links to <runbookUrl>/.
An empty value leaves the annotation out. See Observability.
Offline
The server binary carries the runbooks of its own version:
nauthera-server runbook # list every runbook
nauthera-server runbook alerts NautheraServerDown # print one
nauthera-server runbook problems invalid_credentials
nauthera-server runbook oauth invalid_grantThe operator's failure reasons are not in the server binary; read them here.
Where they come from
The runbooks are declared in nauthera-server's source, beside the code that raises what
they describe (internal/runbook and operator/), and this site renders
them at build time. A change that adds or changes an alert, a code or a reason changes its
runbook in the same pull request, and the server's tests fail on one without a runbook.