Deploy Dapr on a Kubernetes cluster

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

For more information on what is deployed to your Kubernetes cluster read the Kubernetes overview

Prerequisites

• Install Dapr CLI
• Install kubectl
• Kubernetes cluster (see below if needed)

Create cluster

You can install Dapr on any Kubernetes cluster. Here are some helpful links:

• Setup KiNd Cluster
• Setup Minikube Cluster
• Setup Azure Kubernetes Service Cluster
• Setup Google Cloud Kubernetes Engine
• Setup Amazon Elastic Kubernetes Service

Install with Dapr CLI

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

Install Dapr (from an official Dapr Helm chart)

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

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

dapr init -k

⌛  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

Install Dapr (a private Dapr Helm chart)

There are some scenarios where it’s necessary to install Dapr from a private Helm chart, such as:

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

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"

Setting the above parameters will allow dapr init -k to install Dapr images from the configured Helm repository.

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

Install in highly available mode

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

dapr init -k --enable-ha=true

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

Install with Helm (advanced)

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

Add and install Dapr Helm chart

1. Make sure Helm 3 is installed on your machine

2. Add 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
   

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

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

   To install in high availability mode:

   helm upgrade --install dapr dapr/dapr \
   --version=1.10 \
   --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.

Uninstall Dapr on Kubernetes

helm uninstall dapr --namespace dapr-system

More information

• Read this guide for recommended Helm chart values for production setups
• See this page for details on Dapr Helm charts.

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

Using Mariner-based images

When deploying Dapr, whether on Kubernetes or in Docker self-hosted, the default container images that are pulled 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.10-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.10 \
  --namespace dapr-system \
  --create-namespace \
  --set global.tag=1.10.8-mariner \
  --wait

Next steps

• Configure state store & pubsub message broker