The documentation you are viewing is for Dapr v1.11 which is an older version of Dapr. For up-to-date documentation, see the latest version.

Deploy Dapr on a Kubernetes cluster

Follow these steps to deploy Dapr on Kubernetes.

When setting up Dapr on Kubernetes, you can use either the Dapr CLI or Helm.

Install Dapr on Kubernetes

Select your preferred installation method for Dapr on Kubernetes.


You can install Dapr on a Kubernetes cluster using the Dapr CLI.

Prerequisites

Installation options

You can install Dapr from an official Helm chart or a private chart, using a custom namespace, etc.

Install Dapr from an official Dapr Helm chart

The -k flag initializes Dapr on the Kubernetes cluster in your current context.

  1. Verify the correct “target” cluster is set by checking kubectl context (kubectl config get-contexts).

    • You can set a different context using kubectl config use-context <CONTEXT>.

  2. Initialize Dapr on your cluster with the following command:

    dapr init -k

    Expected output

    ⌛  Making the jump to hyperspace...

✅  Deploying the Dapr control plane to your cluster...
✅  Success! Dapr has been installed to namespace dapr-system. To verify, run "dapr status -k" in your terminal. To get started, go here: https://aka.ms/dapr-getting-started

  3. Run the dashboard:

    dapr dashboard -k

    If you installed Dapr in a non-default namespace, run:

    dapr dashboard -k -n <your-namespace>

Install Dapr from a private Dapr Helm chart

Installing Dapr from a private Helm chart can be helpful for when you:

  • Need more granular control of the Dapr Helm chart
  • Have a custom Dapr deployment
  • Pull Helm charts from trusted registries that are managed and maintained by your organization

Set the following parameters to allow dapr init -k to install Dapr images from the configured Helm repository.

export DAPR_HELM_REPO_URL="https://helm.custom-domain.com/dapr/dapr"
export DAPR_HELM_REPO_USERNAME="username_xxx"
export DAPR_HELM_REPO_PASSWORD="passwd_xxx"

Install in high availability mode

You can run Dapr with three replicas of each control plane pod in the dapr-system namespace for production scenarios.

dapr init -k --enable-ha=true

Install in custom namespace

The default namespace when initializing Dapr is dapr-system. You can override this with the -n flag.

dapr init -k -n mynamespace

Disable mTLS

Dapr is initialized by default with mTLS. You can disable it with:

dapr init -k --enable-mtls=false

Wait for the installation to complete

You can wait for the installation to complete its deployment with the --wait flag. The default timeout is 300s (5 min), but can be customized with the --timeout flag.

dapr init -k --wait --timeout 600

Uninstall Dapr on Kubernetes with CLI

Run the following command on your local machine to uninstall Dapr on your cluster:

dapr uninstall -k

You can install Dapr on Kubernetes using a Helm v3 chart.

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

Prerequisites

Add and install Dapr Helm chart

  1. Add the Helm repo and update:

    // Add the official Dapr Helm chart.
helm repo add dapr https://dapr.github.io/helm-charts/
// Or also add a private Dapr Helm chart.
helm repo add dapr http://helm.custom-domain.com/dapr/dapr/ \
   --username=xxx --password=xxx
helm repo update
// See which chart versions are available
helm search repo dapr --devel --versions

  2. Install the Dapr chart on your cluster in the dapr-system namespace.

    helm upgrade --install dapr dapr/dapr \
--version=1.11 \
--namespace dapr-system \
--create-namespace \
--wait

    To install in high availability mode:

    helm upgrade --install dapr dapr/dapr \
--version=1.11 \
--namespace dapr-system \
--create-namespace \
--set global.ha.enabled=true \
--wait

See Guidelines for production ready deployments on Kubernetes for more information on installing and upgrading Dapr using Helm.

(optional) Install the Dapr dashboard as part of the control plane

If you want to install the Dapr dashboard, use this Helm chart with the additional settings of your choice:

helm install dapr dapr/dapr-dashboard --namespace dapr-system

For example:

helm repo add dapr https://dapr.github.io/helm-charts/
helm repo update
kubectl create namespace dapr-system
# Install the Dapr dashboard
helm install dapr dapr/dapr-dashboard --namespace dapr-system

Verify installation

Once the installation is complete, verify that the dapr-operator, dapr-placement, dapr-sidecar-injector, and dapr-sentry pods are running in the dapr-system namespace:

kubectl get pods --namespace dapr-system

NAME                                     READY     STATUS    RESTARTS   AGE
dapr-dashboard-7bd6cbf5bf-xglsr          1/1       Running   0          40s
dapr-operator-7bd6cbf5bf-xglsr           1/1       Running   0          40s
dapr-placement-7f8f76778f-6vhl2          1/1       Running   0          40s
dapr-sidecar-injector-8555576b6f-29cqm   1/1       Running   0          40s
dapr-sentry-9435776c7f-8f7yd             1/1       Running   0          40s

Uninstall Dapr on Kubernetes

helm uninstall dapr --namespace dapr-system

More information

Use Mariner-based images

The default container images pulled on Kubernetes are based on distroless.

Alternatively, you can use Dapr container images based on Mariner 2 (minimal distroless). Mariner, officially known as CBL-Mariner, is a free and open-source Linux distribution and container base image maintained by Microsoft. For some Dapr users, leveraging container images based on Mariner can help you meet compliance requirements.

To use Mariner-based images for Dapr, you need to add -mariner to your Docker tags. For example, while ghcr.io/dapr/dapr:latest is the Docker image based on distroless, ghcr.io/dapr/dapr:latest-mariner is based on Mariner. Tags pinned to a specific version are also available, such as 1.11-mariner.


In the Dapr CLI, you can switch to using Mariner-based images with the --image-variant flag.

dapr init --image-variant mariner

With Kubernetes and Helm, you can use Mariner-based images by setting the global.tag option and adding -mariner. For example:

helm upgrade --install dapr dapr/dapr \
  --version=1.11 \
  --namespace dapr-system \
  --create-namespace \
  --set global.tag=1.11.3-mariner \
  --wait

Use the Dapr Kubernetes Operator

The Dapr Kubernetes Operator manages the lifecycle for Dapr and its components. The operator’s goal is to automate the tasks required when operating a Dapr running in Kubernetes mode.

The operator was created with the intention of running through the Operator Lifecycle Manager, specifically on OpenShift 4, but you can install and get the same functionality on any Kubernetes cluster.

The following example shows the most minimal valid manifest to create a new Dapr instance:

apiVersion: operator.dapr.io/v1alpha1
kind: DaprControlPlane
metadata:
  name: "dapr-control-plane"
spec:
  values: {}

See the Dapr Kubernetes Operator repo for more details.

When the Dapr Kubernetes Operator sees a new DaprControlPlane resource, the Dapr components are provisioned using Kubernetes resources generated from the official Dapr Helm charts and managed by the operator. The same configuration options available when installing Dapr using Helm can also be used to configure the Dapr Kubernetes Operator.

When something changes on an existing DaprControlPlane resource or any resource generated by the operator, the operator reconfigures the cluster to ensure the actual state of the cluster matches the desired state.

The DaprControlPlane custom resource consists of the following properties:

Property Default Description
values [Empty] The values passed into the Dapr Helm chart

Demo

Watch the Dapr Community Call #90 presentation on the Dapr Kubernetes Operator.


Last modified February 15, 2024: Update daprdocs/content/en/operations/hosting/kubernetes/kubernetes-deploy.md (ad5bf014)