Dapr extension for Azure Kubernetes Service (AKS) and Arc-enabled Kubernetes

Dapr is a portable, event-driven runtime that simplifies building resilient, stateless, and stateful applications that run on the cloud and edge and embrace the diversity of languages and developer frameworks. Applying the benefits of a sidecar architecture, Dapr helps you tackle the challenges that come with building microservices and keeps your code platform agnostic. In particular, it helps solve problems around services:

  • Calling other services reliably and securely
  • Building event-driven apps with pub-sub
  • Building applications that are portable across multiple cloud services and hosts (for example, Kubernetes vs. a VM)

By using the Dapr extension to provision Dapr on your AKS or Arc-enabled Kubernetes cluster, you eliminate the overhead of downloading Dapr tooling and manually installing and managing the runtime on your AKS cluster. Additionally, the extension offers support for all native Dapr configuration capabilities through simple command-line arguments.

Note

If you plan on installing Dapr in a Kubernetes production environment, see the Dapr guidelines for production usage documentation page.

How it works

The Dapr extension uses the Azure CLI to provision the Dapr control plane on your AKS or Arc-enabled Kubernetes cluster. This will create:

  • dapr-operator: Manages component updates and Kubernetes services endpoints for Dapr (state stores, pub/subs, etc.)
  • dapr-sidecar-injector: Injects Dapr into annotated deployment pods and adds the environment variables DAPR_HTTP_PORT and DAPR_GRPC_PORT to enable user-defined applications to easily communicate with Dapr without hard-coding Dapr port values.
  • dapr-placement: Used for actors only. Creates mapping tables that map actor instances to pods
  • dapr-sentry: Manages mTLS between services and acts as a certificate authority. For more information, read the security overview.

Once Dapr is installed on your cluster, you can begin to develop using the Dapr building block APIs by adding a few annotations to your deployments. For a more in-depth overview of the building block APIs and how to best use them, see the Dapr building blocks overview.

Warning

If you install Dapr through the AKS or Arc-enabled Kubernetes extension, our recommendation is to continue using the extension for future management of Dapr instead of the Dapr CLI. Combining the two tools can cause conflicts and result in undesired behavior.

Currently supported

Dapr versions

The Dapr extension support varies depending on how you manage the runtime.

Self-managed
For self-managed runtime, the Dapr extension supports:

Self-managed runtime requires manual upgrade to remain in the support window. To upgrade Dapr via the extension, follow the Update extension instance instructions.

Auto-upgrade
Enabling auto-upgrade keeps your Dapr extension updated to the latest minor version. You may experience breaking changes between updates.

Components

Azure + open source components are supported. Alpha and beta components are supported via best effort.

Clouds/regions

Global Azure cloud is supported with Arc support on the following regions:

Region AKS support Arc for Kubernetes support
australiaeast ✔️ ✔️
australiasoutheast ✔️
canadacentral ✔️ ✔️
canadaeast ✔️ ✔️
centralindia ✔️ ✔️
centralus ✔️ ✔️
eastasia ✔️ ✔️
eastus ✔️ ✔️
eastus2 ✔️ ✔️
eastus2euap ✔️
francecentral ✔️ ✔️
germanywestcentral ✔️ ✔️
japaneast ✔️ ✔️
koreacentral ✔️ ✔️
northcentralus ✔️ ✔️
northeurope ✔️ ✔️
norwayeast ✔️
southafricanorth ✔️
southcentralus ✔️ ✔️
southeastasia ✔️ ✔️
swedencentral ✔️ ✔️
switzerlandnorth ✔️ ✔️
uksouth ✔️ ✔️
westcentralus ✔️ ✔️
westeurope ✔️ ✔️
westus ✔️ ✔️
westus2 ✔️ ✔️
westus3 ✔️ ✔️

Prerequisites

Set up the Azure CLI extension for cluster extensions

You'll need the k8s-extension Azure CLI extension. Install by running the following commands:

az extension add --name k8s-extension

If the k8s-extension extension is already installed, you can update it to the latest version using the following command:

az extension update --name k8s-extension

Register the KubernetesConfiguration service provider

If you have not previously used cluster extensions, you may need to register the service provider with your subscription. You can check the status of the provider registration using the [az provider list][az-provider-list] command, as shown in the following example:

az provider list --query "[?contains(namespace,'Microsoft.KubernetesConfiguration')]" -o table

