diff --git a/website/content/docs/k8s/upgrade/index.mdx b/website/content/docs/k8s/upgrade/index.mdx
index 26ef776e1b731..cc0fe6c511a31 100644
--- a/website/content/docs/k8s/upgrade/index.mdx
+++ b/website/content/docs/k8s/upgrade/index.mdx
@@ -11,7 +11,7 @@ This topic describes considerations and strategies for upgrading Consul deployme
## 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 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.
@@ -23,13 +23,13 @@ We recommend updating Consul on Kubernetes when:
- A new Helm chart is released
- You want to upgrade your Consul version
+The upgrade procedure you use depends on the type of upgrade you are performing.
+
### Helm configuration changes
If you make a change to your Helm values file, you need to perform a `helm upgrade`
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.
```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.
-1. Perform a `helm upgrade`:
+1. Perform a `helm upgrade` ensuring you specify the current chart version:
```shell-session
$ 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,
- 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.
+~> 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.
### Upgrade Helm chart version
@@ -63,7 +60,7 @@ certain Helm chart version.
$ 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. Here you can observe that the latest version is `0.40.0`.
```shell-session hideClipboard
$ 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.
-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. 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 may also wish to leave `global.image` unset in which case the Consul version will be set to the latest supported
+ version automatically.
+
+1. Upgrade by performing a `helm upgrade` with the `--version` flag of set to the version you wish to upgrade to:
```shell-session
$ 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
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
global:
- image: consul:1.11.2
+ image: "hashicorp/consul:1.11.1"
```
-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. In this example, version `0.39.0` (from `consul-k8s:0.39.0`) is being used.
```shell-session
$ helm list --filter consul --namespace consul
@@ -128,99 +133,24 @@ 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
```
+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`:
```shell-session
$ 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,
- 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.
-
-## Determine scope of changes
-
-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`.
-
-
-
- ```yaml
- global:
- image: 'consul:123.456'
- server:
- updatePartition: 3
- ```
-
-
-
- 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 --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.
+~> 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.
-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`.
+## Consul server restarts/upgrades
-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.
+-> *Note for older versions*: For versions of Consul on Kubernetes prior to `1.4.0`, we recommended using the `server.updatePartition` setting to slowly upgrade
+Consul servers. This is no longer necessary due to some changes we made to increase the stability of upgrades, but if you
+are upgrading a version of the chart older than `1.4.0`, use the version drop-down at the top of the page to select a version
+<= `1.17.0` (corresponding to the Consul version in your chart, not the chart version) which contains those instructions.
## Upgrading to Consul Dataplane