Upgrade Guide

This document guides you in upgrading APISIX from version 2.15.x to 3.0.0.

Upgrade Guide - 图1note

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.

Changelog

Please refer to the 3.0.0-beta and 3.0.0 changelogs for a complete list of incompatible changes and major updates.

Deployments

From 3.0.0, we no longer support the Alpine-based images of APISIX. You can use the Debian or CentOS-based images instead.

In addition to the Docker images, we also provide:

  1. RPM packages for CentOS 7 and CentOS 8 supporting both AMD64 and ARM64 architectures.
  2. DEB packages for Debian 11 (bullseye) supporting both AMD64 and ARM64 architectures.

See the installation guide for more details.

3.0.0 also introduces multiple deployment modes. The following modes are supported:

  1. Traditional: 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.
  2. Decoupled: 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.
  3. Standalone: 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.

Dependencies

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 build a custom OpenResty distribution (APISIX-Base).

To run APISIX on a native OpenResty instance use OpenResty version 1.19.3.2 and above.

Configurations

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:

  1. config_center is replaced by config_provider and moved under deployment.
  2. etcd is moved under deployment.
  3. The following Admin API configuration attributes are moved to the admin attribute under deployment:
    1. admin_key
    2. enable_admin_cors
    3. allow_admin
    4. admin_listen
    5. https_admin
    6. admin_api_mtls
    7. admin_api_version

The following attributes in the configuration have been replaced:

  1. enable_http2 and listen_port under apisix.ssl are replaced by apisix.ssl.listen. i.e., the below configuration:

    conf/config.yaml

    1. ssl:
    2.   enable_http2: true
    3.   listen_port: 9443

    changes to:

    conf/config.yaml

    1. ssl:
    2.   listen:
    3.     - port: 9443
    4.       enable_http2: true

  2. nginx_config.http.lua_shared_dicts is replaced by nginx_config.http.custom_lua_shared_dict. i.e., the below configuration:

    conf/config.yaml

    1. nginx_config:
    2.   http:
    3.     lua_shared_dicts:
    4.       my_dict: 1m

    changes to:

    conf/config.yaml

    1. nginx_config:
    2.   http:
    3.     custom_lua_shared_dict:
    4.     my_dict: 1m

    This attribute declares custom shared memory blocks.

  3. etcd.health_check_retry is replaced by deployment.etcd.startup_retry. So this configuration:

    conf/config.yaml

    1. etcd:
    2.   health_check_retry: 2

    changes to:

    conf/config.yaml

    1. deployment:
    2.   etcd:
    3.     startup_retry: 2

    This attribute is to configure the number of retries when APISIX tries to connect to etcd.

  4. apisix.port_admin is replaced by deployment.admin.admin_listen. So your previous configuration:

    conf/config.yaml

    1. apisix:
    2.   port_admin: 9180

    Should be changed to:

    conf/config.yaml

    1. deployment:
    2.   apisix:
    3.     admin_listen:
    4.       ip: 127.0.0.1 # replace with the actual IP exposed
    5.       port: 9180

    This attribute configures the Admin API listening port.

  5. apisix.real_ip_header is replaced by nginx_config.http.real_ip_header.

  6. enable_cpu_affinity is set to false by default instead of true. This is because Nginx’s worker_cpu_affinity 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.

