Upgrade

Compatibility matrix

From	To	Notes
v0.18.x	v1.0	/api/v1/* paths now return HTTP 410 Gone; clients must move to /api/v2/*. See api-versioning.
v0.19.x	v1.0	Same wire-break as above. The mcp:"v1_unwrap" opt-in v1-unwrap idiom is removed; v2 envelope is now the only response shape.
v1.0.x	v1.0.x+n	Rolling restart only. Patch-only releases never change the wire contract.

Pre-v1.0 → v1.0 cutover

Wire breaks on the /api/v1 surface are the only behavior change. Operators with a v0.18 / v0.19 deployment:

1. Drain Echo (sends SIGTERM; in-flight requests complete; new requests get 503 + Retry-After).
2. Update the Helm release with the v1.0 chart + image:

   helm upgrade ingero-echo ./helm/ingero-echo \
     --namespace ingero \
     --set image.tag=v1.0.0 \
     --reuse-values
   

3. Watch the rollout. PVC + DuckDB store survive the upgrade.
4. Update any external client (Grafana plugin, custom dashboards) to point at /api/v2/* paths.

DuckDB store survival

The Helm chart deploys Echo as a StatefulSet with a PVC volumeClaimTemplate. helm upgrade does not delete or recreate the PVC; the DuckDB file at /var/lib/ingero-echo/echo.db is preserved.

helm uninstall does NOT delete the PVC (per StatefulSet semantics). To delete data, remove the PVC explicitly:

kubectl -n ingero delete pvc data-ingero-echo-0

Document this loudly in your runbook. A helm uninstall && helm install is NOT a clean reset; it reuses the existing PVC.

Rolling restart (patch releases)

helm upgrade ingero-echo ./helm/ingero-echo --namespace ingero \
  --set image.tag=v1.0.x --reuse-values
kubectl -n ingero rollout status statefulset/ingero-echo

Echo handles SIGTERM cleanly (graceful drain; outermost middleware returns 503 + Retry-After: 5 on new requests during shutdown). The plugin's "test connection" health check tolerates one 503 by design.

Bearer rotation across an upgrade

If you rotate the bearer at the same time as the upgrade:

1. Pre-upgrade: write the new token to the Secret (kubectl create secret --dry-run=client | kubectl apply).
2. Send SIGHUP to the running Echo to enter the accept-both grace window (kubectl exec + pkill -HUP).
3. Then helm upgrade.

The grace window (default 5 min, --rotation-grace) lets in-flight clients catch up without 401 storms.

OTLP receiver compatibility

Fleet's OTLP receiver contract is stable from v0.10 onward; v1.0 makes no changes to the OTLP listener or processor pipeline. Agents at v0.10 - v1.0 all interop with Fleet v1.0.

Helm chart upgrade vs. reinstall

The chart bumps from 0.1.x to 1.0.0 in this release. Helm allows in-place upgrade across chart-version changes. PVC + Secret + Service + StatefulSet all survive; only the StatefulSet pod is recreated to pull the new image.

If you previously deployed Echo as a Deployment (no chart was ever shipped in that shape; this is historical caveat only), do NOT helm-upgrade across the kind change. Reinstall against an existing PVC instead.