The Microsoft.KubernetesConfiguration provider should report as Registered, as shown in the following example output:

Namespace                          RegistrationState    RegistrationPolicy
---------------------------------  -------------------  --------------------
Microsoft.KubernetesConfiguration  Registered           RegistrationRequired

If the provider shows as NotRegistered, register the provider using the az provider register as shown in the following example:

az provider register --namespace Microsoft.KubernetesConfiguration

Create the extension and install Dapr on your AKS or Arc-enabled Kubernetes cluster

When installing the Dapr extension, use the flag value that corresponds to your cluster type:

  • AKS cluster: --cluster-type managedClusters.
  • Arc-enabled Kubernetes cluster: --cluster-type connectedClusters.

Note

If you're using Dapr OSS on your AKS cluster and would like to install the Dapr extension for AKS, read more about how to successfully migrate to the Dapr extension.

Create the Dapr extension, which installs Dapr on your AKS or Arc-enabled Kubernetes cluster. For example, for an AKS cluster:

az k8s-extension create --cluster-type managedClusters \
--cluster-name myAKSCluster \
--resource-group myResourceGroup \
--name dapr \
--extension-type Microsoft.Dapr

You have the option of allowing Dapr to auto-update its minor version by specifying the --auto-upgrade-minor-version parameter and setting the value to true:

--auto-upgrade-minor-version true

When configuring the extension, you can choose to install Dapr from a particular --release-train. Specify one of the two release train values:

Value Description
stable Default.
dev Early releases, can contain experimental features. Not suitable for production.

For example:

--release-train stable

Configuration settings

The extension enables you to set Dapr configuration options by using the --configuration-settings parameter. For example, to provision Dapr with high availability (HA) enabled, set the global.ha.enabled parameter to true:

az k8s-extension create --cluster-type managedClusters \
--cluster-name myAKSCluster \
--resource-group myResourceGroup \
--name dapr \
--extension-type Microsoft.Dapr \
--auto-upgrade-minor-version true \
--configuration-settings "global.ha.enabled=true" \
--configuration-settings "dapr_operator.replicaCount=2"

Note

If configuration settings are sensitive and need to be protected, for example cert related information, pass the --configuration-protected-settings parameter and the value will be protected from being read.

If no configuration-settings are passed, the Dapr configuration defaults to:

  ha:
    enabled: true
    replicaCount: 3
    disruption:
      minimumAvailable: ""
      maximumUnavailable: "25%"
  prometheus:
    enabled: true
    port: 9090
  mtls:
    enabled: true
    workloadCertTTL: 24h
    allowedClockSkew: 15m

For a list of available options, see Dapr configuration.

Targeting a specific Dapr version

Note

Dapr is supported with a rolling window, including only the current and previous versions. It is your operational responsibility to remain up to date with these supported versions. If you have an older version of Dapr, you may have to do intermediate upgrades to get to a supported version.

The same command-line argument is used for installing a specific version of Dapr or rolling back to a previous version. Set --auto-upgrade-minor-version to false and --version to the version of Dapr you wish to install. If the version parameter is omitted, the extension will install the latest version of Dapr. For example, to use Dapr X.X.X:

az k8s-extension create --cluster-type managedClusters \
--cluster-name myAKSCluster \
--resource-group myResourceGroup \
--name dapr \
--extension-type Microsoft.Dapr \
--auto-upgrade-minor-version false \
--version X.X.X

Limiting the extension to certain nodes

In some configurations, you may only want to run Dapr on certain nodes. You can limit the extension by passing a nodeSelector in the extension configuration. If the desired nodeSelector contains ., you must escape them from the shell and the extension. For example, the following configuration will install Dapr to only nodes with topology.kubernetes.io/zone: "us-east-1c":

az k8s-extension create --cluster-type managedClusters \
--cluster-name myAKSCluster \
--resource-group myResourceGroup \
--name dapr \
--extension-type Microsoft.Dapr \
--auto-upgrade-minor-version true \
--configuration-settings "global.ha.enabled=true" \
--configuration-settings "dapr_operator.replicaCount=2" \
--configuration-settings "global.nodeSelector.kubernetes\.io/zone: us-east-1c"

For managing OS and architecture, use the supported versions of the global.daprControlPlaneOs and global.daprControlPlaneArch configuration:

