Skip to main content
Version: 3.1

升级指南

APISIX 的版本升级方式#

APISIX 的版本号遵循语义化版本

升级到 APISIX 3.0.0 是一个重大的版本升级,我们建议您先升级到 2.15.x,然后再升级到 3.0.0。

从 2.15.x 升级到 3.0.0#

升级注意事项和重大更新#

在升级之前,请查看 3.0.0-beta3.0.0 中的 Change 部分,以了解 3.0.0 版本的不兼容的修改与重大更新。

部署#

基于 alpine 的镜像已不再支持,如果你使用了 alpine 的镜像,那么你需要将镜像替换为基于 debian/centos 的镜像。

目前,我们提供了:

  • 基于 debian/centos 的镜像,你可以在 DockerHub 上找到它们
  • CentOS 7 和 CentOS 8 的 RPM 包,支持 AMD64 和 ARM64 架构,可参考文章通过 RPM 仓库安装
  • Debian 11(bullseye) 的 DEB 包,支持 AMD64 和 ARM64 架构,可参考文章通过 DEB 仓库安装

3.0.0 对部署模式进行了重大更新,具体如下:

  • 支持数据面与控制面分离的部署模式,具体可参考 Decoupled
  • 如在使用中仍需沿用原来的部署模式,那么可以使用部署模式中的 traditional 模式,并且更新配置文件,具体可参考 Traditional
  • 支持 Standalone 模式,需要更新配置文件,具体可参考 Standalone

依赖项#

如果你使用提供的二进制包(Debian 和 RHEL)或者镜像,则它们已经捆绑了 APISIX 所有必要的依赖项,你可以跳过本节。

APISIX 的一些特性需要在 OpenResty 中引入额外的 NGINX 模块。如果要使用这些功能,你需要构建一个自定义的 OpenResty 发行版(APISIX-Base)。你可以参考 api7/apisix-build-tools 中的代码,构建自己的 APISIX-Base 环境。

如果你希望 APISIX 运行在原生的 OpenResty 上,这种情况下将只支持运行在 OpenResty 1.19.3.2 及以上的版本。

迁移#

静态配置迁移#

APISIX 的配置方式是用自定义的 conf/config.yaml 中的内容覆盖默认的 conf/config-default.yaml,如果某个配置项在 conf/config.yaml 中不存在,那么就使用 conf/config-default.yaml 中的配置。在 3.0.0 中,我们调整了 conf/config-default.yaml 配置文件中的部分细节,具体内容如下。

移动配置项#

从 2.15.x 到 3.0.0 版本,在 conf/config-default.yaml 有一些配置项的位置被移动了。如果你使用了这些配置项,那么你需要将它们移动到新的位置。

调整内容:

  • config_center 功能改由 deployment 中的 config_provider 实现
  • etcd 字段整体迁移到 deployment
  • 以下的 Admin API 配置移动到 deployment 中的 admin 字段
    • admin_key
    • enable_admin_cors
    • allow_admin
    • admin_listen
    • https_admin
    • admin_api_mtls
    • admin_api_version

你可以在 conf/config-default.yaml 中找到这些配置的新的确切位置。

更新配置项#

某些配置在 3.0.0 中被移除了,并被新的配置项替代。如果你使用了这些配置项,那么你需要将它们更新为新的配置项。

调整内容:

  • 去除 apisix.ssl.enable_http2apisix.ssl.listen_port,使用 apisix.ssl.listen 替代。

    如果在 conf/config.yaml 中有这样的配置:

      ssl:
    enable_http2: true
    listen_port: 9443

    则在 3.0.0 版本中需要转换成如下所示:

      ssl:
    listen:
    - port: 9443
    enable_http2: true
  • 去除 nginx_config.http.lua_shared_dicts,用 nginx_config.http.custom_lua_shared_dict 替代,这个配置用于声明自定义插件的共享内存。

    如果在 conf/config.yaml 中有这样的配置:

    nginx_config:
    http:
    lua_shared_dicts:
    my_dict: 1m

    则在 3.0.0 版本中需要转换成如下所示:

    nginx_config:
    http:
    custom_lua_shared_dict:
    my_dict: 1m
  • 去除 etcd.health_check_retry,用 deployment.etcd.startup_retry 替代,这个配置用于在启动时,重试连接 etcd 的次数。

    如果在 conf/config.yaml 中有这样的配置:

    etcd:
    health_check_retry: 2

    则在 3.0.0 版本中需要转换成如下所示:

    deployment:
    etcd:
    startup_retry: 2
  • 去除 apisix.port_admin,用 deployment.apisix.admin_listen 替代。

    如果在 conf/config.yaml 中有这样的配置:

    apisix:
    port_admin: 9180

    则在 3.0.0 中需要转换成如下所示:

    deployment:
    apisix:
    admin_listen:
    ip: 127.0.0.1 # 替换成实际暴露的 IP
    port: 9180
  • 修改 enable_cpu_affinity 的默认值为 false。主要是因为越来越多的用户通过容器部署 APISIX,由于 Nginx 的 worker_cpu_affinity 不计入 cgroup,默认启用 worker_cpu_affinity 会影响 APISIX 的行为,例如多个实例会被绑定到一个 CPU 上。为了避免这个问题,我们在 conf/config-default.yaml 中默认禁用 enable_cpu_affinity 选项。

  • 去除 apisix.real_ip_header,用 nginx_config.http.real_ip_header 替代

