Upgrade Guide

This guide covers upgrading Arbitex across all three deployment topologies. The upgrade process varies by topology:

Topology	Upgrade method	Downtime
SaaS	Automatic, zero-action	Zero
Hybrid Outpost	Pull new container image, rolling restart	Seconds (rolling) or brief (single instance)
Air-Gap	Manual tarball transfer, image load, restart	Brief

---

SaaS

No action required. SaaS upgrades are automatic and zero-downtime.

Arbitex deploys platform updates as rolling releases to the managed gateway infrastructure. Your applications experience no interruption. Policy configuration, API keys, audit log, and all other data are preserved across upgrades.

What you get notified about

Breaking API changes (new required fields, removed endpoints, behavior changes) are announced in the Arbitex changelog with at least 30 days notice before the change takes effect. Non-breaking additions (new endpoints, new optional fields) are deployed without notice.

No action needed for

• Security patches — applied immediately to the managed fleet
• DLP model updates — applied automatically; detection capabilities improve without configuration changes
• Policy engine improvements — backward-compatible; existing policies continue to evaluate identically

---

Hybrid Outpost

The Hybrid Outpost upgrade process is a three-step procedure: pull the new container image, restart the container, and verify. The policy bundle and certificate continue to function across restarts — no resync or re-registration is required.

Before you upgrade

1. Check the release notes for the target version — look for any required environment variable changes or database migrations
2. Verify your cert expiry — GET /health returns cert_expires_at; ensure it is more than 7 days away before upgrading (cert renewal runs automatically during normal operation)
3. Note the current version for rollback reference

curl http://localhost:8300/health | jq '.version'
# → "0.33.0"

Upgrade procedure

Step 1: Pull the new image

# Pull the new image tag
docker pull ghcr.io/arbitex/outpost:0.34.0

If you are using Docker Compose with a pinned tag in .env:

# Edit .env to update the version
OUTPOST_IMAGE_TAG=0.34.0

Step 2: Restart with the new image

Docker Compose:

docker compose pull outpost
docker compose up -d outpost

Docker Compose pulls the updated image and recreates the container in-place. The policy_cache and audit_buffer volumes are preserved — cached policy bundle and buffered audit events are not lost.

Kubernetes (Helm):

helm upgrade arbitex-outpost charts/arbitex-outpost/ \
  --set image.tag=0.34.0 \
  --wait

The Helm chart uses a RollingUpdate deployment strategy by default. With two or more replicas, there is no downtime.

Step 3: Verify

# Confirm the new version is running
curl http://localhost:8300/health | jq '{version, status, policy_bundle}'

{
  "version": "0.34.0",
  "status": "ok",
  "policy_bundle": "loaded"
}

Send a test request to confirm end-to-end function:

curl http://localhost:8300/v1/chat/completions \
  -H "Authorization: Bearer $ARBITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "anthropic/claude-haiku-3-5", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 4}'

Policy bundle auto-sync

After restart, the Outpost immediately syncs the latest policy bundle from Arbitex Cloud. The sync completes within 60 seconds (the configured POLICY_SYNC_INTERVAL). The local cached bundle from before the restart is used until the sync completes — enforcement is never interrupted.

Certificate rotation during upgrade

Certificate rotation continues unaffected across container restarts. The mTLS cert files are on a persistent volume (/app/certs/). The renewed cert, if one was written before the restart, is picked up automatically on startup.

Rollback procedure

If the new version does not pass verification, roll back to the previous image:

Docker Compose:

# Restore the previous version tag in .env
OUTPOST_IMAGE_TAG=0.33.0

docker compose up -d outpost

Kubernetes:

helm rollback arbitex-outpost

After rollback, verify:

curl http://localhost:8300/health | jq '.version'
# → "0.33.0"

Policy bundles are version-independent — the cached bundle from before the upgrade is still present on the volume and will be used immediately after rollback.

---

