# Upgrade a Docker Gateway

An AISIX Enterprise gateway started with `docker run` from the **Docker** tab in **Data planes** is upgraded by replacing its container. Its configuration and usage history remain in the control plane, while the replacement keeps the gateway certificate and intentional container settings.

Upgrade and verify the AISIX Enterprise control plane before following this procedure. If the control plane must pass through an intermediate release, use this procedure to bring legacy gateways to that release before advancing the control plane again. See [Upgrade AISIX Enterprise](https://docs.api7.ai/ai-gateway/on-premises/upgrade.md).

## Before You Begin[​](#before-you-begin "Direct link to Before You Begin")

The commands use the container name `aisix-dp` from the generated installation snippet. Substitute the actual name if it differs.

A single gateway serves no traffic between the end of its drain and the moment the replacement loads its configuration. If several gateways sit behind a load balancer, replace and verify them one at a time.

## Preserve the Current Deployment[​](#preserve-the-current-deployment "Direct link to Preserve the Current Deployment")

Find the original generated `docker run` command or your deployment record. You need its intentional environment overrides, entrypoint and command, mounts, published ports, host mappings, restart and stop settings, and attached networks. The baseline replacement command below does not reproduce a customized container by itself.

If the original command is unavailable, save the complete container inspection before removing the container. The file contains credentials and other sensitive configuration, so restrict its permissions and do not commit or share it:

```
umask 077

docker inspect aisix-dp > aisix-dp-inspect.json
```

Review `.Config.Env`, `.Config.Entrypoint`, `.Config.Cmd`, `.HostConfig`, `.Mounts`, and `.NetworkSettings.Networks` in the protected file. Do not print the complete environment to a terminal or CI log: it includes the managed private key and can contain other credentials. Image-defined defaults also appear in the inspection, so carry forward only the settings your deployment intentionally supplied.

The private key appears only when a certificate is issued. If you did not retain the generated command, read the managed bundle from the running container and hold it in your shell:

```
export AISIX_MANAGED__CP_BASE_URL="$(docker exec aisix-dp printenv AISIX_MANAGED__CP_BASE_URL)"

export AISIX_MANAGED__CP_CERT_PEM="$(docker exec aisix-dp printenv AISIX_MANAGED__CP_CERT_PEM)"

export AISIX_MANAGED__CP_KEY_PEM="$(docker exec aisix-dp printenv AISIX_MANAGED__CP_KEY_PEM)"

export AISIX_MANAGED__CP_CA_PEM="$(docker exec aisix-dp printenv AISIX_MANAGED__CP_CA_PEM)"
```

If the certificate has expired, [issue a new one](https://docs.api7.ai/ai-gateway/cloud/connect-a-gateway.md#issue-a-gateway-certificate) and use its bundle instead.

## Replace the Container[​](#replace-the-container "Direct link to Replace the Container")

Stop and remove the old container. By default the gateway drains for at least 30 seconds, so a Docker stop with its default 10-second timeout ends in `SIGKILL`:

```
docker stop -t 45 aisix-dp

docker rm aisix-dp
```

A request that runs longer than the stop timeout is cut off. To preserve longer streams, raise the timeout as described in [Size the Platform Deadline](https://docs.api7.ai/ai-gateway/deployment/graceful-shutdown.md#size-the-platform-deadline).

Start the replacement from the target image. Add every intentional option recorded from the old container. The `-e` options without a value take the values exported above:

```
export TARGET_VERSION="1.10.0"



docker run -d --name aisix-dp \

  --restart unless-stopped \

  --stop-timeout 45 \

  -e AISIX_CONFIG_PATH=/etc/aisix/config.managed.yaml \

  -e AISIX_MANAGED__CP_BASE_URL \

  -e AISIX_MANAGED__CP_CERT_PEM \

  -e AISIX_MANAGED__CP_KEY_PEM \

  -e AISIX_MANAGED__CP_CA_PEM \

  -p 3000:3000 \

  "docker.io/api7/aisix:${TARGET_VERSION}"
```

`--restart unless-stopped` brings the gateway back after a host restart. `--stop-timeout 45` makes a later `docker stop` wait long enough without the `-t` option. Installation snippets generated by a control plane at 1.9.0 or earlier do not include these options, so add them when replacing such a gateway.

`docker run` can attach the container to one network with `--network`. If the old container used additional networks, reconnect each one after the container starts:

```
docker network connect <additional-network> aisix-dp
```

## Verify the Replacement[​](#verify-the-replacement "Direct link to Verify the Replacement")

Wait until the replacement has loaded its configuration:

```
until curl -fs --noproxy 127.0.0.1 "http://127.0.0.1:3000/readyz"; do sleep 1; done; echo
```

If the command keeps waiting, inspect `docker logs aisix-dp` for the cause.

In **Data planes**, confirm that the new instance reports the target version, then send representative requests through the gateway. The replaced instance stays listed with its old version until its registration expires.

Keep the protected inspection file or another complete deployment record until the rollback window closes. Remove the certificate values from your shell after verification:

```
unset AISIX_MANAGED__CP_BASE_URL AISIX_MANAGED__CP_CERT_PEM AISIX_MANAGED__CP_KEY_PEM AISIX_MANAGED__CP_CA_PEM
```

## Roll Back[​](#roll-back "Direct link to Roll Back")

Confirm that the pre-upgrade gateway version remains supported by the current control plane. The staged path for a legacy deployment upgrades its gateways to 1.7.1 before the final control-plane upgrade. During that final step, 1.7.1 is the gateway rollback version.

Repeat [Preserve the Current Deployment](#preserve-the-current-deployment) if the saved inspection and certificate variables are no longer available. Then follow [Replace the Container](#replace-the-container) with `TARGET_VERSION` set to the pre-upgrade version and every recorded container option restored.

Complete [Verify the Replacement](#verify-the-replacement) before continuing with a control-plane rollback.

## Clean Up After the Rollback Window[​](#clean-up-after-the-rollback-window "Direct link to Clean Up After the Rollback Window")

Delete the sensitive inspection file if you created it:

```
rm -f aisix-dp-inspect.json
```