Data Compatibility

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:

  1. Backup the incompatible data (see etcdctl snapshot) 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.
  2. 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:

  1. 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:

    1. {
    2.  "plugins":{
    3.      "limit-count":{
    4.          ... // plugin configuration
    5.          "disable":true
    6.      }
    7.  }
    8. }

    should be changed to:

    1. {
    2.  "plugins":{
    3.      "limit-count":{
    4.          ... // plugin configuration
    5.          "_meta":{
    6.              "disable":true
    7.          }
    8.      }
    9.  }
    10. }

  2. service_protocol in route has been replaced with upstream.scheme. For example, this configuration:

    1. {
    2.   "uri": "/hello",
    3.   "service_protocol": "grpc",
    4.   "upstream": {
    5.     "type": "roundrobin",
    6.     "nodes": {
    7.       "127.0.0.1:1980": 1
    8.     }
    9.   }
    10. }

    Should be changed to:

    1. {
    2.   "uri": "/hello",
    3.   "upstream": {
    4.     "type": "roundrobin",
    5.     "scheme": "grpc",
    6.     "nodes": {
    7.       "127.0.0.1:1980": 1
    8.     }
    9.   }
    10. }

  3. audience field from the authz-keycloak plugin has been replaced with client_id. So this configuration:

    1. {
    2.  "plugins":{
    3.      "authz-keycloak":{
    4.          ... // plugin configuration
    5.          "audience":"Client ID"
    6.      }
    7.  }
    8. }

    should be changed to:

    1. {
    2.  "plugins":{
    3.      "authz-keycloak":{
    4.          ... // plugin configuration
    5.          "client_id":"Client ID"
    6.      }
    7.  }
    8. }

  4. upstream attribute from the mqtt-proxy plugin has been moved outside the plugin conference and referenced in the plugin. The configuration below:

    1. {
    2.   "remote_addr": "127.0.0.1",
    3.   "plugins": {
    4.     "mqtt-proxy": {
    5.       "protocol_name": "MQTT",
    6.       "protocol_level": 4,
    7.       "upstream": {
    8.         "ip": "127.0.0.1",
    9.         "port": 1980
    10.       }
    11.     }
    12.   }
    13. }

    changes to:

    1. {
    2.   "remote_addr": "127.0.0.1",
    3.   "plugins": {
    4.     "mqtt-proxy": {
    5.       "protocol_name": "MQTT",
    6.       "protocol_level": 4
    7.     }
    8.   },
    9.   "upstream": {
    10.     "type": "chash",
    11.     "key": "mqtt_client_id",
    12.     "nodes": [
    13.       {
    14.         "host": "127.0.0.1",
    15.         "port": 1980,
    16.         "weight": 1
    17.       }
    18.     ]
    19.   }
    20. }

  5. max_retry_times and retry_interval fields from the syslog plugin are replaced max_retry_count and retry_delay respectively. The configuration below:

    1. {
    2.  "plugins":{
    3.      "syslog":{
    4.          "max_retry_times":1,
    5.          "retry_interval":1,
    6.          ... // other configuration
    7.      }
    8.  }
    9. }

    changes to:

    1. {
    2.  "plugins":{
    3.      "syslog":{
    4.          "max_retry_count":1,
    5.          "retry_delay":1,
    6.          ... // other configuration
    7.      }
    8.  }
    9. }

  6. scheme attribute has been removed from the proxy-rewrite plugin and has been added to the upstream. The configuration below:

    1. {
    2.  "plugins":{
    3.      "proxy-rewrite":{
    4.          "scheme":"https",
    5.          ... // other configuration
    6.      }
    7.  },
    8.  "upstream":{
    9.      "nodes":{
    10.          "127.0.0.1:1983":1
    11.      },
    12.      "type":"roundrobin"
    13.  },
    14.  "uri":"/hello"
    15. }

    changes to:

    1. {
    2. "plugins":{
    3.    "proxy-rewrite":{
    4.        ... // other configuration
    5.    }
    6. },
    7. "upstream":{
    8.    "scheme":"https",
    9.    "nodes":{
    10.        "127.0.0.1:1983":1
    11.    },
    12.    "type":"roundrobin"
    13. },
    14. "uri":"/hello"
    15. }

API

Changes have been made to the Admin API to make it easier to use and be more RESTful.

The following changes have been made:

  1. 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:

    1. {
    2. "count":1,
    3. "action":"get",
    4. "node":{
    5.    "key":"\/apisix\/routes\/1",
    6.    "value":{
    7.        ... // content
    8.    }
    9. }
    10. }

    In 3.0.0, this response body is changes to:

    1. {
    2. "key":"\/apisix\/routes\/1",
    3. "value":{
    4.    ... // content
    5. }
    6. }

  2. 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:

    1. {
    2. "action":"get",
    3. "count":2,
    4. "node":{
    5.    "key":"\/apisix\/routes",
    6.    "nodes":[
    7.        {
    8.            "key":"\/apisix\/routes\/1",
    9.            "value":{
    10.                ... // content
    11.            }
    12.        },
    13.        {
    14.            "key":"\/apisix\/routes\/2",
    15.            "value":{
    16.                ... // content
    17.            }
    18.        }
    19.    ],
    20.    "dir":true
    21. }
    22. }

    In 3.0.0, the response body is:

    1. {
    2. "list":[
    3.    {
    4.        "key":"\/apisix\/routes\/1",
    5.        "value":{
    6.            ... // content
    7.        }
    9.    },
    10.    {
    11.        "key":"\/apisix\/routes\/2",
    12.        "value":{
    13.            ... // content
    14.        }
    15.    }
    16. ],
    17. "total":2
    18. }

  3. The endpoint to SSL resource is changed from /apisix/admin/ssl/{id} to /apisix/admin/ssls/{id}.

  4. The endpoint to Proto resource is changed from /apisix/admin/proto/{id} to /apisix/admin/protos/{id}.

  5. Admin API port is set to 9180 by default.