docs: add 0.9.1 upgrade guides and update related commands in 0.9.0 (#…

…8262)

docs/user_docs/upgrade/faq.md

@@ -0,0 +1,109 @@
+---
+title: FAQ
+description: Upgrade, faq, tips and notes
+keywords: [upgrade, FAQ]
+sidebar_position: 3
+sidebar_label: FAQ
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# FAQ
+
+This guide addresses common questions and issues that may arise when upgrading KubeBlocks, ensuring a smooth and efficient process.
+
+## Manually mark Addons
+
+To prevent an Addon from being deleted during a KubeBlocks upgrade via `kbcli` or Helm, add the `"helm.sh/resource-policy": "keep"` annotation.
+
+### View the Addon annotation
+
+Run the command below to view the annotations of Addons.
+
+```bash
+kubectl get addon -o json | jq '.items[] | {name: .metadata.name, annotations: .metadata.annotations}'
+```
+
+### Manually add an annotation for Addons
+
+Replace `-l app.kubernetes.io/name=kubeblocks` with your actual filter and run the command below to add an annotation.
+
+```bash
+kubectl annotate addons.extensions.kubeblocks.io -l app.kubernetes.io/name=kubeblocks helm.sh/resource-policy=keep
+```
+
+If you want to add the annotation for a specified Addon, replace `{addonName}` with the actual Addon name and run the command below.
+
+```bash
+kubectl annotate addons.extensions.kubeblocks.io {addonName} helm.sh/resource-policy=keep
+```
+
+If you want to check whether the annotation for an Addon was added successfully, replace `{addonName}` with the actual Addon name and run the command below.
+
+```bash
+kubectl get addon {addonName} -o json | jq '{name: .metadata.name, annotations: .metadata.annotations}'
+```
+
+## Fix "cannot patch 'kubeblocks-dataprotection' with kind Deployment" error
+
+When upgrading KubeBlocks to v0.8.x/v0.9.0, you might encounter the following error:
+
+```bash
+Error: UPGRADE FAILED: cannot patch "kubeblocks-dataprotection" with kind Deployment: Deployment.apps "kubeblocks-dataprotection" is invalid: spec.selector: Invalid value: v1.LabelSelector{MatchLabels:map[string]string{"app.kubernetes.io/component":"dataprotection", "app.kubernetes.io/instance":"kubeblocks", "app.kubernetes.io/name":"kubeblocks"}, MatchExpressions:[]v1.LabelSelectorRequirement(nil)}: field is immutable && cannot patch "kubeblocks" with kind Deployment: Deployment.apps "kubeblocks" is invalid: spec.selector: Invalid value: v1.LabelSelector{MatchLabels:map[string]string{"app.kubernetes.io/component":"apps", "app.kubernetes.io/instance":"kubeblocks", "app.kubernetes.io/name":"kubeblocks"}, MatchExpressions:[]v1.LabelSelectorRequirement(nil)}: field is immutable
+```
+
+This is due to label modifications of KubeBlocks and KubeBlocks-Dataprotection in KubeBlocks v0.9.1.
+
+To resolve the issue, manually delete the `kubeblocks` and `kubeblocks-dataprotection` deployments, then run helm upgrade to complete the upgrade to v0.9.1.
+
+```bash
+# Scale to 0 replica
+kubectl -n kb-system scale deployment kubeblocks --replicas 0
+kubectl -n kb-system scale deployment kubeblocks-dataprotection --replicas 0
+
+# Delete deployments
+kubectl delete -n kb-system deployments.apps kubeblocks kubeblocks-dataprotection
+```
+
+## Specify an image registry during KubeBlocks upgrade
+
+KubeBlocks v0.8.x uses `infracreate-registry.cn-zhangjiakou.cr.aliyuncs.com` and `docker.io` as image registries and KubeBlocks v0.9.x uses `apecloud-registry.cn-zhangjiakou.cr.aliyuncs.com` and `docker.io`.
+
+When upgrading KubeBlocks, you can override the default image registry by specifying the following parameters.
+
+<Tabs>
+
+<TabItem value="kbcli" label="kbcli" default>
+
+```bash
+kbcli kb upgrade --version 0.9.1 \ 
+  --set admissionWebhooks.enabled=true \
+  --set admissionWebhooks.ignoreReplicasCheck=true \
+  --set image.registry=docker.io \
+  --set dataProtection.image.registry=docker.io \
+  --set addonChartsImage.registry=docker.io
+```
+
+</TabItem>
+
+<TabItem value="Helm" label="Helm">
+
+```bash
+helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.9.1 \
+  --set admissionWebhooks.enabled=true \
+  --set admissionWebhooks.ignoreReplicasCheck=true \
+  --set image.registry=docker.io \
+  --set dataProtection.image.registry=docker.io \
+  --set addonChartsImage.registry=docker.io
+```
+
+</TabItem>
+
+</Tabs>
+
+Here is an introdution to the flags in the above command.
+
+- `--set image.registry=docker.io` specifies the KubeBlocks image registry.
+- `--set dataProtection.image.registry=docker.io` specifies the KubeBlocks-Dataprotection image registry.
+- `--set addonChartsImage.registry=docker.io` specifies Addon Charts image registry.

docs/user_docs/upgrade/upgrade with helm/upgrade-kubeblocks-to-0.8.md → docs/user_docs/upgrade/upgrade-with-helm/upgrade-kubeblocks-to-0.8.md

@@ -2,7 +2,7 @@
 title: Upgrade to KubeBlocks v0.8
 description: Upgrade to KubeBlocks v0.8, operation, tips and notes
 keywords: [upgrade, 0.8]
-sidebar_position: 2
+sidebar_position: 3
 sidebar_label: Upgrade to KubeBlocks v0.8
 ---
 
@@ -72,3 +72,7 @@ helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.8.1 --set
 ```
 
 :::
+
+## FAQ
+
+Refer to the [FAQ](./../faq.md) to address common questions and issues that may arise when upgrading KubeBlocks. If your question isn't covered, you can [submit an issue](https://github.com/apecloud/kubeblocks/issues/new/choose) or [start a discussion](https://github.com/apecloud/kubeblocks/discussions) on upgrading in GitHub.