Archestra

Upgrades

Pin an exact chart version or image tag from GitHub Releases. Tags ending in -rc.N are release candidates.

Upgrade with Helm

  1. Back up PostgreSQL and preserve authentication, credential-encryption, and content-encryption keys.
  2. Read the selected release's migration and compatibility notes.
  3. Test the release against a staging database before production.
  4. Run the Helm installation command with the new version and your current values. Update archestra.imageTag too: an old values file or --reuse-values can keep the old image. Alternatively, use --reset-then-reuse-values to pick up chart defaults.
  5. Confirm the migration Job succeeds, the rollout completes, and a model request appears in Logs → LLM Proxy.

Keep the migration Job enabled unless your pipeline applies migrations separately. A successful /health response only confirms the process is alive; /ready returns HTTP 503 until the API is ready.

Let Active Requests Finish

Keep archestra.terminationGracePeriodSeconds at least 120. Archestra stops accepting new model requests during shutdown and allows active requests up to 60 seconds to finish; longer requests can lose their connection.

For Docker, use docker stop --time 120 or Compose's stop_grace_period: 120s.

Roll Back

Follow the selected release's rollback instructions. Reverting a container image does not reverse database migrations; a rollback can require restoring a compatible database backup.

If you enabled the Logs user-picker summary, disable it before starting an older binary.

Upgrade Older OAuth Clients

The unified OAuth Clients migration requires stopping older replicas before starting the updated application. Mixed versions and rolling back to the older authorization model are unsupported. Back up PostgreSQL first.

Client IDs, secrets, provider keys, gateway assignments, and tokens carry over. After upgrading, review Settings → OAuth Clients for each client's capabilities and permissions.

Component Cost Accounting

To include separately billed advisor and compaction inference in budgets, set ARCHESTRA_LLM_PROXY_USAGE_ACCOUNTING_MODE on both web and worker pods:

  1. Deploy compatible binaries everywhere with the mode off.
  2. Switch to shadow. Compare candidate charges with provider usage and confirm complete usage records and trusted model prices.
  3. Let old pods and their requests finish, then switch to enforce. With a small test budget, confirm a completed charge over the limit blocks the next request with HTTP 402.

Existing budget consumption remains. Advisor and compaction charges can exhaust budgets sooner; requests already in flight can exceed a limit.

Switching back to off or shadow retains settled charges. Older binaries cannot read those charges correctly: restore a compatible version before relying on budget accuracy. Keep accounting storage and receipts during rollback and log cleanup.