mirror of https://github.com/hashicorp/consul
246 lines
10 KiB
Markdown
246 lines
10 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
|
|
|
|
## 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.
|
|
|
|
### 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
|
|
$ 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`:
|
|
|
|
```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.
|
|
|
|
### 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. Here you can observe that the latest version of `0.40.0`.
|
|
|
|
```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.
|
|
|
|
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:
|
|
|
|
```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
|
|
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: consul:1.11.2
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
2. Determine the version of your exisiting 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
|
|
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. 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 redploying 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
|
|
|
|
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. Before you upgrade, edit your Helm chart to enable Consul client agents by setting `client.enabled` and `client.updateStrategy`:
|
|
|
|
```yaml filename="values.yaml"
|
|
client:
|
|
enabled: true
|
|
updateStrategy: |
|
|
type: OnDelete
|
|
```
|
|
|
|
1. Add `consul.hashicorp.com/consul-k8s-version: 1.0.0` to the annotations for each pod you upgrade.
|
|
|
|
1. Follow our [recommended procedures to upgrade servers](#upgrading-consul-servers) on Kubernetes deployments to upgrade Helm values for the new version of Consul.
|
|
|
|
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. Disable client agents in your Helm chart by deleting the `client` stanza or setting `client.enabled` to `false`.
|
|
|
|
## 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).
|