Skip to main content

Ingestion Keys

Every Saviour agent authenticates to the backend using an ingestion key. This page covers how to create keys, how to pass them to the chart, and how to rotate them.

Creating an ingestion key​

  1. Open app.saviourops.com
  2. Go to Settings → Ingestion Keys
  3. Click New Ingestion Key
  4. Give it a descriptive name (e.g. prod-east-1-cluster)
  5. Copy the key — it is shown only once
Name keys by cluster

One key per cluster makes rotation and revocation simple. Use the cluster name as the key name so you can identify which key belongs where.

Passing the key to the Helm chart​

You have two options. Option A is recommended for production.

Option A — Pre-created Secret (recommended)​

Create the Kubernetes Secret yourself before running helm install. The chart references it by name.

kubectl create namespace saviour

kubectl create secret generic saviour-secret \
  --from-literal=api-key=sav_YOUR_KEY_HERE \
  --namespace saviour

Then install the chart:

helm upgrade --install saviour \
  oci://ghcr.io/saviourops-labs/charts/saviour \
  --set global.existingSecret=saviour-secret \
  --set global.server.url=https://api.saviourops.com \
  --set global.cluster.name=prod-east-1 \
  --namespace saviour

This approach keeps the ingestion key out of Helm values and Helm history.

Option B — Inline key (development / quick start)​

Pass the key directly as a Helm value. The chart creates the Secret automatically.

helm upgrade --install saviour \
  oci://ghcr.io/saviourops-labs/charts/saviour \
  --set global.apiKey=sav_YOUR_KEY_HERE \
  --set global.server.url=https://api.saviourops.com \
  --set global.cluster.name=my-cluster \
  --namespace saviour
warning

global.apiKey stores the key in Helm release history (Kubernetes Secrets in the saviour namespace). Use global.existingSecret in production.

Using an external secret manager​

If you manage secrets with Vault, External Secrets Operator, or Sealed Secrets, create a standard Kubernetes Secret with the shape below and point global.existingSecret at it:

apiVersion: v1
kind: Secret
metadata:
  name: saviour-secret
  namespace: saviour
type: Opaque
data:
  api-key: <base64-encoded key>   # key name must match global.existingSecretKey (default: "api-key")

The global.existingSecretKey value (default: api-key) is the key inside the Secret that holds the token — change it if your secret manager uses a different key name.

Rotating an ingestion key​

Rotation is a two-step process with zero downtime.

Step 1 — Create a new key in the Saviour UI (Settings → Ingestion Keys → New Ingestion Key).

Step 2 — Update the Kubernetes Secret:

kubectl create secret generic saviour-secret \
  --from-literal=api-key=sav_NEW_KEY_HERE \
  --namespace saviour \
  --dry-run=client -o yaml | kubectl apply -f -

Step 3 — Restart the agents to pick up the new key:

kubectl rollout restart deploy/saviour-centurion -n saviour
kubectl rollout restart ds/saviour-sentinel -n saviour

Step 4 — Verify agents reconnect (check UI → cluster still shows data), then revoke the old key in the Saviour UI.

Verifying a key works​

# Check the key stored in the Secret
kubectl get secret saviour-secret -n saviour \
  -o jsonpath='{.data.api-key}' | base64 -d
# Should output: sav_xxxxxxxxxxxxxxxxx

# Check Centurion is authenticated
kubectl logs -n saviour deploy/saviour-centurion | grep -E "auth|connect|error" | tail -5

Key format​

PrefixUsed for
sav_Kubernetes cluster agents (Centurion + Sentinel on Kubernetes)
sav_host_Sentinel installed as a Linux systemd service (VM install)

The prefix is informational — the backend validates the key regardless of prefix.

Multi-cluster setup​

Use a separate key per cluster. This lets you:

  • Revoke a single cluster's access without affecting others
  • See per-cluster key usage in the Saviour UI
  • Rotate one cluster at a time during incidents

Name keys clearly: prod-east-1, staging-us, dev-local — they appear in the Saviour UI next to the cluster name.