Configure the Dapr extension for your Azure Kubernetes Service (AKS) and Arc-enabled Kubernetes project

After completing the prerequisites for installing the Dapr extension, you can configure the Dapr extension to work best for you and your project using various configuration options, like:

• Rotating expiring certificates
• Provisioning Dapr with high availability (HA) enabled
• Limiting which of your nodes use the Dapr extension
• Setting automatic custom resource definition (CRD) updates
• Configuring the Dapr release namespace

The extension enables you to set Dapr configuration options by using the --configuration-settings parameter in the Azure CLI or configurationSettings property in a Bicep template.

Manage mTLS certificates

The Dapr extension supports in-transit encryption of communication between Dapr instances using the Dapr Sentry service control plane, which is a central Certificate Authority (CA). With the Sentry service, you can encrypt communication using self-signed or user-supplied x.509 certificates. Learn more about setting up mTLS certificates in the open-source Dapr documentation.

You can bring in your own certificates, or let Dapr automatically create and persist self-signed root and issuer certificates.

Important

If you don't explicitly configure certificates, Dapr defaults to generating self-signed certificates, which are generally valid for 1 year. Currently, using self-signed certificates generated by Dapr is not recommended. Best practice is to generate custom certificates and update them manually.

Manage Dapr-generated self-signed certificates

If you haven't provided any custom certificates, Dapr automatically creates and persists self-signed certificates, valid for 1 year. The Dapr extension installs the dapr-trust-bundle secret, which contains certificate information under the default dapr-system namespace.

Check expiry of current Dapr-generated self-signed certificates

You can check when the Dapr root certificate of your Kubernetes cluster expires by using the Dapr CLI.

dapr mtls expiry

Expected output:

Root certificate expires in 8759 hours. Expiry date: 2025-12-06 18:14:20 +0000 UTC

You can also find the expiration date for your current certificate in the Kubernetes dapr-trust-bundle secret data.

kubectl get secret dapr-trust-bundle -n dapr-system -o jsonpath='{.data.issuer\.crt}' | base64 -d | openssl x509 -noout -dates

Expected output:

notBefore=Dec  6 17:59:20 2024 GMT
notAfter=Dec  6 18:14:20 2025 GMT

Generate a new Dapr-generated self-signed certificate

• Via the Dapr CLI (recommended)
  Refer to Dapr's Root and issuer certificate upgrade using CLI guide.
• Via kubectl commands Refer to Dapr's Updating root or issuer certs using Kubectl guide.

Manage your own user-supplied x.509 certificates

You can also bring your own custom certificates.

• Generate custom certificates
  Create your own custom certificate; for example, an Azure Key Vault certificate.
• Update your custom certficate manually
  Follow the instructions provided in the Dapr open source documentation to update your custom certificates manually using kubectl.

Provision Dapr with high availability (HA) enabled

Provision Dapr with high availability (HA) enabled by setting the global.ha.enabled parameter to true.

Azure CLI

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.

Bicep

properties: {
  configurationSettings: {
    'global.ha.enabled': true
  }
}

Note

If configuration settings are sensitive and need to be protected (for example, cert-related information), use the configurationProtectedSettings property 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.

Limit 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 installs Dapr only to nodes with topology.kubernetes.io/zone: "us-east-1c":

Azure CLI

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”

Bicep

properties: {
  configurationSettings: {
    'global.clusterType': 'managedclusters'
    'global.ha.enabled': true
    '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:

properties: {
  configurationSettings: {
    'global.clusterType': 'managedclusters'
    'global.ha.enabled': true
    'global.daprControlPlaneOs': 'linux'
    'global.daprControlPlaneArch': 'amd64'
  }
}

Install Dapr in multiple availability zones while in HA mode

By default, the placement service uses a storage class of type standard_LRS. It's recommended to create a zone redundant storage class while installing Dapr in HA mode across multiple availability zones. For example, to create a zrs type storage class, add the storageaccounttype parameter:

kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: custom-zone-redundant-storage
provisioner: disk.csi.azure.com
reclaimPolicy: Delete
allowVolumeExpansion: true
volumeBindingMode: WaitForFirstConsumer
parameters:
  storageaccounttype: Premium_ZRS

When installing Dapr, use the storage class you used in the YAML file:

Azure CLI

az k8s-extension create --cluster-type managedClusters  
--cluster-name XXX  
--resource-group XXX  
--name XXX  
--extension-type Microsoft.Dapr  
--auto-upgrade-minor-version XXX  
--version XXX  
--configuration-settings "dapr_placement.volumeclaims.storageClassName=custom-zone-redundant-storage"

Bicep

properties: {
  configurationSettings: {
    'dapr_placement.volumeclaims.storageClassName': 'custom-zone-redundant-storage'
    'global.ha.enabled': true  
  }
}

Configure the Dapr release namespace

You can configure the release namespace.

Azure CLI

The Dapr extension gets installed in the dapr-system namespace by default. To override it, use --release-namespace. To redefine the namespace, include the cluster --scope.

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

Bicep

The Dapr extension gets installed in the dapr-system namespace by default. To override it, use releaseNamespace in the cluster scope to redefine the namespace.

properties: {
  scope: {
    cluster: {
      releaseNamespace: 'dapr-custom'
    }
  }
}

Learn how to configure the Dapr release namespace when migrating from Dapr open source to the Dapr extension.

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 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, let's say you 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.

Updating your Dapr installation version

Azure CLI

If you are on a specific Dapr version and you don't have --auto-upgrade-minor-version available, you can use the following command to upgrade or downgrade Dapr:

az k8s-extension update --cluster-type managedClusters \
--cluster-name myAKSCluster \
--resource-group myResourceGroup \
--name dapr \
--version 1.12.0 # Version to upgrade or downgrade to

Bicep

If you are on a specific Dapr version and you don't have autoUpgradeMinorVersion available, you can use the following Bicep property to upgrade or downgrade Dapr:

properties: {
  version: '1.12.0'
}

The preceding command updates the Dapr control plane only. To update the Dapr sidecars, restart your application deployments:

kubectl rollout restart deploy/<DEPLOYMENT-NAME>

Using Azure Linux-based images

From Dapr version 1.8.0, you can use Azure Linux images with the Dapr extension. To use them, set the global.tag flag:

Azure CLI

az k8s-extension update --cluster-type managedClusters \
--cluster-name myAKSCluster \
--resource-group myResourceGroup \
--name dapr \
--set global.tag=1.10.0-mariner

Bicep

properties: {
  global.tag: '1.10.0-mariner'
}

• Learn more about using Mariner-based images with Dapr.
• Learn more about deploying Azure Linux on AKS.

Disable automatic CRD updates

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

Azure CLI

az k8s-extension update --cluster-type managedClusters \
--cluster-name myAKSCluster \
--resource-group myResourceGroup \
--name dapr \
--configuration-settings "hooks.applyCrds=false"

Bicep

properties: {
  configurationSettings: {
    'hooks.applyCrds': false
  } 
}

Note

CRDs are only applied in case of upgrades and are skipped during downgrades.

Meet network requirements

The Dapr extension requires the following outbound URLs on https://:443 to function on AKS and Arc for Kubernetes:

1. https://mcr.microsoft.com/daprio URL for pulling Dapr artifacts.
2. The outbound URLs required for AKS or Arc for Kubernetes.

Next Steps

• Walk through the tutorial for deploying Dapr Workflow via the extension
• Migrate from Dapr open source to the Dapr extension.