az k8s-extension create --cluster-type managedClusters \
--cluster-name myAKSCluster \
--resource-group myResourceGroup \
--name dapr \
--extension-type Microsoft.Dapr \
--auto-upgrade-minor-version true \
--configuration-settings "global.ha.enabled=true" \
--configuration-settings "dapr_operator.replicaCount=2" \
--configuration-settings "global.daprControlPlaneOs=linux” \
--configuration-settings "global.daprControlPlaneArch=amd64”

Set automatic CRD updates

Starting with Dapr version 1.9.2, CRDs are automatically upgraded when the extension upgrades. To disable this setting, you can set hooks.applyCrds to false.

az k8s-extension upgrade --cluster-type managedClusters \
--cluster-name myAKSCluster \
--resource-group myResourceGroup \
--name dapr \
--extension-type Microsoft.Dapr \
--auto-upgrade-minor-version true \
--configuration-settings "global.ha.enabled=true" \
--configuration-settings "dapr_operator.replicaCount=2" \
--configuration-settings "global.daprControlPlaneOs=linux” \
--configuration-settings "global.daprControlPlaneArch=amd64” \
--configuration-settings "hooks.applyCrds=false"

Configure the Dapr release namespace

You can configure the release namespace. The Dapr extension gets installed in the dapr-system namespace by default. To override it, use --release-namespace. Include the cluster --scope to redefine the namespace.

az k8s-extension create \
--cluster-type managedClusters \
--cluster-name dapr-aks \
--resource-group dapr-rg \
--name my-dapr-ext \
--extension-type microsoft.dapr \
--release-train stable \
--auto-upgrade false \
--version 1.9.2 \
--scope cluster \
--release-namespace dapr-custom

Show current configuration settings

Use the az k8s-extension show command to show the current Dapr configuration settings:

az k8s-extension show --cluster-type managedClusters \
--cluster-name myAKSCluster \
--resource-group myResourceGroup \
--name dapr

Update configuration settings

Important

Some configuration options cannot be modified post-creation. Adjustments to these options require deletion and recreation of the extension, applicable to the following settings:

  • global.ha.*
  • dapr_placement.*

HA is enabled enabled by default. Disabling it requires deletion and recreation of the extension.

To update your Dapr configuration settings, recreate the extension with the desired state. For example, assume we've previously created and installed the extension using the following configuration:

az k8s-extension create --cluster-type managedClusters \
--cluster-name myAKSCluster \
--resource-group myResourceGroup \
--name dapr \
--extension-type Microsoft.Dapr \
--auto-upgrade-minor-version true \  
--configuration-settings "global.ha.enabled=true" \
--configuration-settings "dapr_operator.replicaCount=2" 

To update the dapr_operator.replicaCount from two to three, use the following command:

az k8s-extension create --cluster-type managedClusters \
--cluster-name myAKSCluster \
--resource-group myResourceGroup \
--name dapr \
--extension-type Microsoft.Dapr \
--auto-upgrade-minor-version true \
--configuration-settings "global.ha.enabled=true" \
--configuration-settings "dapr_operator.replicaCount=3"

Set the outbound proxy for Dapr extension for Azure Arc on-premises

If you want to use an outbound proxy with the Dapr extension for AKS, you can do so by:

  1. Setting the proxy environment variables using the dapr.io/env annotations:
    • HTTP_PROXY
    • HTTPS_PROXY
    • NO_PROXY
  2. Installing the proxy certificate in the sidecar.

Meet network requirements

The Dapr extension for AKS and Arc for Kubernetes requires outbound URLs on https://:443 to function. In addition to the https://mcr.microsoft.com/daprio URL for pulling Dapr artifacts, verify you've included the outbound URLs required for AKS or Arc for Kubernetes.

Troubleshooting extension errors

If the extension fails to create or update, try suggestions and solutions in the Dapr extension troubleshooting guide.

Troubleshooting Dapr

Troubleshoot Dapr errors via the common Dapr issues and solutions guide.

Delete the extension

If you need to delete the extension and remove Dapr from your AKS cluster, you can use the following command:

az k8s-extension delete --resource-group myResourceGroup --cluster-name myAKSCluster --cluster-type managedClusters --name dapr

Next Steps

  • Once you have successfully provisioned Dapr in your AKS cluster, try deploying a sample application.