From deff2d8731886ff53b474451c2f6aa42736f9798 Mon Sep 17 00:00:00 2001 From: vankichi Date: Thu, 18 Aug 2022 10:41:47 +0900 Subject: [PATCH 1/4] :pencil: add upgrade document Signed-off-by: vankichi --- docs/user-guides/upgrade-cluster.md | 141 ++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 docs/user-guides/upgrade-cluster.md diff --git a/docs/user-guides/upgrade-cluster.md b/docs/user-guides/upgrade-cluster.md new file mode 100644 index 0000000000..693b82bd5b --- /dev/null +++ b/docs/user-guides/upgrade-cluster.md @@ -0,0 +1,141 @@ +# Upgrade Vald cluster + +Before this document, we recommend reading [the configuration document](../user-guides/configuration.md) first. + +## Update Configuration + +When you'd like to update the configuration for the Vald cluster, you need to edit your configuration file and apply it according to your deployment method. +Please refer to one of the sections below according to your deployment method. + +
+If each Vald Agent already has the indexes and uses the backup feature, please DO NOT edit the dimension and the distance type to avoid initContainer error.
+(Each Vald Agent will restore from backup data when backup when performing a rolling update) +
+ +
+The indexes will be clear when performing a rolling update if each Vald Agent already has the indexes and does not use the backup. +
+ +### Using Helm for deployment + +The configuration file is `values.yaml`. (https://helm.sh/docs/chart_template_guide/values_files/) + + +You can edit your `values.yaml` and update your Vald cluster by following steps: +1. Edit `values.yaml`. +1. Update with Helm command. + + ```bash + helm upgrade vald/vald --values + # e.g., helm upgrade vald vald/vald --values valeus.yaml + ``` + +### Using vald-helm-operator + +There are two configuration files: +- `vhor.yaml` for vald-helm-operator +- `vr.yaml` for the Vald cluster + +If you don't need to update the `vald-helm-operator`, please skip step.1 and step.2. +The Vald cluster will be updated by the following steps: +1. Edit `vhor.yaml`. +1. Apply `vhor.yaml`. + + ```bash + kubectl apply -f + # e.g., kubectl apply -f vhor.yaml + ``` + +1. Edit `vr.yaml`. +1. Apply `vr.yaml`. + + ```bash + kubectl apply -f + # e.g., kubectl apply -f vr.yaml + ``` + +## Upgrade Vald version + +We recommend using the latest Vald version. + +If your Vald cluster uses an old version and you'd like to upgrade the Vald version, you can upgrade by the following sections. +Please refer to one of the sections below according to your deployment method. + +
+When the upgrade request is applied, Kubernetes will perform a rolling update. +If your Vald cluster does not apply backup, the index will be cleared by a rolling update.
+In addition, if each Vald Agent already has the indexes and uses the backup feature, please DO NOT edit the dimension and the distance type to avoid initContainer error. +(Each Vald Agent will restore from backup data when backup when performing a rolling update) +
+ +### Using Helm for deployment + +Using the `Helm` command for the deployment of the Vald cluster, the upgrading steps are below. + +1. Update Helm repo + + ```bash + helm repo update https://vald.vdaas.org/charts + # e.g., helm repo update vald https://vald.vdaas.org/charts + ``` + +1. Edit `values.yaml` + - We recommend setting a specific version as an image tag. + + ```bash + vim values.yaml + --- + defaults: + ... + image: + tag: v1.5.6 # set a new version + ... + ``` + +1. Apply `values.yaml` + + ```bash + helm upgrade vald/vald --values + # e.g., helm upgrade vald vald/vald --values valeus.yaml + ``` + +### Using vald-helm-operator + +The upgrading steps are below if you use `vald-helm-operator` for the deployment. + +1. Upgrade CRDs + + ```bash + kubectl replace -f https://raw.githubusercontent.com/vdaas/vald//charts/vald-helm-operator/crds/valdrelease.yaml + kubectl replace -f https://raw.githubusercontent.com/vdaas/vald//charts/vald-helm-operator/crds/valdhelmoperatorrelease.yaml + ``` + +1. Update `vhor` + + ```bash + kubectl patch vhor vhor-release -p '{"spec":{"image":{"tag":""}}}' + ``` + + - Also, you can upgrade manually by editing `vhor.yaml` and applying it. + +1. Edit `vr.yaml` + - We recommend setting a specific version as an image tag. + + ```bash + vim vr.yaml + --- + ... + spec: + defaults: + ... + image: + tag: v1.5.6 # set a new version + ... + ``` + +1. Apply `vr.yaml` + + ```bash + kubectl apply -f + # e.g., kubectl apply -f vr.yaml + ``` From dba2e2cf966afdc798e85152ea13a0876d0d310b Mon Sep 17 00:00:00 2001 From: vankichi Date: Thu, 18 Aug 2022 10:46:48 +0900 Subject: [PATCH 2/4] :pencil: fix Signed-off-by: vankichi --- docs/user-guides/upgrade-cluster.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/user-guides/upgrade-cluster.md b/docs/user-guides/upgrade-cluster.md index 693b82bd5b..d86aace594 100644 --- a/docs/user-guides/upgrade-cluster.md +++ b/docs/user-guides/upgrade-cluster.md @@ -82,9 +82,7 @@ Using the `Helm` command for the deployment of the Vald cluster, the upgrading s 1. Edit `values.yaml` - We recommend setting a specific version as an image tag. - ```bash - vim values.yaml - --- + ```yaml defaults: ... image: @@ -121,9 +119,7 @@ The upgrading steps are below if you use `vald-helm-operator` for the deployment 1. Edit `vr.yaml` - We recommend setting a specific version as an image tag. - ```bash - vim vr.yaml - --- + ```yaml ... spec: defaults: From 57ca075d313a08f2985864a0d14fa32c7bac9284 Mon Sep 17 00:00:00 2001 From: Kiichiro YUKAWA Date: Tue, 23 Aug 2022 10:32:57 +0900 Subject: [PATCH 3/4] Update docs/user-guides/upgrade-cluster.md Co-authored-by: Kevin Diu --- docs/user-guides/upgrade-cluster.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guides/upgrade-cluster.md b/docs/user-guides/upgrade-cluster.md index d86aace594..9cbfca40ca 100644 --- a/docs/user-guides/upgrade-cluster.md +++ b/docs/user-guides/upgrade-cluster.md @@ -9,7 +9,7 @@ Please refer to one of the sections below according to your deployment method.
If each Vald Agent already has the indexes and uses the backup feature, please DO NOT edit the dimension and the distance type to avoid initContainer error.
-(Each Vald Agent will restore from backup data when backup when performing a rolling update) +(Each Vald Agent will restore from backup data when performing a rolling update)
From b8c355fa062ba5e8dcaf250c68ca142b4d10dcfb Mon Sep 17 00:00:00 2001 From: vankichi Date: Tue, 23 Aug 2022 11:44:45 +0900 Subject: [PATCH 4/4] :pencil: apply feedback Signed-off-by: vankichi --- docs/user-guides/upgrade-cluster.md | 126 +++++++++++++++------------- 1 file changed, 70 insertions(+), 56 deletions(-) diff --git a/docs/user-guides/upgrade-cluster.md b/docs/user-guides/upgrade-cluster.md index 9cbfca40ca..694a213213 100644 --- a/docs/user-guides/upgrade-cluster.md +++ b/docs/user-guides/upgrade-cluster.md @@ -13,46 +13,48 @@ If each Vald Agent already has the indexes and uses the backup feature, please D
-The indexes will be clear when performing a rolling update if each Vald Agent already has the indexes and does not use the backup. +The indexes will be clear when performing a rolling update if each Vald Agent already has the indexes and the backup feature disabled.
### Using Helm for deployment -The configuration file is `values.yaml`. (https://helm.sh/docs/chart_template_guide/values_files/) - +The configuration file is `values.yaml`. ([Helm Values](https://helm.sh/docs/chart_template_guide/values_files/)) You can edit your `values.yaml` and update your Vald cluster by following steps: + 1. Edit `values.yaml`. -1. Update with Helm command. +1. Update with Helm command. - ```bash - helm upgrade vald/vald --values - # e.g., helm upgrade vald vald/vald --values valeus.yaml - ``` + ```bash + helm upgrade vald/vald --values + # e.g., helm upgrade vald vald/vald --values valeus.yaml + ``` ### Using vald-helm-operator There are two configuration files: + - `vhor.yaml` for vald-helm-operator - `vr.yaml` for the Vald cluster If you don't need to update the `vald-helm-operator`, please skip step.1 and step.2. The Vald cluster will be updated by the following steps: + 1. Edit `vhor.yaml`. 1. Apply `vhor.yaml`. - ```bash - kubectl apply -f - # e.g., kubectl apply -f vhor.yaml - ``` + ```bash + kubectl apply -f + # e.g., kubectl apply -f vhor.yaml + ``` 1. Edit `vr.yaml`. 1. Apply `vr.yaml`. - ```bash - kubectl apply -f - # e.g., kubectl apply -f vr.yaml - ``` + ```bash + kubectl apply -f + # e.g., kubectl apply -f vr.yaml + ``` ## Upgrade Vald version @@ -64,7 +66,7 @@ Please refer to one of the sections below according to your deployment method.
When the upgrade request is applied, Kubernetes will perform a rolling update. If your Vald cluster does not apply backup, the index will be cleared by a rolling update.
-In addition, if each Vald Agent already has the indexes and uses the backup feature, please DO NOT edit the dimension and the distance type to avoid initContainer error. +In addition, if each Vald Agent already has the indexes and the backup feature enabled, please DO NOT edit the dimension and the distance type to avoid initContainer error. (Each Vald Agent will restore from backup data when backup when performing a rolling update)
@@ -72,30 +74,41 @@ In addition, if each Vald Agent already has the indexes and uses the backup feat Using the `Helm` command for the deployment of the Vald cluster, the upgrading steps are below. +
+Before upgrading, please confirm your Vald cluster version.
+If there is major or minor upgrading, the chart structure may have changed. +
+ +1. Verify vald repo in your helm repo + + ```bash + helm repo list + ``` + 1. Update Helm repo - ```bash - helm repo update https://vald.vdaas.org/charts - # e.g., helm repo update vald https://vald.vdaas.org/charts - ``` + ```bash + helm repo update + # e.g., helm repo update vald + ``` 1. Edit `values.yaml` - - We recommend setting a specific version as an image tag. - ```yaml - defaults: - ... - image: - tag: v1.5.6 # set a new version - ... - ``` + - We recommend setting a specific version as an image tag. + + ```yaml + defaults: + --- + image: + tag: v1.5.6 # set a new version + ``` 1. Apply `values.yaml` - ```bash - helm upgrade vald/vald --values - # e.g., helm upgrade vald vald/vald --values valeus.yaml - ``` + ```bash + helm upgrade vald/vald --values + # e.g., helm upgrade vald vald/vald --values valeus.yaml + ``` ### Using vald-helm-operator @@ -103,35 +116,36 @@ The upgrading steps are below if you use `vald-helm-operator` for the deployment 1. Upgrade CRDs - ```bash - kubectl replace -f https://raw.githubusercontent.com/vdaas/vald//charts/vald-helm-operator/crds/valdrelease.yaml - kubectl replace -f https://raw.githubusercontent.com/vdaas/vald//charts/vald-helm-operator/crds/valdhelmoperatorrelease.yaml - ``` + ```bash + kubectl replace -f https://raw.githubusercontent.com/vdaas/vald//charts/vald-helm-operator/crds/valdrelease.yaml + kubectl replace -f https://raw.githubusercontent.com/vdaas/vald//charts/vald-helm-operator/crds/valdhelmoperatorrelease.yaml + ``` 1. Update `vhor` - ```bash - kubectl patch vhor vhor-release -p '{"spec":{"image":{"tag":""}}}' - ``` + ```bash + kubectl patch vhor vhor-release -p '{"spec":{"image":{"tag":""}}}' + ``` - - Also, you can upgrade manually by editing `vhor.yaml` and applying it. + - Also, you can upgrade manually by editing `vhor.yaml` and applying it. 1. Edit `vr.yaml` - - We recommend setting a specific version as an image tag. - - ```yaml - ... - spec: - defaults: - ... - image: - tag: v1.5.6 # set a new version - ... - ``` + + - We recommend setting a specific version as an image tag. + + ```yaml + ... + spec: + defaults: + ... + image: + tag: v1.5.6 # set a new version + ... + ``` 1. Apply `vr.yaml` - ```bash - kubectl apply -f - # e.g., kubectl apply -f vr.yaml - ``` + ```bash + kubectl apply -f + # e.g., kubectl apply -f vr.yaml + ```