# Upgrade Gateway

Read the release notes, confirm the archive matches the host architecture, back up the files listed in [recovery](https://portal.cjcit.io/knowledge-base/keystone_gateway/0.2/operations/backup-and-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.