Utiliser des références App Configuration pour App Service et Azure Functions
Cette rubrique vous montre comment utiliser des données de configuration dans votre application App Service ou Azure Functions, sans avoir à modifier le code. Azure App Configuration est un service de gestion centralisée de la configuration d’applications. En outre, c’est un outil d’audit efficace pour vos valeurs de configuration au fil du temps ou des versions.
Accorder à votre application l’accès à App Configuration
Pour commencer à utiliser des références App Configuration dans App Service, vous devez d’abord disposer d’un magasin App Configuration et fournir à votre application l’autorisation d’accéder aux clés-valeurs de configuration dans le magasin.
Créez un magasin App Configuration en suivant le Guide de démarrage rapide App Configuration.
Créez une identité managée pour votre application.
Les références App Configuration vont utiliser par défaut l’identité attribuée par le système de l’application, mais vous pouvez spécifier une identité attribuée par l’utilisateur.
Activez l’identité nouvellement créée pour avoir le bon ensemble d’autorisations d’accès sur le magasin App Configuration. Mettez à jour les attributions de rôles pour votre magasin. Vous allez attribuer le rôle
App Configuration Data Readerà cette identité, délimitée sur la ressource.
Accéder au magasin App Configuration avec une identité attribuée par l’utilisateur
Certaines applications doivent référencer une configuration au moment de la création, quand une identité attribuée par le système n’est pas encore disponible. Dans ce cas, une identité attribuée par l’utilisateur peut être créée et l’accès au magasin App Configuration peut lui être accordé à l’avance. Suivez ces étapes pour créer une identité attribuée par l’utilisateur pour le magasin App Configuration.
Une fois que vous avez accordé des autorisations à l’identité attribuée par l’utilisateur, procédez comme suit :
Attribuez l’identité à votre application si vous ne l’avez pas déjà fait.
Configurez l’application pour utiliser cette identité pour les opérations de référence App Configuration en définissant la propriété
keyVaultReferenceIdentitysur l’ID de ressource de l’identité attribuée par l’utilisateur. Bien que la propriété ait keyVault dans le nom, l’identité s’applique également aux références App Configuration.userAssignedIdentityResourceId=$(az identity show -g MyResourceGroupName -n MyUserAssignedIdentityName --query id -o tsv) appResourceId=$(az webapp show -g MyResourceGroupName -n MyAppName --query id -o tsv) az rest --method PATCH --uri "${appResourceId}?api-version=2021-01-01" --body "{'properties':{'keyVaultReferenceIdentity':'${userAssignedIdentityResourceId}'}}"
Cette configuration va s’appliquer à toutes les références de cette application.
Accorde à votre application l’accès aux coffres de clés référencés
Outre le stockage des valeurs de configuration brutes, Azure App Configuration a son propre format pour stocker les références Key Vault. Si la valeur d’une référence de App Configuration est une référence Key Vault dans le magasin App Configuration, votre application doit également avoir l’autorisation d’accéder au coffre de clés spécifié.
Notes
Le concept de références Key Vault de Azure App Configuration ne doit pas être confondu avec le concept de références Key Vault de App Service et Azure Functions. Votre application peut utiliser n’importe quelle combinaison de ces éléments, mais d’importantes différences sont à noter. Si votre coffre doit être limité au réseau ou si vous avez besoin que l’application soit régulièrement mise à jour vers les versions les plus récentes, envisagez d’utiliser l’approche directe App Service et Azure Functions au lieu d’utiliser une référence App Configuration.
Identifiez l’identité que vous avez utilisée pour la référence App Configuration. L’accès au coffre doit être accordé à cette même identité.
Créez une stratégie d’accès dans Key Vault pour cette identité. Activez l’autorisation de secret « Get » sur cette stratégie. Ne configurez pas les paramètres « application autorisée » ou
applicationIdcar ils sont incompatibles avec une identité managée.
Syntaxe de référence
Une référence App Configuration est de la forme @Microsoft.AppConfiguration({referenceString}), où {referenceString} est remplacé par ceci :
| Composants des chaînes de référence | Description |
|---|---|
| Endpoint=point de terminaison; | Endpoint est la partie obligatoire de la chaîne de référence. La valeur de Endpoint doit avoir l’URL de votre ressource App Configuration. |
| Key=nom_clé; | Key forme la partie obligatoire de la chaîne de référence. La valeur de Key doit être le nom de la clé que vous voulez affecter au paramètre d’application. |
| Label=libellé | La partie Label est facultative dans la chaîne de référence. Label doit être la valeur du libellé pour la clé spécifiée dans Key |
Par exemple, une référence complète avec Label se présenterait comme ceci :
@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey; Label=myKeysLabel)
Ou, sans Label :
@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey)
Toute modification de la configuration de l’application provoquant un redémarrage du site entraîne une réextraction immédiate de toute les clés-valeurs référencées du magasin App Configuration.
Remarque
L’actualisation ou la réextraction automatique de ces valeurs une fois les clés-valeurs mises à jour dans App Configuration n’est pas actuellement prise en charge.
Paramètres d’application sources dans App Configuration
Les références App Configuration peuvent être utilisées comme valeurs pour les paramètres d’application, ce qui vous permet de conserver les données de configuration dans App Configuration au lieu de le faire dans la configuration du site. Les paramètres d’application et les clés-valeurs App Configuration sont tous chiffrés de façon sécurisée au repos. Si vous avez besoin de fonctionnalités de gestion de configuration centralisées, les données de configuration doivent être placées dans App Configuration.
Pour utiliser une référence App Configuration pour un paramètre d’application, définissez la référence comme valeur du paramètre. Votre application peut référencer la valeur de Configuration via sa clé, comme habituellement. Le code n’a pas besoin d’être modifié.
Conseil
La plupart des paramètres d’application qui utilisent des références App Configuration doivent être marqués comme paramètres d’emplacement, car vous devez avoir des magasins ou des libellés distincts pour chaque environnement.
Considérations relatives au montage Azure Files
Les applications peuvent utiliser le paramètre d’application WEBSITE_CONTENTAZUREFILECONNECTIONSTRING pour monter Azure Files en tant que système de fichiers. Ce paramètre a des contrôles de validation supplémentaires pour garantir que l’application peut être démarrée correctement. La plateforme s’appuie sur un partage de contenu dans Azure Files et suppose un nom par défaut, sauf si un nom est spécifié via le paramètre WEBSITE_CONTENTSHARE. Pour les demandes qui modifient ces paramètres, la plateforme va tenter de vérifier si ce partage de contenu existe, et si ce n’est pas le cas, elle va tenter de le créer. Si elle ne peut pas localiser ou créer le partage de contenu, la demande est bloquée.
Si vous utilisez des références App Configuration pour ce paramètre, ce contrôle de validation va échouer par défaut, car la connexion elle-même ne peut pas être résolue lors du traitement de la demande entrante. Pour éviter ce problème, vous pouvez ignorer la validation en affectant « 1 » à WEBSITE_SKIP_CONTENTSHARE_VALIDATION. Cette valeur du paramètre permet d’ignorer toutes les vérifications, et le partage de contenu ne sera pas créé pour vous. Vous devez vérifier qu’il est créé à l’avance.
Attention
Si vous ignorez la validation et que la chaîne de connexion ou le partage de contenu ne sont pas valides, l’application ne pourra pas démarrer correctement et renverra uniquement des erreurs HTTP 500.
Dans le cadre de la création du site, il est également possible que la tentative de montage du partage de contenu échoue en raison d’autorisations d’identité gérées qui ne sont pas propagées ou d’une intégration de réseau virtuel qui n’est pas configurée. Vous pouvez différer la configuration d’Azure Files jusqu’à un moment ultérieur dans le modèle de déploiement pour la configuration requise. Pour en savoir plus, consultez Modes de déploiement d’Azure Resource Manager. App Service utilise un système de fichiers par défaut jusqu’à ce qu’Azure Files soit configuré et les fichiers ne sont pas copiés : vous devez donc vérifier qu’aucune tentative de déploiement ne se produit pendant la période intermédiaire avant le montage d’Azure Files.
Déploiement Azure Resource Manager
Quand vous automatisez des déploiements de ressources par le biais de modèles Azure Resource Manager, vous pouvez avoir besoin de séquencer vos dépendances dans un ordre particulier pour que cette fonctionnalité fonctionne. Sinon, vous devrez définir vos paramètres d’application comme étant leur propre ressource, au lieu d’utiliser une propriété siteConfig dans la définition de site. C’est parce que le site doit être défini en premier pour que le système puisse affecter l’identité et que cette identité puisse être utilisée dans la stratégie d’accès.
Voici un exemple de pseudo-modèle pour une application de fonction avec des références App Configuration :
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"roleNameGuid": {
"type": "string",
"defaultValue": "[newGuid()]",
"metadata": {
"description": "A new GUID used to identify the role assignment"
}
}
},
"variables": {
"functionAppName": "DemoMBFunc",
"appConfigStoreName": "DemoMBAppConfig",
"resourcesRegion": "West US2",
"appConfigSku": "standard",
"FontNameKey": "FontName",
"FontColorKey": "FontColor",
"myLabel": "Test",
"App Configuration Data Reader": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', '516239f1-63e1-4d78-a4de-a74fb236a071')]"
},
"resources": [
{
"type": "Microsoft.Web/sites",
"name": "[variables('functionAppName')]",
"apiVersion": "2021-03-01",
"location": "[variables('resourcesRegion')]",
"identity": {
"type": "SystemAssigned"
},
//...
"resources": [
{
"type": "config",
"name": "appsettings",
"apiVersion": "2021-03-01",
//...
"dependsOn": [
"[resourceId('Microsoft.Web/sites', variables('functionAppName'))]",
"[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]"
],
"properties": {
"WEBSITE_FONTNAME": "[concat('@Microsoft.AppConfiguration(Endpoint=', reference(resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))).endpoint,'; Key=',variables('FontNameKey'),'; Label=',variables('myLabel'), ')')]",
"WEBSITE_FONTCOLOR": "[concat('@Microsoft.AppConfiguration(Endpoint=', reference(resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))).endpoint,'; Key=',variables('FontColorKey'),'; Label=',variables('myLabel'), ')')]",
"WEBSITE_ENABLE_SYNC_UPDATE_SITE": "true"
//...
}
},
{
"type": "sourcecontrols",
"name": "web",
"apiVersion": "2021-03-01",
//...
"dependsOn": [
"[resourceId('Microsoft.Web/sites', variables('functionAppName'))]",
"[resourceId('Microsoft.Web/sites/config', variables('functionAppName'), 'appsettings')]"
]
}
]
},
{
"type": "Microsoft.AppConfiguration/configurationStores",
"name": "[variables('appConfigStoreName')]",
"apiVersion": "2019-10-01",
"location": "[variables('resourcesRegion')]",
"sku": {
"name": "[variables('appConfigSku')]"
},
//...
"dependsOn": [
"[resourceId('Microsoft.Web/sites', variables('functionAppName'))]"
],
"properties": {
},
"resources": [
{
"type": "keyValues",
"name": "[variables('FontNameKey')]",
"apiVersion": "2021-10-01-preview",
//...
"dependsOn": [
"[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]"
],
"properties": {
"value": "Calibri",
"contentType": "application/json"
}
},
{
"type": "keyValues",
"name": "[variables('FontColorKey')]",
"apiVersion": "2021-10-01-preview",
//...
"dependsOn": [
"[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]"
],
"properties": {
"value": "Blue",
"contentType": "application/json"
}
}
]
},
{
"scope": "[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]",
"type": "Microsoft.Authorization/roleAssignments",
"apiVersion": "2020-04-01-preview",
"name": "[parameters('roleNameGuid')]",
"properties": {
"roleDefinitionId": "[variables('App Configuration Data Reader')]",
"principalId": "[reference(resourceId('Microsoft.Web/sites/', variables('functionAppName')), '2020-12-01', 'Full').identity.principalId]",
"principalType": "ServicePrincipal"
}
}
]
}
Notes
Dans cet exemple, le déploiement du contrôle de code source varie selon les paramètres d’application. Il s’agit normalement d’un comportement non sécurisé, car la mise à jour du paramètre d’application se comporte de façon asynchrone. Toutefois, comme nous avons inclus le paramètre d'application WEBSITE_ENABLE_SYNC_UPDATE_SITE, la mise à jour est synchrone. Cela signifie que le déploiement de contrôle source commence uniquement une fois que les paramètres d’application ont été entièrement mis à jour. Pour plus d’informations sur les paramètres d’application, consultez Variables d’environnement et paramètres d’application dans Azure App Service.
Résolution des problèmes liés aux références App Configuration
Si une référence ne se résout pas correctement, la valeur de la référence est utilisée à la place. Pour les paramètres d’application, une variable d’environnement sera créée, dont la valeur a la syntaxe @Microsoft.AppConfiguration(...). Ceci peut entraîner une erreur, car l’application attendait à la place une valeur de configuration.
La plupart du temps, cette erreur peut être due à une configuration incorrecte de la stratégie d’accès App Configuration. Cependant, cela peut également être dû à une erreur de syntaxe dans la référence ou au fait que la clé-valeur de Configuration n’existe pas dans le magasin.