Upgrade Dapr on a Kubernetes cluster

Follow these steps to upgrade Dapr on Kubernetes and ensure a smooth upgrade.

You can upgrade the Dapr control plane on a Kubernetes cluster using either the Dapr CLI or Helm.

Note

Refer to the Dapr version policy for guidance on Dapr’s upgrade path.

Upgrade using the Dapr CLI

You can upgrade Dapr using the Dapr CLI.

Prerequisites

Upgrade existing cluster to 1.12.0

  1. dapr upgrade -k --runtime-version=1.12.0

You can provide all the available Helm chart configurations using the Dapr CLI.

Troubleshoot upgrading via the CLI

There is a known issue running upgrades on clusters that may have previously had a version prior to 1.0.0-rc.2 installed on a cluster.

While this issue is uncommon, a few upgrade path edge cases may leave an incompatible CustomResourceDefinition installed on your cluster. If this is your scenario, you may see an error message like the following:

  1. Failed to upgrade Dapr: Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply
  2. The CustomResourceDefinition "configurations.dapr.io" is invalid: spec.preserveUnknownFields: Invalid value: true: must be false in order to use defaults in the schema

Solution

  1. Run the following command to upgrade the CustomResourceDefinition to a compatible version:

    1. kubectl replace -f https://raw.githubusercontent.com/dapr/dapr/5a15b3e0f093d2d0938b12f144c7047474a290fe/charts/dapr/crds/configuration.yaml
  2. Proceed with the dapr upgrade --runtime-version 1.12.0 -k command.

Upgrade using Helm

You can upgrade Dapr using a Helm v3 chart.

Important: The latest Dapr Helm chart no longer supports Helm v2. Migrate from Helm v2 to Helm v3.

Prerequisites

Upgrade existing cluster to 1.12.0

As of version 1.0.0 onwards, existing certificate values will automatically be reused when upgrading Dapr using Helm.

Note Helm does not handle upgrading resources, so you need to perform that manually. Resources are backward-compatible and should only be installed forward.

  1. Upgrade Dapr to version 1.12.0:

    1. kubectl replace -f https://raw.githubusercontent.com/dapr/dapr/v1.12.0/charts/dapr/crds/components.yaml
    2. kubectl replace -f https://raw.githubusercontent.com/dapr/dapr/v1.12.0/charts/dapr/crds/configuration.yaml
    3. kubectl replace -f https://raw.githubusercontent.com/dapr/dapr/v1.12.0/charts/dapr/crds/subscription.yaml
    4. kubectl apply -f https://raw.githubusercontent.com/dapr/dapr/v1.12.0/charts/dapr/crds/resiliency.yaml
    5. kubectl apply -f https://raw.githubusercontent.com/dapr/dapr/v1.12.0/charts/dapr/crds/httpendpoints.yaml
    1. helm repo update
    1. helm upgrade dapr dapr/dapr --version 1.12.0 --namespace dapr-system --wait

    If you’re using a values file, remember to add the --values option when running the upgrade command.*

  2. Ensure all pods are running:

    1. kubectl get pods -n dapr-system -w
    2. NAME READY STATUS RESTARTS AGE
    3. dapr-dashboard-69f5c5c867-mqhg4 1/1 Running 0 42s
    4. dapr-operator-5cdd6b7f9c-9sl7g 1/1 Running 0 41s
    5. dapr-placement-server-0 1/1 Running 0 41s
    6. dapr-sentry-84565c747b-7bh8h 1/1 Running 0 35s
    7. dapr-sidecar-injector-68f868668f-6xnbt 1/1 Running 0 41s
  3. Restart your application deployments to update the Dapr runtime:

    1. kubectl rollout restart deploy/<DEPLOYMENT-NAME>

Upgrade existing Dapr deployment to enable high availability mode

Enable high availability mode in an existing Dapr deployment with a few additional steps.

Last modified October 12, 2023: Update config.toml (#3826) (0ffc2e7)