[apisix-ingress-controller] branch master updated: doc: update upgrade guide (#1479)

[zh...@apache.org]

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 de9f84fc doc: update upgrade guide (#1479)
de9f84fc is described below

commit de9f84fce92e9ad26d487ccafa4bb7e800176776
Author: Xin Rong <al...@gmail.com>
AuthorDate: Wed Dec 7 14:05:13 2022 +0800

    doc: update upgrade guide (#1479)
---
 docs/en/latest/upgrade.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)

diff --git a/docs/en/latest/upgrade.md b/docs/en/latest/upgrade.md
index 881ba5ac..eb3fd6d8 100644
--- a/docs/en/latest/upgrade.md
+++ b/docs/en/latest/upgrade.md
@@ -21,6 +21,105 @@ title: Upgrade Guide
 #
 -->
 
+## 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.
+
+### Operating Step
+
+1. Update Helm repo
+
+Before upgrading, you need to update the helm repo to ensure that the resources in the repo are up to date.
+
+```sh
+helm repo update
+```
+
+2. Upgrade CRDs
+
+When the CRD exists, Helm Chart will not automatically update the CRD when upgrading or installing, so you need to update the CRD resource yourself
+
+- Using Helm (Helm version >= 3.7.0)
+
+```sh
+helm show crds apisix/apisix-ingress-controller | kubectl apply -f -
+```
+
+> If the Helm version does not support it, you need to obtain it from the [apisix-helm-chart](https://github.com/apache/apisix-helm-chart) repository.
+> 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
+> ```
+
+3. UpgradeAPISIX 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`.
+
+```sh
+helm upgrade apisix apisix/apisix \
+  --set gateway.type=NodePort \
+  --set ingress-controller.enabled=true \
+  --namespace ingress-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***
+
+```sh
+helm upgrade apisix apisix/apisix *** # omit some configuration
+```
+
+#### ***1.4 to 1.5***
+
+The chart version corresponding to chart version 1.5:
+
+* `apisix-0.11.3`
+* `apisix-ingress-controller-0.10.1`
+
+```sh
+helm upgrade apisix apisix/apisix --version 0.11.3 ***  # omit some configuration
+```
+
+### Incompatible upgrade
+
+#### ***1.3 to 1.4***
+
+The chart version corresponding to chart version 1.4:
+
+* `apisix-0.10.2`
+* `apisix-ingress-controller-0.9.3`
+
+```sh
+helm upgrade apisix apisix/apisix --version 0.10.2 ***  # omit some configuration
+```
+
+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.