Upgrade Gateway

Read the release notes, confirm the archive matches the host architecture, back up the files listed in recovery, and record version, /readyz, /v1/ha, and entitlement status. Validate the new configuration before stopping the old service.

Because the archive carries a default gateway.yaml, preserve the site’s configuration before copying a new release over the installation root:

sudo systemctl stop keystone-gateway
sudo cp /opt/particle_horizon/local_config/keystone-gateway/gateway.yaml \
  /opt/particle_horizon/local_config/keystone-gateway/gateway.yaml.bak
sudo cp -a "${INSTALL_TMP}/particle_horizon/." /opt/particle_horizon/

The state key and signed license are not carried in the archive, so they survive the copy; only gateway.yaml is replaced. Restore the site’s configuration, or merge it into the newly supplied file where a release introduces configuration changes:

sudo cp /opt/particle_horizon/local_config/keystone-gateway/gateway.yaml.bak \
  /opt/particle_horizon/local_config/keystone-gateway/gateway.yaml

Then run config validate, start the service, and verify /readyz, license metadata, and a non-destructive status query. To roll back, stop the service, repoint the stable path at the previous SOFTWARE directory, and restore a compatible configuration/state backup. Do not assume state formats are backward compatible; follow release notes.

For HA, V1 documents no guaranteed rolling or zero-downtime upgrade. Plan a maintenance window, preserve both nodes’ matching state key and license, and upgrade one node at a time only after confirming release compatibility. A node may become degraded-active during peer maintenance; observe /v1/ha, avoid deliberate partitioning, and validate convergence before upgrading the other node.