Project: APISIX (Orchestration & Management / API Gateway)
File: upgrade-guide-from-2.15.x-to-3.0.0.md

title: Upgrade Guide keywords: APISIX APISIX Upgrade Guide APISIX Version Upgrade description: Guide for upgrading APISIX from version 2.15.x to 3.0.0. <!-- --> This document guides you in upgrading APISIX from version 2.15.x to 3.0.0. :::note Upgrading to version 3.0.0 is a major change and it is recommended that you first upgrade to version 2.15.x before you upgrade to 3.0.0. ::: Please refer to the and changelogs for a complete list of incompatible changes and major updates. From 3.0.0, we no longer support the Alpine-based images of APISIX. You can use the instead. In addition to the Docker images, we also provide: RPM packages for CentOS 7 and CentOS 8 supporting both AMD64 and ARM64 architectures. DEB packages for Debian 11 (bullseye) supporting both AMD64 and ARM64 architectures. See the for more details. 3.0.0 also introduces multiple deployment modes. The following modes are supported: : As the name implies, this is the original deployment mode where one instance of APISIX acts as the control plane and the data plane. Use this deployment mode to keep your deployment similar to older versions. : In this mode, the data plane and the control plane are separated. You can deploy an instance of APISIX either as a control plane or a data plane. : Using this mode will disable etcd as the configuration center and use a static configuration file instead. You can use this to manage APISIX configuration decaratively or for using other configuration centers. All Docker images and binary packages (RPM, DEB) already come with all the necessary dependencies for APISIX. Some features might require additional Nginx modules in OpenResty and requires you to . To run APISIX on a native OpenResty instance use and above. There are some major changes to the configuration file in APISIX. You need to update your configuration file (`conf/config.yaml`) to reflect these changes. See the `conf/config-default.yaml` file for the complete changes. The following attributes in the configuration have been moved: `configcenter` is replaced by `configprovider` and moved under `deployment`. `etcd` is moved under `deployment`. The following Admin API configuration attributes are moved to the `admin` attribute under `deployment`: `admin_key` `enableadmincors` `allow_admin` `admin_listen` `https_admin` `adminapimtls` `adminapiversion` The following attributes in the configuration have been replaced: `enablehttp2` and `listenport` under `apisix.ssl` are replaced by `apisix.ssl.listen`. i.e., the below configuration: ```yaml title="conf/config.yaml" ssl: enable_http2: true listen_port: 9443 ``` changes to: ```yaml title="conf/config.yaml" ssl: listen: port: 9443 enable_http2: true ``` `nginxconfig.http.luashareddicts` is replaced by `nginxconfig.http.customluashared_dict`. i.e., the below configuration: ```yaml title="conf/config.yaml" nginx_config: http: luashareddicts: my_dict: 1m ``` changes to: ```yaml

nginx_config: http: customluashared_dict: my_dict: 1m ``` This attribute declares custom shared memory blocks. `etcd.healthcheckretry` is replaced by `deployment.etcd.startup_retry`. So this configuration: ```yaml title="conf/config.yaml" etcd: healthcheckretry: 2 ``` changes to: ```yaml title="conf/config.yaml" deployment: etcd: startup_retry: 2 ``` This attribute is to configure the number of retries when APISIX tries to connect to etcd. `apisix.portadmin` is replaced by `deployment.admin.adminlisten`. So your previous configuration: ```yaml title="conf/config.yaml" apisix: port_admin: 9180 ``` Should be changed to: ```yaml title="conf/config.yaml" deployment: apisix: admin_listen: ip: 127.0.0.1 # replace with the actual IP exposed port: 9180 ``` This attribute configures the Admin API listening port. `apisix.realipheader` is replaced by `nginxconfig.http.realip_header`. `enablecpuaffinity` is set to `false` by default instead of `true`. This is because Nginx's `workercpuaffinity` does not count against the cgroup when APISIX is deployed in containers. In such scenarios, it can affect APISIX's behavior when multiple instances are bound to a single CPU. In 3.0.0, the data structures holding route, upstream, and plugin configuration have been modified and is not fully compatible with 2.15.x. You won't be able to connect an instance of APISIX 3.0.0 to an etcd cluster used by APISIX 2.15.x. To ensure compatibility, you can try one of the two ways mentioned below: Backup the incompatible data (see ) in etcd and clear it. Convert the backed up data to be compatible with 3.0.0 as mentioned in the below examples and reconfigure it through the Admin API of 3.0.0 instance. Use custom scripts to convert the data structure in etcd to be compatible with 3.0.0. The following changes have been made in version 3.0.0: `disable` attribute of a plugin has been moved under `_meta`. It enables or disables the plugin. For example, this configuration to disable the `limit-count` plugin: ```json { "plugins":{ "limit-count":{ ... // plugin configuration "disable":true } } } ``` should be changed to: ```json { "plugins":{ "limit-count":{ ... // plugin configuration "_meta":{ "disable":true } } } } ``` `service_protocol` in route has been replaced with `upstream.scheme`. For example, this configuration: ```json { "uri": "/hello", "service_protocol": "grpc", "upstream": { "type": "roundrobin", "nodes": { "127.0.0.1:1980": 1 } } } ``` Should be changed to: ```json { "uri": "/hello", "upstream": { "type": "roundrobin", "scheme": "grpc", "nodes": { "127.0.0.1:1980": 1 } } } ``` `audience` field from the plugin has been replaced with `client_id`. So this configuration: ```json { "plugins":{ "authz-keycloak":{ ... // plugin configuration "audience":"Client ID" } } } ``` should be changed to: ```json { "plugins":{ "authz-keycloak":{

