status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: update k8s upgrade instructions (#20263) 

* docs: update k8s upgrade instructions

With https://github.com/hashicorp/consul-k8s/pull/3000 merged, users can
upgrade their k8s installs using a regular helm upgrade since the
upgrade is now stable.

Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
This commit is contained in:
Luke Kysow 2024-01-18 15:18:50 -08:00 committed by GitHub
parent 59cb12c798
commit 0cb64ccfc8
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 30 additions and 102 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

132
website/content/docs/k8s/upgrade/index.mdx
View File

@ -11,7 +11,7 @@ This topic describes considerations and strategies for upgrading Consul deployme
## Version-specific upgrade requirements ## Version-specific upgrade requirements
As of Consul v1.14.0, Kubernetes deployments use [Consul Dataplane](/consul/docs/connect/dataplane) instead of client agents. If you upgrade Consul from a version that uses client agents to a version that uses dataplanes, you must follow specific steps to update your Helm chart and remove client agents from the existing deployment. Refer to [Upgrading to Consul Dataplane](/consul/docs/k8s/upgrade#upgrading-to-consul-dataplane) for more information. As of Consul v1.14.0 and the corresponding Helm chart version v1.0.0, Kubernetes deployments use [Consul Dataplane](/consul/docs/connect/dataplane) instead of client agents. If you upgrade Consul from a version that uses client agents to a version that uses dataplanes, you must follow specific steps to update your Helm chart and remove client agents from the existing deployment. Refer to [Upgrading to Consul Dataplane](/consul/docs/k8s/upgrade#upgrading-to-consul-dataplane) for more information.
The v1.0.0 release of the Consul on Kubernetes Helm chart also introduced a change to the [`externalServers[].hosts` parameter](/consul/docs/k8s/helm#v-externalservers-hosts). Previously, you were able to enter a provider lookup as a string in this field. Now, you must include `exec=` at the start of a string containing a provider lookup. Otherwise, the string is treated as a DNS name. Refer to the [`go-netaddrs`](https://github.com/hashicorp/go-netaddrs) library and command line tool for more information. The v1.0.0 release of the Consul on Kubernetes Helm chart also introduced a change to the [`externalServers[].hosts` parameter](/consul/docs/k8s/helm#v-externalservers-hosts). Previously, you were able to enter a provider lookup as a string in this field. Now, you must include `exec=` at the start of a string containing a provider lookup. Otherwise, the string is treated as a DNS name. Refer to the [`go-netaddrs`](https://github.com/hashicorp/go-netaddrs) library and command line tool for more information.
@ -23,13 +23,13 @@ We recommend updating Consul on Kubernetes when:
- A new Helm chart is released - A new Helm chart is released
- You want to upgrade your Consul version - You want to upgrade your Consul version
The upgrade procedure you use depends on the type of upgrade you are performing.
### Helm configuration changes ### Helm configuration changes
If you make a change to your Helm values file, you need to perform a `helm upgrade` If you make a change to your Helm values file, you need to perform a `helm upgrade`
for those changes to take effect. for those changes to take effect.
For example, if you installed Consul with `connectInject.enabled: false` and you want to change its value to `true`:
1. Determine your current installed chart version. 1. Determine your current installed chart version.
```shell-session ```shell-session
@ -40,16 +40,13 @@ For example, if you installed Consul with `connectInject.enabled: false` and you
In this example, version `0.40.0` (from `consul-k8s:0.40.0`) is being used, and Consul on Kubernetes is installed in the `consul` namespace. In this example, version `0.40.0` (from `consul-k8s:0.40.0`) is being used, and Consul on Kubernetes is installed in the `consul` namespace.
1. Perform a `helm upgrade`: 1. Perform a `helm upgrade` and make sure that you specify the current chart version:
```shell-session ```shell-session
$ helm upgrade consul hashicorp/consul --namespace consul --version 0.40.0 --values /path/to/my/values.yaml $ helm upgrade consul hashicorp/consul --namespace consul --version 0.40.0 --values /path/to/my/values.yaml
``` ```
**Before performing the upgrade, be sure you read the other sections on this page, ~> Note: If you don't pass the `--version` flag when upgrading a Helm chart, Helm uses the most up-to-date version of the chart in its local cache, which may result in an unintended version upgrade.
continuing at [Determine scope of changes](#determine-scope-of-changes).**
~> Note: You should always set the `--version` flag when upgrading Helm. Otherwise, Helm uses the most up-to-date version in its local cache, which may result in an unintended upgrade.
### Upgrade Helm chart version ### Upgrade Helm chart version
@ -63,7 +60,7 @@ certain Helm chart version.
$ helm repo update $ helm repo update
``` ```
1. List all available versions. Here you can observe that the latest version of `0.40.0`. 1. List all available versions. The console lists version `0.40.0` in the following example.
```shell-session hideClipboard ```shell-session hideClipboard
$ helm search repo hashicorp/consul --versions $ helm search repo hashicorp/consul --versions
@ -85,19 +82,27 @@ certain Helm chart version.
In this example, version `0.39.0` (from `consul-k8s:0.39.0`) is being used. In this example, version `0.39.0` (from `consul-k8s:0.39.0`) is being used.
If you want to upgrade to the latest `0.40.0` version, use the following procedure:
1. Check the changelog for any breaking changes from that version and any versions in between: [CHANGELOG.md](https://github.com/hashicorp/consul-k8s/blob/main/CHANGELOG.md). 1. Check the changelog for any breaking changes from that version and any versions in between: [CHANGELOG.md](https://github.com/hashicorp/consul-k8s/blob/main/CHANGELOG.md).
1. Upgrade by performing a `helm upgrade` with the `--version` flag: 1. Check the [Consul on Kubernetes Version Compatibility](/consul/docs/k8s/compatibility) matrix. Each 1.x version of
the chart corresponds to a specific 1.x version of Consul. You may need to upgrade your Consul version to match the
chart version you want to upgrade to. For example, chart version `1.3.1` must be used with Consul version `1.17.x`.
To set the Consul version, set `global.image` in your `values.yaml` file, for example:
```
global:
image: "hashicorp/consul:1.17.5"
```
You can leave the `global.image` value unset to use the latest supported version of Consul.
version automatically.
1. Upgrade by performing a `helm upgrade` with the `--version` flag set to the version you want to upgrade to:
```shell-session ```shell-session
$ helm upgrade consul hashicorp/consul --namespace consul --version 0.40.0 --values /path/to/my/values.yaml $ helm upgrade consul hashicorp/consul --namespace consul --version 0.40.0 --values /path/to/my/values.yaml
``` ```
**Before performing the upgrade, be sure you've read the other sections on this page,
continuing at [Determine scope of changes](#determine-scope-of-changes).**
### Upgrade Consul version ### Upgrade Consul version
If a new version of Consul is released, you need to perform a Helm upgrade If a new version of Consul is released, you need to perform a Helm upgrade
@ -115,12 +120,12 @@ to update to the new version. Before you upgrade to a new version:
```yaml ```yaml
global: global:
image: consul:1.11.2 image: "hashicorp/consul:1.11.1"
``` ```
</CodeBlockConfig> </CodeBlockConfig>
2. Determine the version of your existing Helm installation. In this example, version `0.39.0` (from `consul-k8s:0.39.0`) is being used. 1. Determine the version of your existing Helm installation. The following example shows that version `0.39.0` is installed. The version is derived from the `CHART` column.
```shell-session ```shell-session
$ helm list --filter consul --namespace consul $ helm list --filter consul --namespace consul
@ -128,99 +133,22 @@ to update to the new version. Before you upgrade to a new version:
consul consul 2 2022-02-02 21:49:45.647678 -0800 PST deployed consul-0.39.0 1.11.1 consul consul 2 2022-02-02 21:49:45.647678 -0800 PST deployed consul-0.39.0 1.11.1
``` ```
1. Check the [Consul on Kubernetes Version Compatibility](/consul/docs/k8s/compatibility) matrix. Each 1.x version of
the chart corresponds to a specific 1.x version of Consul. You may need to upgrade your chart version to match the
Consul version you want to upgrade to.
1. Perform a `helm upgrade`: 1. Perform a `helm upgrade`:
```shell-session ```shell-session
$ helm upgrade consul hashicorp/consul --namespace consul --version 0.39.0 --values /path/to/my/values.yaml $ helm upgrade consul hashicorp/consul --namespace consul --version 0.39.0 --values /path/to/my/values.yaml
``` ```
**Before performing the upgrade, be sure you have read the other sections on this page, ~> Note: If you don't pass the `--version` flag when upgrading a Helm chart, Helm uses the most up-to-date version of the chart in its local cache, which may result in an unintended version upgrade.
continuing at [Determine scope of changes](#determine-scope-of-changes).**
~> Note: You should always set the `--version` flag when upgrading Helm. Otherwise, Helm uses the most up-to-date version in its local cache, which may result in an unintended upgrade. ## Consul server restarts and upgrades
## Determine scope of changes Note that for versions of Consul on Kubernetes prior to `1.4.0`, we recommended using the `server.updatePartition` setting to gradually upgrade
Consul servers. Refer to an older version of the documentation for instructions on upgrading to a version of the chart older than `v1.4.0`. Use the version drop-down at the top of this page to select a version older than or equal to `v1.17.0`. Consul documentation versions correspond to the Consul version in your chart, not the chart version, that contains the instructions.
Before upgrading, it is important to understand the changes that affect your
cluster. For example, you need to take more care if your upgrade results
in the Consul server StatefulSet being redeployed.
There is no built-in functionality in Helm that shows what a helm upgrade
changes. There is, however, a Helm plugin [helm-diff](https://github.com/databus23/helm-diff)
that can be used.
1. Install `helm-diff` with:
```shell-session
$ helm plugin install https://github.com/databus23/helm-diff
```
1. If you are updating your `values.yaml` file, do so now.
1. Take the same `helm upgrade` command you were planning to issue but perform `helm diff upgrade` instead of `helm upgrade`:
```shell-session
$ helm diff upgrade consul hashicorp/consul --namespace consul --version 0.40.0 --values /path/to/your/values.yaml
```
This command prints out the manifests that will be updated and their diffs.
1. To see only updated objects, add `| grep "has changed"`:
```shell-session
$ helm diff upgrade consul hashicorp/consul --namespace consul --version 0.40.0 --values /path/to/your/values.yaml |
grep "has changed"
```
1. Take specific note if `consul-server, StatefulSet` is listed, as it means your Consul server statefulset will be redeployed.
If your Consul server statefulset needs to be redeployed, follow the same pattern for upgrades as
on other platforms by redeploying servers one by one. Refer tp [Upgrading Consul](/consul/docs/upgrading) for more information.
If neither the server statefulset is not being redeployed,
then you can continue with the Helm upgrade without any specific sequence to follow.
## Upgrade Consul servers
Initiate the server upgrade:
1. Change the `global.image` value to the desired Consul version.
1. Set the `server.updatePartition` value to the number of server replicas. By default, there are 3 servers, so you would set this value to `3`.
1. Set the `updateStrategy` for clients to `OnDelete`.
<CodeBlockConfig filename="values.yaml">
```yaml
global:
image: 'consul:123.456'
server:
updatePartition: 3
```
</CodeBlockConfig>
The `updatePartition` value controls how many instances of the server
cluster are updated. Only instances with an index _greater than_ the
`updatePartition` value are updated (zero-indexed). Therefore, by setting
it equal to replicas, updates should not occur immediately.
1. Next, perform the upgrade:
```shell-session
$ helm upgrade consul hashicorp/consul --namespace consul --version <your-version> --values /path/to/your/values.yaml
```
This command does not cause the servers to redeploy, although the resource is updated. If
everything is stable, decrease the `updatePartition` value by one
and performing `helm upgrade` again. This will cause the first Consul server
to be stopped and restarted with the new image.
1. Wait until the Consul server cluster is healthy again (30s to a few minutes).
This can be confirmed by issuing `consul members` on one of the previous servers,
and ensuring that all servers are listed and are `alive`.
1. Decrease `updatePartition` by one and upgrade again. Continue until
`updatePartition` is `0`. At this point, you may remove the
`updatePartition` configuration. Your server upgrade is complete.
## Upgrading to Consul Dataplane ## Upgrading to Consul Dataplane