Air-Gap {#air-gap}

Air-gap upgrades require a manual media transfer of the container image tarball and a controlled restart. No internet connection is used at any point.

Before you upgrade

1. Obtain the signed upgrade tarball from your Arbitex account team:

   • arbitex-platform-x.y.z.tar.gz — container image archive
   • arbitex-platform-x.y.z.tar.gz.sig — Ed25519 signature file
   • arbitex-release-key.pub — Arbitex release signing key

2. Verify the tarball signature before loading it:

# Verify the release signature (requires openssl or minisign)
openssl pkey -pubin -in arbitex-release-key.pub -noout 2>/dev/null && \
openssl dgst -sha256 -verify arbitex-release-key.pub \
  -signature arbitex-platform-x.y.z.tar.gz.sig \
  arbitex-platform-x.y.z.tar.gz

Expected output: Verified OK

Do not proceed if signature verification fails.

3. Transfer the verified tarball to your air-gapped host via your approved secure media transfer process.

Upgrade procedure

Step 1: Load the image

docker load < arbitex-platform-x.y.z.tar.gz

Expected output:

Loaded image: ghcr.io/arbitex/platform:x.y.z

Step 2: Update the image reference

Edit your .env or docker-compose.yml to point to the new image tag:

.env

PLATFORM_IMAGE_TAG=x.y.z

Step 3: Apply any database migrations

Check the release notes for the target version. If database migrations are required:

docker compose run --rm backend alembic upgrade head

Run migrations before restarting the main service. Migrations are designed to be backward-compatible with the previous release.

Step 4: Restart the service

docker compose up -d backend frontend

Step 5: Verify

curl http://localhost:8100/health

{
  "status": "ok",
  "version": "x.y.z"
}

Confirm the audit log, policy packs, and user configuration are intact:

# Check a recent audit entry
curl "http://localhost:8100/api/admin/audit-logs/?limit=1" \
  -H "Authorization: Bearer $ARBITEX_ADMIN_KEY" | jq '.total'

GeoIP database update (if included)

Air-gap upgrade packages optionally include an updated MaxMind GeoLite2-City MMDB. If provided:

# Replace the MMDB file (no restart required — loaded on next event)
cp GeoLite2-City.mmdb /etc/arbitex/geoip/GeoLite2-City.mmdb

DLP model update (if included)

If the upgrade includes updated ONNX model files for Tier 2 (NER) or Tier 3 (DeBERTa):

# Place models in the configured model directory
cp ner-model.onnx /etc/arbitex/models/ner/
cp deberta-model.onnx /etc/arbitex/models/deberta/

# Reload models without full restart via admin API
curl -X POST http://localhost:8100/api/admin/dlp/reload \
  -H "Authorization: Bearer $ARBITEX_ADMIN_KEY"

Rollback procedure

Before loading the new image, back up the current image:

docker save ghcr.io/arbitex/platform:current-version -o arbitex-platform-backup.tar

To roll back after a failed upgrade:

# Load the backup image
docker load < arbitex-platform-backup.tar

# Update .env to point to the previous version tag
PLATFORM_IMAGE_TAG=previous-version

# Restore the database from backup if migrations were applied
# (restore from pre-upgrade backup taken per your DR runbook)

# Restart
docker compose up -d backend frontend

Database migrations

If you applied database migrations before discovering a problem, rolling back the container image is not sufficient. You must also restore the database from a pre-upgrade backup. Always take a database backup before applying migrations in air-gap environments.

---

Version compatibility

Outpost version	Platform API version	Compatible
0.34.x	v1	Yes
0.33.x	v1	Yes
0.32.x	v1	Yes
< 0.30.x	v1	Check release notes

The Outpost and Platform API maintain backward compatibility within the same major version. Upgrade the Outpost before the Platform when both require updating.

---

Upgrade checklist

Use this checklist for any Hybrid Outpost or Air-Gap upgrade:

• Read the release notes for the target version
• Verify cert expiry is > 7 days (GET /health → cert_expires_at)
• Take a database backup (Air-Gap)
• Pull or load the new image
• Apply database migrations if required
• Restart the container(s)
• Verify health endpoint returns "status": "ok" and the new version number
• Send a test request through the proxy endpoint
• Check audit log contains the test request entry
• Confirm policy bundle is loaded ("policy_bundle": "loaded" in health response)

---

See also

• Deployment Topologies — choose the right topology for your requirements
• Outpost Deployment Guide — full initial deployment instructions
• Outpost Resilience Guide — circuit breaker, graceful degradation, and audit buffering
• Outpost Health Monitoring — heartbeat, status thresholds, and alerts