// plugin configuration "client_id":"Client ID" } } } ``` `upstream` attribute from the plugin has been moved outside the plugin conference and referenced in the plugin. The configuration below: ```json { "remote_addr": "127.0.0.1", "plugins": { "mqtt-proxy": { "protocol_name": "MQTT", "protocol_level": 4, "upstream": { "ip": "127.0.0.1", "port": 1980 } } } } ``` changes to: ```json { "remote_addr": "127.0.0.1", "plugins": { "mqtt-proxy": { "protocol_name": "MQTT", "protocol_level": 4 } }, "upstream": { "type": "chash", "key": "mqttclientid", "nodes": [ { "host": "127.0.0.1", "port": 1980, "weight": 1 } ] } } ``` `maxretrytimes` and `retryinterval` fields from the plugin are replaced `maxretrycount` and `retrydelay` respectively. The configuration below: ```json { "plugins":{ "syslog":{ "maxretrytimes":1, "retry_interval":1, ... // other configuration } } } ``` changes to: ```json { "plugins":{ "syslog":{ "maxretrycount":1, "retry_delay":1, ... // other configuration } } } ``` `scheme` attribute has been removed from the plugin and has been added to the upstream. The configuration below: ```json { "plugins":{ "proxy-rewrite":{ "scheme":"https", ... // other configuration } }, "upstream":{ "nodes":{ "127.0.0.1:1983":1 }, "type":"roundrobin" }, "uri":"/hello" } ``` changes to: ```json { "plugins":{ "proxy-rewrite":{ ... // other configuration } }, "upstream":{ "scheme":"https", "nodes":{ "127.0.0.1:1983":1 }, "type":"roundrobin" }, "uri":"/hello" } ``` Changes have been made to the Admin API to make it easier to use and be more RESTful. The following changes have been made: The `count`, `action`, and `node` fields in the response body when querying resources (single and list) are removed and the fields in `node` are moved up to the root of the response body. For example, if you query the `/apisix/admin/routes/1` endpoint of the Admin API in version 2.15.x, you get the response: ```json { "count":1, "action":"get", "node":{ "key":"\/apisix\/routes\/1", "value":{ ... // content } } } ``` In 3.0.0, this response body is changes to: ```json { "key":"\/apisix\/routes\/1", "value":{ ... // content } } ``` When querying list resources, the `dir` field is removed from the response body, a `list` field to store the data of the list resources and a `total` field to show the total number of list resources are added. For example, if you query the `/apisix/admin/routes` endpoint of the Admin API in version 2.15.x, you get the response: ```json { "action":"get", "count":2, "node":{ "key":"\/apisix\/routes", "nodes":[ { "key":"\/apisix\/routes\/1", "value":{ ... // content } }, { "key":"\/apisix\/routes\/2", "value":{ ... // content } } ], "dir":true } } ``` In 3.0.0, the response body is: ```json { "list":[ { "key":"\/apisix\/routes\/1", "value":{ ... // content } }, { "key":"\/apisix\/routes\/2", "value":{ ... // content } } ], "total":2 } ``` The endpoint to SSL resource is changed from `/apisix/admin/ssl/{id}` to `/apisix/admin/ssls/{id}`. The endpoint to Proto resource is changed from `/apisix/admin/proto/{id}` to `/apisix/admin/protos/{id}`. Admin API port is set to `9180` by default.