Partager via

Utiliser des références App Configuration pour Azure App Service et Azure Functions

Cet article explique comment utiliser des données de configuration dans des applications Azure App Service ou Azure Functions sans apporter de modifications de code. Azure App Configuration est un service Azure que vous pouvez utiliser pour gérer de manière centralisée la configuration des applications. Il s’agit également d’un outil efficace pour auditer vos valeurs de configuration au fil du temps ou entre les versions.

Octroyer à l’application l’accès à App Configuration

Pour commencer à utiliser des références App Configuration dans App Service, vous devez d’abord créer un magasin App Configuration. Vous accordez ensuite des autorisations à votre application pour accéder aux paires clé/valeur de configuration qui se trouvent dans le magasin.

  1. Pour créer un magasin App Configuration, suivez le Guide de démarrage rapide App Configuration.

  2. Créez une identité managée pour votre application.

    Les références App Configuration vont utiliser par défaut l’identité affectée par le système de l’application, mais vous pouvez spécifier une identité affectée par l’utilisateur.

  3. Octroyez à l’identité le jeu d’autorisations d’accès correct au magasin App Configuration. Mettez à jour les attributions de rôles pour votre magasin. Attribuez le rôle Lecteur de données App Configuration à cette identité, délimitée sur la ressource.

Accédez au magasin App Configuration avec une identité affectée par l’utilisateur

Dans certains cas, les applications peuvent avoir besoin de référencer la configuration lorsque vous les créez, mais une identité affectée par le système n’est pas encore disponible. Dans ce scénario, vous pouvez créer une identité affectée par l’utilisateur pour le magasin App Configuration à l’avance.

Après avoir octroyé les autorisations à l’identité affectée par l’utilisateur, procédez comme suit :

  1. Affectez l’identité à votre application.

  2. Configurez l’application pour utiliser cette identité pour les opérations de référence App Configuration en définissant la propriété keyVaultReferenceIdentity sur l’ID de ressource de l’identité affecté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. Voici le code  :

    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 s’applique à toutes les références dans l’application.

Octroyez à votre application l’accès aux coffres de clés référencés

Outre le stockage des valeurs de configuration brutes, App Configuration a son propre format pour stocker les références Azure Key Vault. Si la valeur d’une référence de configuration d'application est une référence "Key Vault" dans le magasin de configuration d'application, votre application doit également avoir les autorisations nécessaires pour accéder au coffre de clés spécifié dans la référence.

Remarque

Les références App Configuration Key Vault ne doivent pas être confondues avec les références App Service et Azure Functions Key Vault. Votre application peut utiliser n’importe quelle combinaison de ces références, mais d’importantes différences existent. 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 dernières versions, envisagez d’utiliser l’approche App Service et Azure Functions au lieu d’utiliser une référence App Configuration.

Pour accorder à votre application l’accès à un coffre de clés :

  1. Identifiez l’identité que vous avez utilisée pour la référence App Configuration. Vous devez octroyer l’accès au coffre à la même identité.

  2. 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 l’application autorisée ou les paramètres applicationId, car ils ne sont pas compatibles avec une identité managée.

Syntaxe de référence

Une référence App Configuration a la forme @Microsoft.AppConfiguration({referenceString}), où {referenceString} est remplacé par une valeur, comme décrit dans le tableau suivant :

Composant de la chaîne de référence Descriptif
Endpoint = <endpointURL> Endpoint (obligatoire). URL de votre ressource App Configuration.
Key = <myAppConfigKey> Key (obligatoire). Nom de la clé que vous souhaitez affecter au paramètre d’application.
Label = <myKeyLabel> Label (facultatif). Valeur de l’étiquette de clé spécifiée dans Key.

Voici un exemple de référence complète qui inclut Label :

@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey; Label=myKeyLabel)​

Voici un exemple qui n’inclut pas Label :

@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey)​

Toute modification de configuration apportée à l’application qui entraîne un redémarrage de site entraîne une nouvelle extraction immédiate de toutes les paires clé/valeur référencées à partir du magasin App Configuration.

Remarque

