23.2 23.1 22.3 22.2 22.1 21.11

Upgrade Redpanda in Kubernetes

To benefit from Redpanda’s new features and enhancements, use rolling upgrades to upgrade to the latest version. New features are available after all brokers (Pods) in the cluster are upgraded and restarted.

Redpanda platform version numbers follow the convention AB.C.D, where AB is the two digit year, C is the feature release, and D is the patch release. For example, version 22.3.1 indicates the first patch release on the third feature release of the year 2022. Patch releases include bug fixes and minor improvements, with no change to user-facing behavior. New and enhanced features are documented with each feature release.

  • New features are enabled after all brokers (nodes) in the cluster are upgraded. You can stop the upgrade process and roll back to the original version as long as you have not upgraded every broker and restarted the cluster.

  • Redpanda only supports upgrading one sequential feature release at a time. For example, you can upgrade from the 22.2 feature release to 22.3. You cannot skip feature releases.

  • Redpanda only supports downgrading between sequential patch releases. For example, you can downgrade from the 22.2.2 patch release to 22.2.1, but you cannot downgrade to 22.1.7.

  • With Remote Read Replicas, upgrade the Remote Read Replica cluster before upgrading the origin cluster. The Remote Read Replica cluster must run on the same version of Redpanda as the origin cluster, or just one feature release ahead of the origin cluster.

Prerequisites

  • A running Redpanda cluster.

  • jq for listing available versions.

  • An understanding of the impact of broker restarts on clients, node CPU, and any alerting systems you use.

Find a new version

Before you perform a rolling upgrade, you must find out which Redpanda version you are currently running, whether you can upgrade straight to the new version, and what’s changed since your original version.

  1. Find your current version:

    • TLS Enabled

    • TLS Disabled

    kubectl exec redpanda-0 -n redpanda -c redpanda -- \
  rpk redpanda admin brokers list \
    --admin-api-tls-enabled \
    --admin-api-tls-truststore <path-to-admin-api-ca-certificate> \
    --hosts <broker-url>:<admin-api-port>
    kubectl exec redpanda-0 -n redpanda -c redpanda -- \
  rpk redpanda admin brokers list \
    --hosts <broker-url>:<admin-api-port> \

    For all available flags, see the rpk redpanda admin brokers list command reference.

    Example output:

    The Redpanda version for each broker is listed under BROKER-VERSION.

    NODE-ID  BROKER-VERSION
0        v22.2.10
1        v22.2.10
2        v22.2.10

  2. Find the Redpanda version that’s used in the latest Redpanda Helm chart:

    helm repo update && \
helm show chart redpanda/redpanda | grep appVersion

    Example output:

    appVersion:	v22.2.10

    If your current version is more than one feature release behind the version in the latest Redpanda Helm chart, you must first upgrade to an intermediate version. To list all available versions:

    curl -s 'https://hub.docker.com/v2/repositories/redpandadata/redpanda/tags/?ordering=last_updated&page=1&page_size=50' | jq -r '.results[].name'

  3. Check the release notes to find information about what has changed between Redpanda versions.

Impact of broker restarts

When brokers restart, clients may experience higher latency, nodes may experience CPU spikes when the broker becomes available again, and you may receive alerts about under-replicated partitions. Topics that weren’t using replication (that is, topics that had replication.factor=1) will be unavailable.

Temporary increase in latency on clients (producers and consumers)

When you restart one or more brokers in a cluster, clients (consumers and producers) may experience higher latency due to partition leadership reassignment. Because clients must communicate with the leader of a partition, they may send a request to a broker whose leadership has been transferred, and receive NOT_LEADER_FOR_PARTITION. In this case, clients must request metadata from the cluster to find out the address of the new leader. Clients refresh their metadata periodically, or when the client receives some retryable errors that indicate that the metadata may be stale. For example:

  1. Broker A shuts down.

  2. Client sends a request to broker A, and receives NOT_LEADER_FOR_PARTITION.

  3. Client requests metadata, and learns that the new leader is broker B.

  4. Client sends the request to broker B.

CPU spikes upon broker restart

When a restarted broker becomes available again, you may see your nodes' CPU usage increase temporarily. This temporary increase in CPU usage is due to the cluster rebalancing the partition replicas.

Under-replicated partitions

When a broker is in maintenance mode, Redpanda continues to replicate updates to that broker. When a broker is taken offline during a restart, partitions with replicas on the broker could become out of sync until it is brought back online. Once the broker is available again, data is copied to its under-replicated replicas until all affected partitions are in sync with the partition leader.

Perform a rolling upgrade

