Quickstart: Create an Azure App Configuration store by using an ARM template

Article
07/15/2024

This quickstart describes how to:

Deploy an App Configuration store using an Azure Resource Manager template (ARM template).
Create key-values in an App Configuration store using ARM template.
Read key-values in an App Configuration store from ARM template.

Tip

Feature flags and Key Vault references are special types of key-values. Check out the Next steps for examples of creating them using the ARM template.

An Azure Resource Manager template is a JavaScript Object Notation (JSON) file that defines the infrastructure and configuration for your project. The template uses declarative syntax. You describe your intended deployment without writing the sequence of programming commands to create the deployment.

If your environment meets the prerequisites and you're familiar with using ARM templates, select the Deploy to Azure button. The template will open in the Azure portal.

Prerequisites

If you don't have an Azure subscription, create a trial subscription before you begin.

Authorization

Managing Azure App Configuration resource inside an ARM template requires Azure Resource Manager role, such as contributor or owner. Accessing Azure App Configuration data (key-values, snapshots) requires Azure Resource Manager role and Azure App Configuration data plane role under pass-through ARM authentication mode.

Note

Key-value data access inside an ARM template is disabled if access key authentication is disabled.

Review the template

The template used in this quickstart is from Azure Quickstart Templates. It creates a new App Configuration store with two key-values inside. It then uses the reference function to output the values of the two key-value resources. Reading the key's value in this way allows it to be used in other places in the template.

The quickstart uses the copy element to create multiple instances of key-value resource. To learn more about the copy element, see Resource iteration in ARM templates.

Important

This template requires App Configuration control plane API version 2022-05-01 or later. This version uses the reference function to read key-values. The listKeyValue function that was used to read key-values in the previous version is not available starting in version 2020-07-01-preview.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "_generator": {
      "name": "bicep",
      "version": "0.4.1318.3566",
      "templateHash": "2545519807081080362"
    }
  },
  "parameters": {
    "configStoreName": {
      "type": "string",
      "metadata": {
        "description": "Specifies the name of the App Configuration store."
      }
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "Specifies the Azure location where the app configuration store should be created."
      }
    },
    "keyValueNames": {
      "type": "array",
      "defaultValue": [
        "myKey",
        "myKey$myLabel"
      ],
      "metadata": {
        "description": "Specifies the names of the key-value resources. The name is a combination of key and label with $ as delimiter. The label is optional."
      }
    },
    "keyValueValues": {
      "type": "array",
      "defaultValue": [
        "Key-value without label",
        "Key-value with label"
      ],
      "metadata": {
        "description": "Specifies the values of the key-value resources. It's optional"
      }
    },
    "contentType": {
      "type": "string",
      "defaultValue": "the-content-type",
      "metadata": {
        "description": "Specifies the content type of the key-value resources. For feature flag, the value should be application/vnd.microsoft.appconfig.ff+json;charset=utf-8. For Key Value reference, the value should be application/vnd.microsoft.appconfig.keyvaultref+json;charset=utf-8. Otherwise, it's optional."
      }
    },
    "tags": {
      "type": "object",
      "defaultValue": {
        "tag1": "tag-value-1",
        "tag2": "tag-value-2"
      },
      "metadata": {
        "description": "Adds tags for the key-value resources. It's optional"
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.AppConfiguration/configurationStores",
      "apiVersion": "2021-10-01-preview",
      "name": "[parameters('configStoreName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "standard"
      }
    },
    {
      "copy": {
        "name": "configStoreKeyValue",
        "count": "[length(parameters('keyValueNames'))]"
      },
      "type": "Microsoft.AppConfiguration/configurationStores/keyValues",
      "apiVersion": "2021-10-01-preview",
      "name": "[format('{0}/{1}', parameters('configStoreName'), parameters('keyValueNames')[copyIndex()])]",
      "properties": {
        "value": "[parameters('keyValueValues')[copyIndex()]]",
        "contentType": "[parameters('contentType')]",
        "tags": "[parameters('tags')]"
      },
      "dependsOn": [
        "[resourceId('Microsoft.AppConfiguration/configurationStores', parameters('configStoreName'))]"
      ]
    }
  ],
  "outputs": {
    "reference_key_value_value": {
      "type": "string",
      "value": "[reference(resourceId('Microsoft.AppConfiguration/configurationStores/keyValues', parameters('configStoreName'), parameters('keyValueNames')[0])).value]"
    },
    "reference_key_value_object": {
      "type": "object",
      "value": "[reference(resourceId('Microsoft.AppConfiguration/configurationStores/keyValues', parameters('configStoreName'), parameters('keyValueNames')[1]), '2021-10-01-preview', 'full')]"
    }
  }
}

Two Azure resources are defined in the template:

Microsoft.AppConfiguration/configurationStores: create an App Configuration store.
Microsoft.AppConfiguration/configurationStores/keyValues: create a key-value inside the App Configuration store.

Tip

The keyValues resource's name is a combination of key and label. The key and label are joined by the $ delimiter. The label is optional. In the above example, the keyValues resource with name myKey creates a key-value without a label.

Percent-encoding, also known as URL encoding, allows keys or labels to include characters that are not allowed in ARM template resource names. % is not an allowed character either, so ~ is used in its place. To correctly encode a name, follow these steps:

Apply URL encoding
Replace ~ with ~7E
Replace % with ~

For example, to create a key-value pair with key name AppName:DbEndpoint and label name Test, the resource name should be AppName~3ADbEndpoint$Test.

Note

App Configuration allows key-value data access over a private link from your virtual network. By default, when the feature is enabled, all requests for your App Configuration data over the public network are denied. Because the ARM template runs outside your virtual network, data access from an ARM template isn't allowed. To allow data access from an ARM template when a private link is used, you can enable public network access by using the following Azure CLI command. It's important to consider the security implications of enabling public network access in this scenario.

az appconfig update -g MyResourceGroup -n MyAppConfiguration --enable-public-network true

Deploy the template

Select the following image to sign in to Azure and open a template. The template creates an App Configuration store with two key-values inside.

You can also deploy the template by using the following PowerShell cmdlet. The key-values will be in the output of PowerShell console.

$projectName = Read-Host -Prompt "Enter a project name that is used for generating resource names"
$location = Read-Host -Prompt "Enter the location (i.e. chinaeast)"
$templateUri = "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.appconfiguration/app-configuration-store-kv/azuredeploy.json"

$resourceGroupName = "${projectName}rg"

New-AzResourceGroup -Name $resourceGroupName -Location "$location"
New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateUri $templateUri

Read-Host -Prompt "Press [ENTER] to continue ..."

Review deployed resources

Sign in to the Azure portal.
In the Azure portal search box, type App Configuration. Select App Configuration from the list.
Select the newly created App Configuration resource.
Under Operations, click Configuration explorer.
Verify that two key-values exist.

Clean up resources

When no longer needed, delete the resource group, the App Configuration store, and all related resources. If you're planning to use the App Configuration store in the future, you can skip deleting it. If you aren't going to continue to use this store, delete all resources created by this quickstart by running the following cmdlet:

$resourceGroupName = Read-Host -Prompt "Enter the Resource Group name"
Remove-AzResourceGroup -Name $resourceGroupName
Write-Host "Press [ENTER] to continue..."

Next steps

To learn about adding feature flag and Key Vault reference to an App Configuration store, check below ARM template examples.