Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: update Upgrade Guide CN version details and conclusion #8392

Merged
merged 1 commit into from
Nov 25, 2022
Merged

docs: update Upgrade Guide CN version details and conclusion #8392

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 68 additions & 64 deletions docs/zh/latest/upgrade-guide-from-2.15.x-to-3.0.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,15 +28,15 @@ description: 本文档将引导你了解如何升级 APISIX 版本。

## APISIX 的版本升级方式

APISIX 的版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
APISIX 的版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。

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

## 从 2.15.x 升级到 3.0.0

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

在升级之前，请查看 [3.0.0-beta](./CHANGELOG.md#300-beta) 和 [3.0.0](./CHANGELOG.md#300) 中的 Change 部分以了解 3.0.0 版本的不兼容的修改与重大更新。
在升级之前，请查看 [3.0.0-beta](./CHANGELOG.md#300-beta) 和 [3.0.0](./CHANGELOG.md#300) 中的 Change 部分，以了解 3.0.0 版本的不兼容的修改与重大更新。

#### 部署

Expand All @@ -45,38 +45,38 @@ APISIX 的版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
目前，我们提供了：

- 基于 debian/centos 的镜像，你可以在 [DockerHub](https://hub.docker.com/r/apache/apisix/tags?page=1&ordering=last_updated) 上找到它们
- CentOS 7 和 CentOS 8 的 RPM 包，支持 amd64 和 arm64 架构，参考 [通过 RPM 仓库安装](./installation-guide.md#通过-rpm-仓库安装)
- Debian 11(bullseye) 的 DEB 包，支持 amd64 和 arm64 架构，参考 [通过 DEB 仓库安装](./installation-guide.md#通过-deb-仓库安装)
- CentOS 7 和 CentOS 8 的 RPM 包，支持 AMD64 和 ARM64 架构，可参考文章[通过 RPM 仓库安装](./installation-guide.md#通过-rpm-仓库安装)
- Debian 11(bullseye) 的 DEB 包，支持 AMD64 和 ARM64 架构，可参考文章[通过 DEB 仓库安装](./installation-guide.md#通过-deb-仓库安装)

3.0.0 对部署模式做了重大更新，具体如下：
3.0.0 对部署模式进行了重大更新，具体如下：

- 支持数据面与控制面分离的部署模式，请参考 [Decoupled](../../en/latest/deployment-modes.md#decoupled)
- 如果需要继续使用原来的部署模式，那么可以使用部署模式中的 `traditional` 模式，并且更新配置文件，请参考 [Traditional](../../en/latest/deployment-modes.md#traditional)
- 支持 Standalone 模式，需要更新配置文件，请参考 [Standalone](../../en/latest/deployment-modes.md#standalone)
- 支持数据面与控制面分离的部署模式，具体可参考 [Decoupled](../../en/latest/deployment-modes.md#decoupled)
- 如在使用中仍需沿用原来的部署模式，那么可以使用部署模式中的 `traditional` 模式，并且更新配置文件，具体可参考 [Traditional](../../en/latest/deployment-modes.md#traditional)
- 支持 Standalone 模式，需要更新配置文件，具体可参考 [Standalone](../../en/latest/deployment-modes.md#standalone)

#### 依赖项

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

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

如果你希望 APISIX 运行在原生的 OpenResty 上，那么只支持 OpenResty 1.19.3.2 及以上的版本。
如果你希望 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`。
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` 字段
* `config_center` 功能改由 `deployment` 中的 `config_provider` 实现
* `etcd` 字段整体迁移到 `deployment` 中
* 以下的 Admin API 配置移动到 `deployment` 中的 `admin` 字段
- admin_key
- enable_admin_cors
- allow_admin
Expand All @@ -93,17 +93,17 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖

调整内容：

* 去除 `apisix.ssl.enable_http2` 和 `apisix.ssl.listen_port`，使用 `apisix.ssl.listen` 替代
* 去除 `apisix.ssl.enable_http2` 和 `apisix.ssl.listen_port`，使用 `apisix.ssl.listen` 替代。

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

```yaml
ssl:
enable_http2: true
listen_port: 9443
```

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

```yaml
ssl:
Expand All @@ -112,9 +112,9 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖
enable_http2: true
```

* 去除 `nginx_config.http.lua_shared_dicts`， 用 `nginx_config.http.custom_lua_shared_dict` 替代，这个配置用于声明自定义插件的共享内存
* 去除 `nginx_config.http.lua_shared_dicts`，用 `nginx_config.http.custom_lua_shared_dict` 替代，这个配置用于声明自定义插件的共享内存。

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

```yaml
nginx_config:
Expand All @@ -123,7 +123,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖
my_dict: 1m
```

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

```yaml
nginx_config:
Expand All @@ -132,33 +132,33 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖
my_dict: 1m
```

* 去除 `etcd.health_check_retry`，用 `deployment.etcd.startup_retry` 替代，这个配置用于在启动时，重试连接 etcd 的次数
* 去除 `etcd.health_check_retry`，用 `deployment.etcd.startup_retry` 替代，这个配置用于在启动时，重试连接 etcd 的次数。

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

```yaml
etcd:
health_check_retry: 2
```

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

```yaml
deployment:
etcd:
startup_retry: 2
```

* 去除 `apisix.port_admin`，用 `deployment.apisix.admin_listen` 替代
* 去除 `apisix.port_admin`，用 `deployment.apisix.admin_listen` 替代。

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

```yaml
apisix:
port_admin: 9180
```

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

```yaml
deployment:
Expand All @@ -168,7 +168,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖
port: 9180
```

* 修改 `enable_cpu_affinity` 的默认值为 `false`。原因：越来越多的用户通过容器部署 APISIX。由于 Nginx 的 worker_cpu_affinity 不计入 cgroup，默认启用 worker_cpu_affinity 会影响 APISIX 的行为，例如，多个实例会被绑定到一个 CPU 上。为了避免这个问题，我们在 `conf/config-default.yaml` 中默认禁用 `enable_cpu_affinity` 选项。
* 修改 `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` 替代

##### 数据迁移
Expand All @@ -177,18 +177,18 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖

#### 数据兼容

在 3.0.0 中，我们调整了部分数据结构，这些调整影响到 APISIX 的路由、上游、插件等数据。3.0.0 版本与 2.15.x 版本之间数据不完全兼容。不能用 3.0.0 版本的 APISIX 直接连接到 2.15.x 版本的 APISIX 使用的 ETCD 集群。
在 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` 移动到 `_meta` 中。

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

```json
{
Expand All @@ -201,7 +201,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖
}
```

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

```json
{
Expand All @@ -216,11 +216,11 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖
}
```

注意：`disable` 是插件的元配置，这个调整对所有插件配置生效，不仅仅是 `limit-count` 插件。
注意：`disable` 是插件的元配置，该调整对所有插件配置生效，不仅仅是 `limit-count` 插件。

* 去除路由的 `service_protocol` 字段，使用 `upstream.scheme` 替代
* 去除路由的 `service_protocol` 字段，使用 `upstream.scheme` 替代。

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

```json
{
Expand All @@ -235,7 +235,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖
}
```

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

```json
{
Expand All @@ -250,9 +250,9 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖
}
```

* 去除 authz-keycloak 插件中的 `audience` 字段，使用 `client_id` 替代
* 去除 `authz-keycloak` 插件中的 `audience` 字段，使用 `client_id` 替代。

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

```json
{
Expand All @@ -265,7 +265,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖
}
```

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

```json
{
Expand All @@ -278,9 +278,9 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖
}
```

* 去除 mqtt-proxy 插件中的 `upstream`，在插件外部配置 `upstream`，并在插件中引用
* 去除 `mqtt-proxy` 插件中的 `upstream`，在插件外部配置 `upstream`，并在插件中引用。

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

```json
{
Expand All @@ -298,7 +298,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖
}
```

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

```json
{
Expand All @@ -323,9 +323,9 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖
}
```

* 去除 syslog 插件中的 `max_retry_times` 和 `retry_interval` 字段，使用 `max_retry_count` 和 `retry_delay` 替代
* 去除 `syslog` 插件中的 `max_retry_times` 和 `retry_interval` 字段，使用 `max_retry_count` 和 `retry_delay` 替代。

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

```json
{
Expand All @@ -339,7 +339,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖
}
```

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

```json
{
Expand All @@ -353,9 +353,9 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖
}
```

* 去除 proxy-rewrite 插件中的 `scheme` 字段，在配置上游时，用 `upstream.scheme` 替代
* 去除 `proxy-rewrite` 插件中的 `scheme` 字段，在配置上游时，用 `upstream.scheme` 替代。

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

```json
{
Expand All @@ -375,7 +375,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖
}
```

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

```json
{
Expand All @@ -397,13 +397,11 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖

#### Admin API

我们对 Admin API 进行了一些调整，这些调整是为了使 Admin API 更加易用，更加符合 RESTful 的设计理念。

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

* 操作资源时（包括查询单个资源和列表资源），删除了响应体中的 `count`、 `action` 和 `node` 字段，并且将 `node` 中的内容提升到响应体的根节点
* 操作资源时（包括查询单个资源和列表资源），删除了响应体中的 `count`、`action` 和 `node` 字段，并将 `node` 中的内容提升到响应体的根节点。

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

```json
{
Expand All @@ -418,7 +416,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖
}
```

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

```json
{
Expand All @@ -429,9 +427,9 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖
}
```

* 查询列表资源时，删除 `dir` 字段，新增 `list` 字段，存放列表资源的数据，新增 `total` 字段，存放列表资源的总数
* 查询列表资源时，删除 `dir` 字段，新增 `list` 字段，存放列表资源的数据；新增 `total` 字段，存放列表资源的总数。

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

```json
{
Expand All @@ -458,7 +456,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖
}
```

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

```json
{
Expand All @@ -481,32 +479,38 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖
}
```

* 调整 ssl 资源的请求路径，从 `/apisix/admin/ssl/{id}` 改为 `/apisix/admin/ssls/{id}`
* 调整 ssl 资源的请求路径，从 `/apisix/admin/ssl/{id}` 调整为 `/apisix/admin/ssls/{id}`。

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

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

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

```shell
curl -i http://{apisix_listen_address}/apisix/admin/ssls/{id}
```

* 调整 proto 资源的请求路径，从 `/apisix/admin/proto/{id}` 改为 `/apisix/admin/protos/{id}`
* 调整 proto 资源的请求路径，从 `/apisix/admin/proto/{id}` 调整为 `/apisix/admin/protos/{id}`。

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

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

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

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

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

## 总结

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

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