Upgrading from v1.x

Before you upgrade to v2.0.0

These are the breaking changes from the v2.0.0 release notes. Complete them first.

Helm with obleth.existingSecret: add the new keys to the Secret first. The chart now reads the Redis URL from the Secret, because it carries the Redis password, instead of setting it in the pod environment. With existingSecret the chart does not render that Secret. If a key is missing, the new pods cannot start (the gateway has no Redis URL, and the bundled Redis and Postgres have no password) and the rollout stalls, with the old pods still serving. Before upgrading:

• External Redis (redis.enabled: false): copy the URL the running pods use into the Secret. It must include the password if your Redis requires one.

  kubectl patch secret <existing-secret> -n <namespace> --type merge -p "{\"stringData\":{\"OBLETH_REDIS_URL\":\"$(kubectl get deploy <release>-obleth -n <namespace> -o jsonpath='{.spec.template.spec.containers[0].env[?(@.name=="OBLETH_REDIS_URL")].value}')\"}}"
  

• Bundled Redis (redis.enabled: true): the upgraded Redis requires a password, so the URL the running pods use (which has none) will not authenticate. Generate a password and add it together with a URL that carries it:

  PW=$(openssl rand -hex 16)
  kubectl patch secret <existing-secret> -n <namespace> --type merge -p "{\"stringData\":{\"REDIS_PASSWORD\":\"$PW\",\"OBLETH_REDIS_URL\":\"redis://:$PW@<release>-redis:6379\"}}"
  

• Bundled Postgres (postgres.enabled: true): add POSTGRES_PASSWORD, set to the password the existing database already uses (the one in the gateway's database URL). Postgres reads it only when it initializes an empty volume, so an existing database keeps its password either way.

The full key list for the gateway Secret:

Redis now requires a password. The Helm chart takes redis.password (required, URL-safe characters only; hex is simplest) and the compose stacks take REDIS_PASSWORD. The chart's bundled Redis gets a 512Mi limit with maxmemory 400mb and volatile-lru; under that policy only entries with a TTL are evicted, and once none are left a full Redis rejects writes with an out-of-memory error.

• Helm without existingSecret: add --set redis.password=$(openssl rand -hex 16) once to the Helm upgrade.
• Compose: echo "REDIS_PASSWORD=$(openssl rand -hex 16)" >> deploy/docker/.env before recreating. The standalone datastore stack reads it from datastores.env.
• redis-cli now needs -a "$REDIS_PASSWORD" --no-auth-warning.

Upstream secrets are no longer returned by the Management API. Model, endpoint, and MCP server responses carry api_key_set / auth_header_set booleans instead of the secret itself. Writes are unchanged: omit the field to keep the stored value, or send an empty string to clear it. Clients that read api_key or auth_header from a response must be updated.

POST /v1/messages is translated, not forwarded. The gateway now serves the Anthropic Messages API itself. A deployment that relied on it being passed through to the upstream unchanged must route those requests another way.

Guardrails policies refuse endpoints they cannot enforce. For a tenant whose policy blocks or redacts, POST /v1/completions, audio transcription and translation, and unrecognized paths now return 400; use /v1/chat/completions, /v1/responses, or /v1/messages. Embedding, rerank, and moderation inputs are now scanned, so indexing a document that trips a scanner returns 400.

OBLETH_GLOBAL_MAX_IN_FLIGHT is a ceiling across per-model pools. A deployment that pinned it (the shipped compose file used 64) should raise it above the sum of its models' pool sizes, or the ceiling binds before the pools do.

With more than one gateway replica, fairshare limits are now cluster-wide. Pool sizes, the global ceiling, and per-tenant and per-key max in flight hold across every replica together instead of each replica enforcing all of them. A deployment that sized those numbers per replica (N replicas × the configured value reaching the upstream, as the chart used to advise) will see its aggregate drop to the configured value: multiply its settings by the replica count before upgrading, or set both OBLETH_FAIRSHARE_SHARED_SLOTS=false and OBLETH_FAIRSHARE_REPLICA_AWARE=false (Helm obleth.fairshareSharedSlots and obleth.fairshareReplicaAware) to keep the old behaviour. Single-replica deployments are unaffected. See Scaling.

Response cache and compression store are scoped per tenant. Existing entries are not reused after the upgrade (one miss per request until repopulated). A cache TTL of 0 now means "do not cache" rather than "never expire"; entries written with TTL 0 by earlier versions remain until flushed. To remove only those, run this where REDIS_PASSWORD is set:

redis-cli -a "$REDIS_PASSWORD" --no-auth-warning --scan --pattern 'obleth:cache:*' |
while read -r key; do
  if [ "$(redis-cli -a "$REDIS_PASSWORD" --no-auth-warning ttl "$key")" = "-1" ]; then
    redis-cli -a "$REDIS_PASSWORD" --no-auth-warning del "$key" > /dev/null
  fi
done

Dashboard email sign-up is closed. The break-glass admin is seeded from DASHBOARD_ADMIN_EMAIL / DASHBOARD_PASSWORD.

Other changes in v2.0.0

v2.0.0 also changes behaviour that needs no action, such as 503 instead of 401 when Redis fails during a key lookup, and GET /v1/models listing the gateway's registry. Read the release notes before upgrading.

Rolling back across v2.0.0 returns Redis to running without a password; migrations are not reverted.