L'actualisation automatique et la récupération de ces valeurs lorsque les paires clé/valeur sont mises à jour dans l'App Configuration ne sont actuellement pas prises en charge.

Paramètres d’application source à partir d’App Configuration

Vous pouvez utiliser des références App Configuration comme valeurs pour les paramètres d’application afin de conserver les données de configuration dans App Configuration au lieu des paramètres de configuration du site. Les paramètres d’application et les paires clé/valeur App Configuration sont tous deux chiffrés en toute sécurité au repos. Si vous avez besoin de fonctionnalités de gestion de configuration centralisées, ajoutez les données de configuration à 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 par le biais de sa clé comme d’habitude. Aucune modification du code n’est requise.

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, afin de disposer de magasins ou d’étiquettes 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 démarre correctement. La plateforme s’appuie sur la présence d’un partage de contenu dans Azure Files et suppose un nom par défaut, sauf si un partage de contenu est spécifié dans le paramètre WEBSITE_CONTENTSHARE. Pour toutes les requêtes qui modifient ces paramètres, la plateforme tente de vérifier que le partage de contenu existe. Si le partage n’existe pas, la plateforme tente de créer le partage. Si elle ne peut pas localiser ou créer le partage de contenu, la requête est bloquée.

Si vous utilisez des références App Configuration pour ce paramètre, ce contrôle de validation échoue par défaut, car la connexion elle-même ne peut pas être résolue lors du traitement de la requête entrante. Pour éviter ce problème, vous pouvez ignorer la validation en définissant WEBSITE_SKIP_CONTENTSHARE_VALIDATION sur 1. Ce paramètre contourne toutes les vérifications et le partage de contenu n’est pas créé automatiquement. Vous devez vous assurer que le partage est créé à l’avance.

Attention

Si vous ignorez la validation et que la chaîne de connexion ou le partage de contenu n’est pas valide, l’application ne peut pas démarrer correctement et ne sert que les erreurs HTTP 500.

Lorsque vous créez un site, le montage du partage de contenu peut échouer si les autorisations d’identité managée ne sont pas propagées ou si l’intégration du réseau virtuel 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 plus d’informations, consultez le déploiement d’Azure Resource Manager dans la section suivante. Dans ce cas, App Service n’utilise qu’un système de fichiers par défaut jusqu’à ce qu’Azure Files soit configuré, et les fichiers ne sont pas copiés. Assurez-vous 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

Si vous automatisez les déploiements de ressources à l’aide de modèles Azure Resource Manager (ARM), vous devrez peut-être séquencer vos dépendances dans un ordre spécifique pour que les références App Configuration fonctionnent. Dans ce scénario, vous devez définir les paramètres de votre application comme leur propre ressource au lieu d’utiliser une propriété siteConfig dans la définition de site. Le site doit d’abord être défini afin que l’identité affectée par le système soit créée avec le site. L’identité managée est ensuite utilisée dans la stratégie d’accès.

Voici un exemple de modèle pour une application fonctionnelle qui contient 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"
            }
        }
    ]
}

Remarque

Dans cet exemple, le déploiement du contrôle de code source dépend des paramètres d’application. Dans la plupart des scénarios, cette séquence est moins sécurisée, car les paramètres de l’application sont mis à jour de façon asynchrone. Toutefois, étant donné que l’exemple inclut le WEBSITE_ENABLE_SYNC_UPDATE_SITE paramètre d’application, la mise à jour est synchrone. Le déploiement du contrôle de code source ne commence que lorsque les paramètres de l’application sont 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ésoudre les problèmes de références de configuration des applications

Si une référence ne se résout pas correctement, la valeur de la référence est utilisée à la place. Une variable d’environnement qui utilise la syntaxe @Microsoft.AppConfiguration(...) est créée. La référence peut entraîner une erreur, car l’application attendait une valeur de configuration.

Cette erreur est généralement le résultat d’une configuration incorrecte de la stratégie d’accès App Configuration. Toutefois, il peut également se produire s’il existe une erreur de syntaxe dans la référence ou si la paire clé/valeur de configuration n’existe pas dans le magasin.

Contenu connexe

  • Last updated on