数据迁移#

如果你需要备份与恢复数据,可以利用 ETCD 的备份与恢复功能,参考 etcdctl snapshot

数据兼容#

在 3.0.0 中,我们调整了部分数据结构,这些调整影响到 APISIX 的路由、上游、插件等数据。3.0.0 版本与 2.15.x 版本之间数据不完全兼容。因此,你无法使用 3.0.0 版本的 APISIX 直接连接到 2.15.x 版本 APISIX 使用的 ETCD 集群。

为了保持数据兼容,有两种方式,仅供参考:

  1. 梳理 ETCD 中的数据,将不兼容的数据备份然后清除,将备份的数据结构转换成 3.0.0 版本的数据结构,通过 3.0.0 版本的 Admin API 来恢复数据
  2. 梳理 ETCD 中的数据,编写脚本,将 2.15.x 版本的数据结构批量转换成 3.0.0 版本的数据结构

数据层面调整内容如下。

  • 将插件配置的元属性 disable 移动到 _meta 中。

    disable 表示该插件的启用/禁用状态,如果在 ETCD 中存在这样的数据结构:

    {
    "plugins":{
    "limit-count":{
    ... // 插件配置
    "disable":true
    }
    }
    }

    则在 3.0.0 版本中,这个插件的数据结构应该变成如下所示:

    {
    "plugins":{
    "limit-count":{
    ... // 插件配置
    "_meta":{
    "disable":true
    }
    }
    }
    }

    注意:disable 是插件的元配置,该调整对所有插件配置生效,不仅仅是 limit-count 插件。

  • 去除路由的 service_protocol 字段,使用 upstream.scheme 替代。

    如果在 ETCD 中存在这样的数据结构:

    {
    "uri":"/hello",
    "service_protocol":"grpc",
    "upstream":{
    "type":"roundrobin",
    "nodes":{
    "127.0.0.1:1980":1
    }
    }
    }

    则在 3.0.0 版本中,这个路由的数据结构应该变成如下所示:

    {
    "uri":"/hello",
    "upstream":{
    "type":"roundrobin",
    "scheme":"grpc",
    "nodes":{
    "127.0.0.1:1980":1
    }
    }
    }
  • 去除 authz-keycloak 插件中的 audience 字段,使用 client_id 替代。

    如果在 ETCD 中 authz-keycloak 的插件配置存在这样的数据结构:

    {
    "plugins":{
    "authz-keycloak":{
    ... // 插件配置
    "audience":"Client ID"
    }
    }
    }

    则在 3.0.0 中,这个路由的数据结构应该变成如下所示:

    {
    "plugins":{
    "authz-keycloak":{
    ... // 插件配置
    "client_id":"Client ID"
    }
    }
    }
  • 去除 mqtt-proxy 插件中的 upstream,在插件外部配置 upstream,并在插件中引用。

    如果在 ETCD 中 mqtt-proxy 的插件配置存在这样的数据结构:

    {
    "remote_addr":"127.0.0.1",
    "plugins":{
    "mqtt-proxy":{
    "protocol_name":"MQTT",
    "protocol_level":4,
    "upstream":{
    "ip":"127.0.0.1",
    "port":1980
    }
    }
    }
    }

    则在 3.0.0 版本中,这个插件的数据结构应该变成如下所示:

    {
    "remote_addr":"127.0.0.1",
    "plugins":{
    "mqtt-proxy":{
    "protocol_name":"MQTT",
    "protocol_level":4
    }
    },
    "upstream":{
    "type":"chash",
    "key":"mqtt_client_id",
    "nodes":[
    {
    "host":"127.0.0.1",
    "port":1980,
    "weight":1
    }
    ]
    }
    }
  • 去除 syslog 插件中的 max_retry_timesretry_interval 字段,使用 max_retry_countretry_delay 替代。

    如果在 ETCD 中 syslog 的插件配置存在这样的数据结构:

    {
    "plugins":{
    "syslog":{
    "max_retry_times":1,
    "retry_interval":1,
    ... // 其他配置
    }
    }
    }

    则在 3.0.0 版本中,这个插件的数据结构应该变成如下所示:

    {
    "plugins":{
    "syslog":{
    "max_retry_count":1,
    "retry_delay":1,
    ... // 其他配置
    }
    }
    }
  • 去除 proxy-rewrite 插件中的 scheme 字段,在配置上游时,用 upstream.scheme 替代。

    如果在 ETCD 中 proxy-rewrite 的插件配置存在这样的数据结构:

    {
    "plugins":{
    "proxy-rewrite":{
    "scheme":"https",
    ... // 其他配置
    }
    },
    "upstream":{
    "nodes":{
    "127.0.0.1:1983":1
    },
    "type":"roundrobin"
    },
    "uri":"/hello"
    }

    则在 3.0.0 版本中,这个插件的数据结构应该变成如下所示:

    {
    "plugins":{
    "proxy-rewrite":{
    ... // 其他配置
    }
    },
    "upstream":{
    "scheme":"https",
    "nodes":{
    "127.0.0.1:1983":1
    },
    "type":"roundrobin"
    },
    "uri":"/hello"
    }

