This is an automated email from the ASF dual-hosted git repository.
zhangjintao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-ingress-controller.git
The following commit(s) were added to refs/heads/master by this push:
new 4c0535ba doc: update 1.6 upgrade guide (#1592)
4c0535ba is described below
commit 4c0535ba929c64ed9f9ac603300156879fe79e26
Author: Xin Rong <[email protected]>
AuthorDate: Tue Jan 31 13:43:28 2023 +0800
doc: update 1.6 upgrade guide (#1592)
Co-authored-by: rongxin <[email protected]>
Co-authored-by: Navendu Pottekkat <[email protected]>
---
docs/en/latest/upgrade.md | 81 ++++++++++++++++++++++++++++++++---------------
1 file changed, 55 insertions(+), 26 deletions(-)
diff --git a/docs/en/latest/upgrade.md b/docs/en/latest/upgrade.md
index eb3fd6d8..130b28d9 100644
--- a/docs/en/latest/upgrade.md
+++ b/docs/en/latest/upgrade.md
@@ -21,9 +21,30 @@ title: Upgrade Guide
#
-->
+## 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 @@ helm show crds apisix/apisix-ingress-controller | kubectl
apply -f -
> 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 @@ helm upgrade apisix apisix/apisix \
--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 @@ helm upgrade apisix apisix/apisix --version 0.11.3 *** #
omit some configuratio
#### ***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 @@ helm upgrade apisix apisix/apisix --version 0.10.2 *** #
omit some configuratio
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.
