How to rotate API keys

This guide shows how to rotate bearer API keys used by clients of the Ingress Info Service.

What you’ll do

  • Create a new key and add it to the Kubernetes Secret
  • Roll out the change without downtime
  • Verify the new key works and remove the old one

Before you start

  • Access to the cluster using your Kubernetes command‑line tooling and permissions for the target namespace
  • The service is deployed and reading keys from Secret ingress-info-keys

Secret format

  • Secret name: ingress-info-keys in the service namespace
  • Type: Opaque
  • Data: one or more entries. Supported forms:
    • data.keys: newline- or comma-separated keys
    • or multiple keys as separate data entries; all values are treated as keys

Example manifest

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

apiVersion: v1
kind: Secret
metadata:
  name: ingress-info-keys
type: Opaque
data:
  # base64-encoded values
  keys: |
    c2VjcmV0LWtleS0xCg==
    c2VjcmV0LWtleS0y

Step 1 — Add the new key

  1. Generate a key (example):
    • 32+ random characters. Example: ingress-info-$(openssl rand -hex 16)
  2. Append it to the Secret (preferred: edit and add to data.keys as a new line).

Step 2 — Apply and allow refresh

  • Apply the Secret change using your cluster tooling
  • The service refreshes keys periodically (on restart and on background refresh). If you need immediate pickup, restart the Deployment using your cluster tooling

Local override (for testing)

  • You can run the service locally with a file of keys using the environment variable INGRESS_INFO_KEYS_FILE pointing to a text file with one key per line.

Step 3 — Verify the new key

  • Call the API with the new key:
    • Set header: Authorization: Bearer NEW_KEY
    • Expect 200 OK for /v1/ingresses when authenticated.

Step 4 — Remove the old key

  • After clients switch, remove the old key from the Secret
  • Apply the change and wait for refresh or restart the Deployment

Troubleshooting

  • 401 Unauthorized: ensure the Authorization header uses Bearer and the exact key value
  • Secret not found: confirm namespace and name ingress-info-keys
  • Local runs: verify INGRESS_INFO_KEYS_FILE path is readable by the process

References

  • Code: internal/auth/keys.go (Secret and file parsing)
  • Spec: DOC-002, OPS-002, SEC-002, AC-005