Upgrade and rollback

Upgrade using immutable images and a chart/configuration set from the same release. Record the old digest, configuration and recoverable state before changing the workload. Image rollback and database restore are separate actions.

Before an upgrade

Read the target release's compatibility notes and compare enabled product features, datastore schema, endpoint protocols, authentication and licensing. Capture the running image digest and Helm history. Keep values and rendered manifests private; they can contain deployment addresses and configuration.

umask 077
mkdir -p eden-upgrade
helm -n eden history eden >eden-upgrade/history.txt
helm -n eden get values eden >eden-upgrade/previous-values.yaml
kubectl -n eden get pods -l app.kubernetes.io/instance=eden \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.containerStatuses[*].imageID}{"\n"}{end}' \
  >eden-upgrade/images.txt

Take and verify a recoverable backup. Test the candidate against a restored, isolated state copy and representative client traffic. Verify schema changes and determine whether the previous binary can read state written by the candidate. Eden does not provide a universal downgrade or mixed version compatibility guarantee.

Finish active migrations before routine upgrades. If that is impossible, deliberately pause and inspect their durable operation state, preserve source authority, and plan for restart reconciliation. A process restart can fence an interrupted migration against in-place continuation. Draining HTTP requests alone does not prove that long-lived Redis sessions or external writes stopped.

Keep the existing license and identities

Replacing an image in the same deployment does not require detaching its license. Retain the same persistent volume, EDEN_DB_ENCRYPTION_KEY, JWT secret, node/gateway UUID, service deployment/instance UUIDs, EDEN_CLUSTER_UID and runtime license configuration. The license must remain active and permit the replacement product. Moving to another deployment/host is a separate licensing operation; a CLI download session is not the runtime credential.

For offline deployments, also preserve the signed lease, trust inputs and current anti-rollback watermark. Do not restore an older watermark during an image rollback. Obtain a replacement runtime credential only when rotating that credential deliberately, not as a routine upgrade step.

Replace a Docker quickstart image

These commands use the names and private files from the CLI quickstart. Existing deployments must retain their own actual mounts, ports, limits and settings.

1. Finish active migrations, fence new traffic and verify a recoverable backup.
2. Use eden image pull --output eden-next-image.tar.gz and

docker load --input eden-next-image.tar.gz. Set EDEN_NEXT_IMAGE to the exact image reference printed by the verified load. Keep the old digest for a compatibility-checked rollback.

1. From the directory holding the original eden.runtime.env and

eden.license.env, replace only the container:

: "${EDEN_NEXT_IMAGE:?set the exact reference printed by docker load}"
docker stop --time 180 eden
docker rm eden
docker run -d --name eden --restart unless-stopped \
  --env-file eden.runtime.env --env-file eden.license.env \
  --publish 127.0.0.1:8000:8000 --publish 127.0.0.1:6200:6200 \
  --volume eden-data:/var/lib/eden \
  "$EDEN_NEXT_IMAGE"

Keep the volume; do not use a volume-removing cleanup command. Wait for readiness, then repeat authenticated organization/node/endpoint reads and a fresh disposable backend write/read. Check saved native listeners answer on their original ports and completed migrations still use the target route. Check background logs for database errors. If an operation was interrupted, follow migration recovery; restarting it is not permission to bypass reconciliation.

Apply the Kubernetes candidate

Render the target chart with reviewed values and the new image digest. Compare the result to the current deployment, including volume mounts, Secret names, replica identities, ports, probes and termination grace periods. Do not use --reuse-values to carry undocumented old defaults into a new chart.

For a single embedded instance, stop admission and the previous writer before starting the replacement. Do not allow an overlapping rollout to open the same embedded database. With the names from the installation guide, fence traffic, then run:

kubectl -n eden scale deployment/eden --replicas=0
kubectl -n eden wait --for=delete pod \
  -l app.kubernetes.io/instance=eden --timeout=120s

Keep workload.deploymentStrategy.type: Recreate and workload.deploymentStrategy.rollingUpdate: null in the reviewed single-node values. The chart's default rolling strategy must not introduce a second writer. For HA, retain quorum, required membership and migration participant barriers during replacement. Use one release across the fleet; only use mixed versions when explicitly qualified for that version pair.

With your reviewed eden-upgrade/next-values.yaml containing the new immutable image and all intended settings, run:

helm upgrade eden ./helm/charts/eden --namespace eden \
  -f eden-upgrade/next-values.yaml --wait --timeout 10m
kubectl -n eden get pods,pvc

Helm readiness success is one check. Verify /health, /ready, authentication, authorized endpoint reads and a disposable write/read round trip. In HA, also check cache-sync, consensus-control and NAT relay health. Verify telemetry, audit/outbox drain, error rate, throughput and latency against your pre-upgrade window. Observe a representative workload period before closing the rollback window. Do not use a fixed sleep as evidence of migration completion.

Roll back a failed workload change

Stop new admission and identify whether the candidate changed durable schema, control state or external data. If the previous binary is compatible with the current state, use the recorded successful Helm revision:

helm -n eden history eden
helm -n eden rollback eden <previous-revision> --wait --timeout 10m

These commands restore chart resources; they do not undo database migrations, external writes, credential changes or a committed migration cutover. See Helm rollback.

If state is incompatible, keep traffic fenced and follow the tested database restore procedure. Account for every write since the recovery point before reopening traffic. Preserve current offline-license watermarks and monotonic HA configuration generations; rolling these back is not a recovery mechanism.

After either path, repeat the same application, authorization, HA and export checks used for the candidate. Record the running digest and recovery boundary. Keep the failed candidate's redacted diagnostic evidence for investigation.