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

Before you begin

Add the Azure CLI extension for cluster extensions

Install the k8s-extension Azure CLI extension 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 resource provider

If you haven't previously used cluster extensions, you may need to register the resource provider with your subscription. You can check the status of the provider registration using the 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

Register the ExtenstionTypes feature to your Azure subscription

The ExtensionTypes feature needs to be registered to your Azure subscription. In the terminal, verify you're in the correct subscription:

az account set --subscription <YOUR-AZURE-SUBSCRIPTION-ID>

Register the ExtenstionTypes feature.

az feature registration create --namespace Microsoft.KubernetesConfiguration --name ExtensionTypes

Feature registration may take some time. After a few minutes, check the registration status using the following command:

az feature show --namespace Microsoft.KubernetesConfiguration --name ExtensionTypes

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.

Create the Dapr extension, which installs Dapr on your AKS or Arc-enabled Kubernetes cluster.

For example, install the latest version of Dapr via the Dapr extension on your AKS cluster:

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

Configuring automatic updates to Dapr control plane

If you install Dapr without specifying a version, --auto-upgrade-minor-version is automatically enabled, configuring the Dapr control plane to automatically update its minor version on new releases.

You can disable auto-update by specifying the --auto-upgrade-minor-version parameter and setting the value to false.

Dapr versioning is in MAJOR.MINOR.PATCH format, which means 1.11.0 to 1.12.0 is a minor version upgrade.

--auto-upgrade-minor-version true

Targeting a specific Dapr 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 installs the latest version of Dapr. For example, to use Dapr 1.11.2:

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 1.11.2

Choosing a release train

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

For example:

--release-train stable

Before you begin

Register the KubernetesConfiguration resource provider

If you haven't previously used cluster extensions, you may need to register the resource provider with your subscription. You can check the status of the provider registration using the 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

Register the ExtenstionTypes feature to your Azure subscription

The ExtensionTypes feature needs to be registered to your Azure subscription. In the terminal, verify you're in the correct subscription:

az account set --subscription <YOUR-AZURE-SUBSCRIPTION-ID>

Register the ExtenstionTypes feature.

az feature registration create --namespace Microsoft.KubernetesConfiguration --name ExtensionTypes

Feature registration may take some time. After a few minutes, check the registration status using the following command:

az feature show --namespace Microsoft.KubernetesConfiguration --name ExtensionTypes

Deploy the Dapr extension on your AKS or Arc-enabled Kubernetes cluster

Create a Bicep template similar to the following example to deploy the Dapr extension to your existing cluster.

@description('The name of the Managed Cluster resource.')
param clusterName string

resource existingManagedClusters 'Microsoft.ContainerService/managedClusters@2023-05-02-preview' existing = {
  name: clusterName
}

resource daprExtension 'Microsoft.KubernetesConfiguration/extensions@2022-11-01' = {
  name: 'dapr'
  scope: existingManagedClusters
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    autoUpgradeMinorVersion: true
    configurationProtectedSettings: {}
    configurationSettings: {
      'global.clusterType': 'managedclusters'
    }
    extensionType: 'microsoft.dapr'
    releaseTrain: 'stable'
    scope: {
      cluster: {
        releaseNamespace: 'dapr-system'
      }
    }
    version: '1.11.2'
  }
}

Set the following variables, changing the values below to your actual resource group and cluster names.

MY_RESOURCE_GROUP=myResourceGroup
MY_AKS_CLUSTER=myAKScluster

Deploy the Bicep template using the az deployment group command.

az deployment group create \
  --resource-group $MY_RESOURCE_GROUP \
  --template-file ./my-bicep-file-path.bicep \
  --parameters clusterName=$MY_AKS_CLUSTER

Configuring automatic updates to Dapr control plane

If you deploy Dapr without specifying a version, autoUpgradeMinorVersion is automatically enabled, configuring the Dapr control plane to automatically update its minor version on new releases.

You can disable auto-update by specifying the autoUpgradeMinorVersion parameter and setting the value to false.

Dapr versioning is in MAJOR.MINOR.PATCH format, which means 1.11.0 to 1.12.0 is a minor version upgrade.

properties {
  autoUpgradeMinorVersion: true
}

Targeting a specific Dapr version

Set autoUpgradeMinorVersion to false and version to the version of Dapr you wish to install. If the autoUpgradeMinorVersion parameter is set to true, and version parameter is omitted, the extension installs the latest version of Dapr.

For example, to use Dapr 1.11.2:

properties: {
  autoUpgradeMinorVersion: false
  version: '1.11.2'
}

Choosing a release train

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

For example:

properties: {
  releaseTrain: 'stable'
}