mirror of https://github.com/hashicorp/consul
200 lines
12 KiB
Markdown
200 lines
12 KiB
Markdown
---
|
|
layout: docs
|
|
page_title: Upgrading Consul on Kubernetes Components
|
|
description: >-
|
|
Consul on Kubernetes relies on packages and binaries that have individual upgrade requirements. Learn how to update Helm configurations, Helm versions, Consul versions, and Consul agents, as well as how to determine what will change and its impact on your service mesh.
|
|
---
|
|
|
|
# Upgrading Consul on Kubernetes components
|
|
|
|
This topic describes considerations and strategies for upgrading Consul deployments running on Kubernetes clusters. In addition to upgrading the version of Consul, you may need to update your Helm chart or the release version of the Helm chart.
|
|
|
|
## Version-specific upgrade requirements
|
|
|
|
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.
|
|
|
|
If you configured your Consul agents to use [`ports.grpc_tls`](https://developer.hashicorp.com/consul/docs/agent/config/config-files#grpc_tls_port) instead of [`ports.grpc`](https://developer.hashicorp.com/consul/docs/agent/config/config-files#grpc_port) and you want to upgrade a multi-datacenter deployment with Consul servers running outside of the Kubernetes cluster to v1.0.0 or higher, set [`externalServers.tlsServerName`](/consul/docs/k8s/helm#v-externalservers-tlsservername) to `server.<primary-datacenter>.domain`.
|
|
|
|
## Upgrade types
|
|
|
|
We recommend updating Consul on Kubernetes when:
|
|
|
|
- You change your Helm configuration
|
|
- 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.
|
|
|
|
1. Determine your current installed chart version.
|
|
|
|
```shell-session
|
|
$ helm list --filter consul --namespace consul
|
|
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
|
|
consul consul 2 2022-02-02 21:49:45.647678 -0800 PST deployed consul-0.40.0 1.11.2
|
|
```
|
|
|
|
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` and make sure that 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
|
|
```
|
|
|
|
~> 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
|
|
|
|
You may wish to upgrade your Helm chart version to take advantage of new features and
|
|
bug fixes, or because you want to upgrade your Consul version and it requires a
|
|
certain Helm chart version.
|
|
|
|
1. Update your local Helm repository cache:
|
|
|
|
```shell-session
|
|
$ helm repo update
|
|
```
|
|
|
|
1. List all available versions. The console lists version `0.40.0` in the following example.
|
|
|
|
```shell-session hideClipboard
|
|
$ helm search repo hashicorp/consul --versions
|
|
NAME CHART VERSION APP VERSION DESCRIPTION
|
|
hashicorp/consul 0.40.0 1.11.2 Official HashiCorp Consul Chart
|
|
hashicorp/consul 0.39.0 1.11.1 Official HashiCorp Consul Chart
|
|
hashicorp/consul 0.38.0 1.10.4 Official HashiCorp Consul Chart
|
|
hashicorp/consul 0.37.0 1.10.4 Official HashiCorp Consul Chart
|
|
...
|
|
```
|
|
|
|
1. To determine which version you have installed, issue the following command:
|
|
|
|
```shell-session
|
|
$ helm list --filter consul --namespace consul
|
|
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
|
|
consul consul 2 2022-02-02 21:49:45.647678 -0800 PST deployed consul-0.39.0 1.11.1
|
|
```
|
|
|
|
In this example, version `0.39.0` (from `consul-k8s:0.39.0`) is being used.
|
|
|
|
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 [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
|
|
$ helm upgrade consul hashicorp/consul --namespace consul --version 0.40.0 --values /path/to/my/values.yaml
|
|
```
|
|
|
|
### Upgrade Consul version
|
|
|
|
If a new version of Consul is released, you need to perform a Helm upgrade
|
|
to update to the new version. Before you upgrade to a new version:
|
|
|
|
1. Read the [Upgrading Consul](/consul/docs/upgrading) documentation.
|
|
1. Read any [specific instructions](/consul/docs/upgrading/upgrade-specific) for the version you want to upgrade
|
|
to, as well as the Consul [changelog](https://github.com/hashicorp/consul/blob/main/CHANGELOG.md) for that version.
|
|
1. Read our [Compatibility Matrix](/consul/docs/k8s/compatibility) to ensure
|
|
your current Helm chart version supports this Consul version. If it does not,
|
|
you may need to also upgrade your Helm chart version at the same time.
|
|
1. Set `global.image` in your `values.yaml` to the desired version:
|
|
|
|
<CodeBlockConfig filename="values.yaml" highlight="2">
|
|
|
|
```yaml
|
|
global:
|
|
image: "hashicorp/consul:1.11.1"
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
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
|
|
$ helm list --filter consul --namespace consul
|
|
NAME NAMESPACE REVISION UPDATED STATUS CHART APP 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
|
|
```
|
|
|
|
~> 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.
|
|
|
|
## Consul server restarts and upgrades
|
|
|
|
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.
|
|
|
|
## Upgrading to Consul Dataplane
|
|
|
|
In earlier versions, Consul on Kubernetes used client agents in its deployments. As of v1.14.0, Consul uses [Consul Dataplane](/consul/docs/connect/dataplane/) in Kubernetes deployments instead of client agents.
|
|
|
|
If you upgrade Consul from a version that uses client agents to a version the uses dataplanes, complete the following steps to upgrade your deployment safely and without downtime.
|
|
|
|
1. If ACLs are enabled, you must first upgrade to consul-k8s 0.49.8 or above. These versions expose the setting `connectInject.prepareDataplanesUpgrade`
|
|
which is required for no-downtime upgrades when ACLs are enabled.
|
|
|
|
Set `connectInject.prepareDataplanesUpgrade` to `true` and then perform the upgrade to 0.49.8 or above (whichever is the latest in the 0.49.x series)
|
|
|
|
```yaml filename="values.yaml"
|
|
connectInject:
|
|
prepareDataplanesUpgrade: true
|
|
```
|
|
|
|
1. Consul dataplanes disables Consul clients by default, but during an upgrade you need to ensure Consul clients continue to run. Edit your Helm chart configuration and set the [`client.enabled`](/consul/docs/k8s/helm#v-client-enabled) field to `true` and specify an action for Consul to take during the upgrade process in the [`client.updateStrategy`](/consul/docs/k8s/helm#v-client-updatestrategy) field:
|
|
|
|
```yaml filename="values.yaml"
|
|
client:
|
|
enabled: true
|
|
updateStrategy: |
|
|
type: OnDelete
|
|
```
|
|
|
|
1. Follow our [recommended procedures to upgrade servers](#upgrade-consul-servers) on Kubernetes deployments to upgrade Helm values for the new version of Consul. The latest version of consul-k8s components may be in a CrashLoopBackoff state during the performance of the server upgrade from versions <1.14.x until all Consul servers are on versions >=1.14.x. Components in CrashLoopBackoff will not negatively affect the cluster because older versioned components will still be operating. Once all servers have been fully upgraded, the latest consul-k8s components will automatically restore from CrashLoopBackoff and older component versions will be spun down.
|
|
|
|
1. Run `kubectl rollout restart` to restart your service mesh applications. Restarting service mesh application causes Kubernetes to re-inject them with the webhook for dataplanes.
|
|
|
|
1. Restart all gateways in your service mesh.
|
|
|
|
1. Now that all services and gateways are using Consul dataplanes, disable client agents in your Helm chart by deleting the `client` stanza or setting `client.enabled` to `false` and running a `consul-k8s` or Helm upgrade.
|
|
|
|
1. If ACLs are enabled, outdated ACL tokens will persist a result of the upgrade. You can manually delete the tokens to declutter your Consul environment.
|
|
|
|
Outdated connect-injector tokens have the following description: `token created via login: {"component":"connect-injector"}`. Do not delete
|
|
the tokens that have a description where `pod` is a key, for example `token created via login: {"component":"connect-injector","pod":"default/consul-connect-injector-576b65747c-9547x"}`). The dataplane-enabled connect inject pods use these tokens.
|
|
|
|
You can also review the creation date for the tokens and only delete the injector tokens created before your upgrade, but do not delete all old tokens without considering if they are still in use. Some tokens, such as the server tokens, are still necessary.
|
|
|
|
## Configuring TLS on an existing cluster
|
|
|
|
If you already have a Consul cluster deployed on Kubernetes and
|
|
would like to turn on TLS for internal Consul communication,
|
|
refer to [Configuring TLS on an Existing Cluster](/consul/docs/k8s/operations/tls-on-existing-cluster).
|