A rolling upgrade involves putting a broker into maintenance mode, upgrading the broker, taking the broker out of maintenance mode, and then repeating the process on the next broker in the cluster. Placing brokers into maintenance mode ensures a smooth upgrade of your cluster while reducing the risk of interruption or degradation in service.

When a broker is placed into maintenance mode, it reassigns its partition leadership to other brokers for all topics that have a replication factor greater than one. Reassigning partition leadership involves draining leadership from the broker and transferring that leadership to another broker. If you have topics with replication.factor=1 and sufficient disk space, Redpanda Data recommends temporarily increasing the replication factor. This can help limit outages for these topics during the rolling upgrade. Do this before the upgrade to ensure there’s time for the data to replicate to other brokers. For details, see Change topic replication factor.

To perform a rolling upgrade:

  1. Deploy an upgraded StatefulSet with your desired Redpanda version.

  2. Upgrade and restart the brokers separately, one after the other.

Redpanda Data does not recommend using the kubectl rollout restart command to perform rolling upgrades. Although the chart’s preStop lifecycle hook puts the broker into maintenance mode before a Pod is deleted, the terminationGracePeriod may not be long enough to allow maintenance mode to finish. If maintenance mode does not finish before the Pod is deleted, you may lose data. After the terminationGracePeriod, the container is forcefully stopped using a SIGKILL command.

It can be a challenge to determine the necessary value for the terminationGracePeriod. In common cases, 30 seconds should be sufficient. For large clusters, 90 seconds should be sufficient. You can test different values in a development environment. To configure the terminationGracePeriod, use the statefulset.terminationGracePeriodSeconds setting.

Deploy an upgraded StatefulSet

To deploy an upgraded StatefulSet, you need to delete the existing StatefulSet, then upgrade the Redpanda Helm chart deployment with your desired Redpanda version.

  1. Delete the existing StatefulSet, but leave the Pods running:

    kubectl delete statefulset redpanda --cascade=orphan -n redpanda

  2. Upgrade the Redpanda version by overriding the image.tag setting. Replace <new-version> with a valid version tag.

    helm upgrade --install redpanda redpanda/redpanda \
  --namespace redpanda \
  --create-namespace \
  --set image.tag=<new-version> --set statefulset.updateStrategy.type=OnDelete

    Make sure to include all your configuration overrides in the helm upgrade command. Otherwise, the upgrade may fail. For example, if you already enabled SASL, include the same SASL overrides.

    Do not use the --reuse-values flag, otherwise Helm won’t include any new values from the upgraded chart.

The statefulset.updateStrategy.type=OnDelete setting stops the StatefulSet from upgrading all the Pods automatically. Changing the upgradeStrategy to OnDelete allows you to keep the existing Pods running and upgrade each broker separately. For more details, see the Kubernetes documentation.

To use the Redpanda version in the latest version of the Redpanda Helm chart, set image.tag to "" (empty string).

Upgrade and restart the brokers

To upgrade the Redpanda brokers, you must do the following to each broker, one at a time:

  1. Place the broker into maintenance mode.

  2. Wait for maintenance mode to finish.

  3. Delete the Pod that the broker was running in.

Before placing a broker into maintenance mode, you may want to temporarily disable or ignore alerts related to under-replicated partitions. When a broker is taken offline during a restart, replicas can become under-replicated.

  1. Select a broker that has not been upgraded yet and place it into maintenance mode.

    In this example, the command is executed on a Pod called redpanda-0 in the redpanda namespace. The ordinal of the StatefulSet replica, 0 in this example, is the same as the broker’s ID. This ID is used to enable maintenance mode on the broker: rpk cluster maintenance enable 0.

    • TLS Enabled

    • TLS Disabled

    kubectl exec redpanda-0 -n redpanda -c redpanda -- \
  rpk cluster maintenance enable 0 --wait \
    --admin-api-tls-enabled \
    --admin-api-tls-truststore <path-to-admin-api-ca-certificate> \
    --api-urls <broker-url>:<admin-api-port>
    kubectl exec redpanda-0 -n redpanda -c redpanda -- \
  rpk cluster maintenance enable 0 --wait \
    --api-urls <broker-url>:<admin-api-port> \

    The --wait flag ensures that the cluster is healthy before putting the broker into maintenance mode.

    The draining process won’t start until the cluster is healthy. The amount of time it takes to drain a broker and reassign partition leadership depends on the number of partitions and how healthy the cluster is. For healthy clusters, draining leadership should take less than a minute. If the cluster is unhealthy, such as when a follower is not in sync with the leader, then draining the broker can take even longer.

    Example output:

    NODE-ID  DRAINING  FINISHED  ERRORS  PARTITIONS  ELIGIBLE  TRANSFERRING  FAILED
