doc: update 1.6 upgrade guide (#1592)
Co-authored-by: rongxin <alinsran@apache.org>
Co-authored-by: Navendu Pottekkat <navendupottekkat@gmail.com>
diff --git a/docs/en/latest/upgrade.md b/docs/en/latest/upgrade.md
index eb3fd6d..130b28d 100644
--- a/docs/en/latest/upgrade.md
+++ b/docs/en/latest/upgrade.md
@@ -21,9 +21,30 @@
#
-->
+## Version change
+
+### ***1.6.0***
+
+APISIX 3.x.x has changed the Admin API. To make APISIX Ingress compatible with these changes, you need to select the corresponding chart version. Please refer [1.5 to 1.6](#15-to-16).
+
+### ***1.5.0***
+
+- CRD has been upgraded to the V2 version, and V2beta3 has been marked as deprecated.
+- `app_namespace` is deprecated. you can use `namespace_selector` instead.
+
+### ***1.4.0***
+
+- CRD unified upgrade to V2beta3, delete resource v2alpha1 and v1 versions
+
## Upgrade using Helm chart
-Note: Before upgrading APISIX Ingress, you need to update the corresponding CRD resource first, k8s will automatically replace it with the default CRD resource version, incompatible items will be discarded, and its configuration needs to be updated to the current version.
+Before upgrading APISIX Ingress, you need to update the corresponding CRD resource first, k8s will automatically replace it with the default CRD resource version, incompatible items will be discarded, and its configuration needs to be updated to the current version.
+
+:::note
+
+It is recommended not to upgrade across versions.
+
+:::
### Operating Step
@@ -49,12 +70,12 @@
> CRDs directory: `charts/apisix-ingress-controller/crds/customresourcedefinitions.yaml`
>
> ```sh
-> kubectl apply -f https://raw.githubusercontent.com/apache/apisix-helm-chart/apisix-0.11.1/charts/apisix-ingress-controller/crds/customresourcedefinitions.yaml
+> kubectl apply -f https://raw.githubusercontent.com/apache/apisix-helm-chart/apisix-1.1.0/charts/apisix-ingress-controller/crds/customresourcedefinitions.yaml
> ```
-3. UpgradeAPISIX Ingress
+3. Upgrade APISIX Ingress
-Just as an example, the specific configuration needs to be modified by yourself. If you want to upgrade to a specific chart version, please add this flag `--version x.x.x`.
+Just as an example, the specific configuration needs to be modified by yourself. If you want to upgrade to a specific chart version, please add this flag `--version x.x.x`, Please refer [compatible-upgrade](#compatible-upgrade) or [incompatible-upgrade](#incompatible-upgrade).
```sh
helm upgrade apisix apisix/apisix \
@@ -64,23 +85,46 @@
--set ingress-controller.config.apisix.serviceNamespace=ingress-apisix
```
-### Precautions
-
-It is recommended not to upgrade across major versions.
-
### Compatible upgrade
Compatible upgrades can be made without changing any resources.
#### ***1.5 to 1.6***
+:::note
+
+[Relevant version information and compatibility of apisix-helm-chart](https://github.com/apache/apisix-helm-chart#compatibility-matrix).
+
+If you use the `apisix-ingress-controller` chart, you need to focus on the configuration item [adminAPIVersion](https://github.com/apache/apisix-helm-chart/blob/apisix-ingress-controller-0.11.3/charts/apisix-ingress-controller/values.yaml#L134).
+
+:::
+
+You need to select the corresponding chart version according to the APISIX version as shown to install or upgrade:
+
+|Chart version| APISIX version | Values |
+|--| ---|--|
+|apisix-1.1.0| >= 3.0.0 | |
+|apisix-0.13.0| <= 2.15.x | |
+|apisix-ingress-controller-0.11.3| >= 3.0.0| adminAPIVersion=v3 |
+|apisix-ingress-controller-0.11.3| <= 2.15.x| |
+
+For `APISIX:3.x.x`, Use `apisix` chart to upgrade:
+
```sh
-helm upgrade apisix apisix/apisix *** # omit some configuration
+helm upgrade apisix apisix/apisix --version 1.1.0 *** # omit some configuration
+```
+
+For `APISIX:3.x.x`, use `apisix-ingress-controller` chart to upgrade:
+
+```sh
+helm upgrade apisix apisix/apisix-ingress-controller \
+ --version 0.11.3 \
+ --set config.apisix.adminAPIVersion=v3 # omit some configuration
```
#### ***1.4 to 1.5***
-The chart version corresponding to chart version 1.5:
+The chart version corresponding to `apisix-ingress-controller:1.5`:
* `apisix-0.11.3`
* `apisix-ingress-controller-0.10.1`
@@ -93,7 +137,7 @@
#### ***1.3 to 1.4***
-The chart version corresponding to chart version 1.4:
+The chart version corresponding to `apisix-ingress-controller:1.4`:
* `apisix-0.10.2`
* `apisix-ingress-controller-0.9.3`
@@ -105,21 +149,6 @@
Incompatible upgrade, need to change resources.
ApisixRoute `object(http[].backend)` has been removed in V2beta3 and needs to be converted to `array(http[].backends)`. It is recommended not to upgrade across major versions.
-## Version change
-
-### ***1.6.0***
-
-- No breaking changes in this release.
-
-### ***1.5.0***
-
-- CRD has been upgraded to the V2 version, and V2beta3 has been marked as deprecated.
-- `app_namespace` is deprecated, you can use `namespace_selector` instead.
-
-### ***1.4.0***
-
-- CRD unified upgrade to V2beta3, delete resource v2alpha1 and v1 versions
-
## Validate Compatibility
Apache APISIX Ingress project is a continuously actively developed project.
