Upgrades¶

Ampora releases follow a MAJOR.MINOR.PATCH versioning scheme. The scheme is a contract about schema and API compatibility.

We never break the OpAMP wire format in a minor release — agents should be able to talk to one minor older or one minor newer of Ampora.

Reading release notes¶

Every release ships with a release notes entry covering:

• new features and the ADRs they trace to,
• bug fixes,
• deprecations (warnings emitted; removal scheduled for a future major),
• removals (always called out at top, never silent),
• migration guidance for breaking changes,
• security advisories.

Production upgrade procedure¶

For a typical minor or patch:

1. Read the release notes. Skim for the words "breaking", "remove", "rename", "policy".
2. Take a Postgres snapshot. Pre-upgrade backup is the difference between "we rolled back" and "we restored at 4 a.m.".
3. Pin by digest. Update kustomize edit set image with the new tag's image digest, not just the tag.
4. Apply.

   kubectl apply -k deploy/kustomize/overlays/acme-prod
   kubectl -n ampora rollout status deploy/ampora-web
   

5. Watch the metrics. ampora_opamp_active_sessions, ampora_dispatch_no_session_total, up{job="ampora-web"}. Anomalies usually surface inside 5 minutes.
6. Spot-check the UI. Log in. The Dashboard, Fleet, Configurations should render. The version in the footer should match the new tag.

The rolling-update strategy is RollingUpdate with maxSurge=1, maxUnavailable=0 — you keep all replicas available during the rollout. WebSockets get drained one pod at a time.

Migrations¶

EF migrations apply on startup if AMPORA_AUTO_MIGRATE=1. Migrations are:

• forward-only — Ampora does not ship Down methods,
• transactional — a failed migration leaves the schema at the previous successful one,
• online-first — they avoid table rewrites where possible. When a rewrite is unavoidable (e.g. promoting TEXT to JSONB), the release notes warn and give an estimated runtime.

For tightly controlled clusters, run migrations as a Job ahead of the deployment rollout. See Database & migrations.

Downgrade policy¶

Downgrade is supported across PATCH boundaries only. Across a MINOR boundary the schema may have been migrated forward in a way the older binary cannot read.

If you must downgrade across a MINOR:

1. Restore Postgres from the pre-upgrade snapshot.
2. Re-deploy the previous Ampora version.
3. Re-attach the master key from the secret manager.

You will lose any data written between the upgrade and the downgrade. Audit logs cannot be merged across that gap because they were written under different schemas.

Rolling back inside the same version¶

This is not a downgrade — it is just rolling the deployment back to the previously-running image:

kubectl -n ampora rollout undo deploy/ampora-web

Always safe within a PATCH. Within a MINOR it depends on whether the in-flight version applied any schema changes; if it did, you are in the "downgrade across minor" case above.

Deprecations¶

Deprecated features:

1. Emit a structured warning log on every use.
2. Surface a banner in the Settings UI for the deprecated feature.
3. Remain functional for at least one full MINOR cycle before removal.

This gives you at least one release where you can plan to migrate. The warning log line is searchable in your log shipper: category=Ampora.* level=Warning message=*deprecated*.

Security advisories¶

Security fixes ship as soon as possible — usually as a PATCH on the current minor and the previous minor. Subscribe to GitLab security advisories on the project; the disclosure window follows the project's SECURITY.md.