The audit log

What is recorded

Every create, update, delete, restart, rollback, promotion, invitation and token change is recorded automatically. So is every denied or failed attempt, every throttled login, and every login. Each record holds:

Field	Example
actor	the user, and whether they came through a session or an API token
action	the OpenAPI operation id, e.g. createApp, promoteApp, revokeToken; some changes add a more specific record, e.g. webhook.created; sign-ins are login
target	shop/production/api
outcome	success, denied, failure, throttled or error, with the HTTP status
client	the client IP and the request id
when	a timestamp

denied means the request was refused with 401 or 403; a wrong password is recorded as failure. Request bodies are never recorded, and therefore neither are secret values, passwords or tokens.

Reading it

• Console: open Audit in the sidebar. The Audit log shows when, who, the action, the target, the outcome and the IP; Load older events pages back. Owners and admins can read it. The Recent deployments card on Home is built from it too.
• API: newest first, paged with a cursor:

curl -fsS "$KUBEN_URL/api/v1/audit?limit=100" -H "Authorization: Bearer $KUBEN_TOKEN"
# older pages:
curl -fsS "$KUBEN_URL/api/v1/audit?limit=100&before=<next_before from the previous page>" \
  -H "Authorization: Bearer $KUBEN_TOKEN"

The API also returns each record’s request id, so you can correlate it with Kuben’s logs (JSON by default) and with your gateway’s access log.

Properties

• Append-only through the API. There is no endpoint that edits or deletes audit records.
• Written before the answer. Kuben writes the record while it handles the request, before it answers. If the write fails, the request still goes through; Kuben logs the failure and counts it in the kuben_audit_write_errors_total metric so you can alert on it.
• Shared by all replicas. Every replica writes to the same log in PostgreSQL.

Retention

Kuben does not delete audit records. The log lives in PostgreSQL; size it and back it up accordingly (see Backup and restore). Signed anchoring of the log is on the roadmap.

Client addresses behind a proxy

By default Kuben records the address of the TCP peer. Behind a proxy that appends the client address, set KUBEN_SECURITY__TRUST_FORWARDED_FOR=true (the Helm chart does, because the Gateway sits in front). Kuben then uses the last X-Forwarded-For hop; earlier hops are client-controlled and ignored. To believe the header only from your proxy, also set KUBEN_SECURITY__TRUSTED_PROXIES to its addresses (CIDRs). See Sign-in and throttling.