Admin API#

在 3.0.0 版本中,我们对 Admin API 也进行了一些调整。使得 Admin API 更加易用,更加符合 RESTful 的设计理念,具体调整内容如下。

  • 操作资源时(包括查询单个资源和列表资源),删除了响应体中的 countactionnode 字段,并将 node 中的内容提升到响应体的根节点。

    在 2.x 版本中,通过 Admin API 查询 /apisix/admin/routes/1 的响应格式是这样的:

    {
    "count":1,
    "action":"get",
    "node":{
    "key":"\/apisix\/routes\/1",
    "value":{
    ... // 配置内容
    }
    }
    }

    在 3.0.0 版本中,通过 Admin API 查询 /apisix/admin/routes/1 资源的响应格式调整为如下所示:

    {
    "key":"\/apisix\/routes\/1",
    "value":{
    ... // 配置内容
    }
    }
  • 查询列表资源时,删除 dir 字段,新增 list 字段,存放列表资源的数据;新增 total 字段,存放列表资源的总数。

    在 2.x 版本中,通过 Admin API 查询 /apisix/admin/routes 的响应格式是这样的:

    {
    "action":"get",
    "count":2,
    "node":{
    "key":"\/apisix\/routes",
    "nodes":[
    {
    "key":"\/apisix\/routes\/1",
    "value":{
    ... // 配置内容
    }
    },
    {
    "key":"\/apisix\/routes\/2",
    "value":{
    ... // 配置内容
    }
    }
    ],
    "dir":true
    }
    }

    在 3.0.0 版本中,通过 Admin API 查询 /apisix/admin/routes 资源的响应格式调整为如下所示:

    {
    "list":[
    {
    "key":"\/apisix\/routes\/1",
    "value":{
    ... // 配置内容
    }

    },
    {
    "key":"\/apisix\/routes\/2",
    "value":{
    ... // 配置内容
    }
    }
    ],
    "total":2
    }
  • 调整 ssl 资源的请求路径,从 /apisix/admin/ssl/{id} 调整为 /apisix/admin/ssls/{id}

    在 2.x 版本中,通过 Admin API 操作 ssl 资源是这样的:

    curl -i http://{apisix_listen_address}/apisix/admin/ssl/{id}

    在 3.0.0 版本中,通过 Admin API 操作 ssl 资源调整为如下所示:

    curl -i http://{apisix_listen_address}/apisix/admin/ssls/{id}
  • 调整 proto 资源的请求路径,从 /apisix/admin/proto/{id} 调整为 /apisix/admin/protos/{id}

    在 2.x 版本中,通过 Admin API 操作 proto 资源是这样的:

    curl -i http://{apisix_listen_address}/apisix/admin/proto/{id}

    在 3.0.0 版本中,通过 Admin API 操作 proto 资源调整为如下所示:

    curl -i http://{apisix_listen_address}/apisix/admin/protos/{id}

除以上内容外,我们也将 Admin API 的端口调整为 9180。

总结#

Apache APISIX 3.0.0 版本的发布,将产品的更多细节迭代了一大步。由于大版本的更新迭代会导致一些配置与数据也相应进行调整,为此我们为您整理了这份 APISIX 升级指南。希望对各位在使用 APISIX 的过程中,对于版本的更新操作也更得心应手。

如果您有任何问题或意见,欢迎随时在社区进行交流。