0        true      true      false   1           0         1             0

  2. Wait until the cluster is healthy before continuing:

    • TLS Enabled

    • TLS Disabled

    kubectl exec redpanda-0 -n redpanda -c redpanda -- \
  rpk cluster health \
    --admin-api-tls-enabled \
    --admin-api-tls-truststore <path-to-admin-api-ca-certificate> \
    --api-urls <broker-url>:<admin-api-port>
    kubectl exec redpanda-0 -n redpanda -c redpanda -- \
  rpk cluster health \
    --api-urls <broker-url>:<admin-api-port> \

    Example output:

    CLUSTER HEALTH OVERVIEW
=======================
Healthy:               true
Controller ID:         0
All nodes:             [0 2 1]
Nodes down:            []
Leaderless partitions: []

    You can also evaluate external metrics to determine cluster health. If the cluster has any issues, take the broker out of maintenance mode by running the following command before proceeding with other operations, such as decommissioning or retrying the rolling upgrade:

    rpk cluster maintenance disable <node-id>

  3. Delete the Pod in which the broker was running:

    kubectl delete pod redpanda-0 -n redpanda

  4. When the Pod restarts, make sure that it’s now running the upgraded version of Redpanda:

    • TLS Enabled

    • TLS Disabled

    kubectl exec redpanda-0 -n redpanda -c redpanda -- \
  rpk redpanda admin brokers list \
    --admin-api-tls-enabled \
    --admin-api-tls-truststore <path-to-admin-api-ca-certificate> \
    --hosts <broker-url>:<admin-api-port>
    kubectl exec redpanda-0 -n redpanda -c redpanda -- \
  rpk redpanda admin brokers list \
    --hosts <broker-url>:<admin-api-port> \

  5. Repeat this process for all the other brokers in the cluster.

Verify that the upgrade was successful

When you’ve upgraded all brokers, verify that the cluster is healthy. If the cluster is unhealthy, the upgrade may still be in progress. Try waiting a few moments, then run the command again.

  • TLS Enabled

  • TLS Disabled

kubectl exec redpanda-0 -n redpanda -c redpanda -- \
  rpk cluster health \
    --admin-api-tls-enabled \
    --admin-api-tls-truststore <path-to-admin-api-ca-certificate> \
    --api-urls <broker-url>:<admin-api-port>
kubectl exec redpanda-0 -n redpanda -c redpanda -- \
  rpk cluster health \
    --api-urls <broker-url>:<admin-api-port> \

Example output:

CLUSTER HEALTH OVERVIEW
=======================
Healthy:               true
Controller ID:         1
All nodes:             [2,1,0]
Nodes down:            []
Leaderless partitions: []

Rollbacks

If something does not go as planned during a rolling upgrade, you can roll back to the original version as long as you have not upgraded every broker. The StatefulSet uses the RollingUpdate strategy by default in statefulset.updateStrategy.type, which means all Pods in the StatefulSet are restarted in reverse-ordinal order. For details, see the Kubernetes documentation.

  1. Find the previous revision:

    helm history redpanda -n redpanda

    Example output

    REVISION	UPDATED                 	STATUS    	CHART          	APP VERSION	DESCRIPTION
1       	Fri Mar  3 15:16:24 year	superseded	redpanda-2.12.2	v22.3.13   	Install complete
2       	Fri Mar  3 15:19:41 year	deployed	  redpanda-2.12.2	v22.3.13   	Upgrade complete

  2. Roll back to the previous revision:

    helm rollback redpanda <previous-revision> -n redpanda

  3. Verify that the cluster is healthy. If the cluster is unhealthy, the upgrade may still be in progress. Try waiting a few moments, then run the command again.

    • TLS Enabled

    • TLS Disabled

    kubectl exec redpanda-0 -n redpanda -c redpanda -- \
  rpk cluster health \
    --admin-api-tls-enabled \
    --admin-api-tls-truststore <path-to-admin-api-ca-certificate> \
    --api-urls <broker-url>:<admin-api-port>
    kubectl exec redpanda-0 -n redpanda -c redpanda -- \
  rpk cluster health \
    --api-urls <broker-url>:<admin-api-port> \

    Example output:

    CLUSTER HEALTH OVERVIEW
=======================
Healthy:               true
Controller ID:         1
All nodes:             [2,1,0]
Nodes down:            []
Leaderless partitions: []

Suggested reading

Set up a real-time dashboard to monitor your cluster health, see Monitor Redpanda.