Verwenden von App-Konfigurationsreferenzen für Azure App Service und Azure-Funktionen

In diesem Artikel wird gezeigt, wie Sie mit Konfigurationsdaten in Azure App Service- oder Azure Functions-Anwendungen arbeiten, ohne Codeänderungen vorzunehmen. Die Azure-App-Konfiguration ist ein Azure-Dienst, mit dem Sie die Anwendungskonfiguration zentral verwalten können. Es ist auch ein effektives Tool für die Überwachung Ihrer Konfigurationswerte im Laufe der Zeit oder über versionen hinweg.

Gewähren des App-Zugriffs auf die App-Konfiguration

Um mit der Verwendung von App-Konfigurationsverweisen in App Service zu beginnen, erstellen Sie zuerst einen App-Konfigurationsspeicher. Anschließend erteilen Sie Ihrer App Berechtigungen, um auf die im Store gespeicherten Konfigurationsschlüssel-Wert-Paare zuzugreifen.

1. Befolgen Sie zum Erstellen eines App Configuration-Speichers den Schnellstart zu App Configuration.

2. Erstellen Sie eine verwaltete Identität für Ihre App.

   App-Konfigurationsverweise verwenden standardmäßig die vom System zugewiesene Identität der App, sie können jedoch eine vom Benutzer zugewiesene Identität angeben.

3. Gewähren Sie der Identität die richtigen Zugriffsberechtigungen für den App Configuration-Speicher. Aktualisieren Sie die Rollenzuweisungen für Ihren Speicher. Weisen Sie dieser Identität die Rolle „App Configuration-Datenleser“ für die Ressource zu.

Zugreifen auf den App-Konfigurationsspeicher mit einer vom Benutzer zugewiesenen Identität

In einigen Fällen müssen Apps möglicherweise auf die Konfiguration verweisen, wenn Sie sie erstellen, aber eine vom System zugewiesene Identität ist noch nicht verfügbar. In diesem Szenario können Sie im Voraus eine vom Benutzer zugewiesene Identität für den App-Konfigurationsspeicher erstellen .

Nachdem Sie berechtigungen für die vom Benutzer zugewiesene Identität erteilt haben, führen Sie die folgenden Schritte aus:

1. Weisen Sie der Anwendung die Identität zu.

2. Konfigurieren Sie die App so, dass sie diese Identität für App Configuration-Verweisvorgänge verwendet, indem Sie die Eigenschaft keyVaultReferenceIdentity auf die Ressourcen-ID der benutzerseitig zugewiesenen Identität festlegen. Obwohl keyVault im Namen der Eigenschaft enthalten ist, gilt die Identität auch für App-Konfigurationsverweise. Der Code lautet wie folgt:

   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}'}}"
   

Diese Konfiguration gilt für alle Verweise in der App.

Gewähren Sie Ihrer App Zugriff auf referenzierte Schlüsseltresore

Neben dem Speichern von unformatierten Konfigurationswerten verfügt die App-Konfiguration über ein eigenes Format zum Speichern von Azure Key Vault-Verweisen. Wenn der Wert eines App Configuration-Verweises ein Key Vault-Verweis im App Configuration-Speicher ist, benötigt Ihre App auch Berechtigungen für den Zugriff auf den referenzierten Schlüsseltresor.

So gewähren Sie Zugriff auf einen Schlüsseltresor für Ihre App

1. Identifizieren Sie die Identität, die Sie für den App Configuration-Verweis verwendet haben. Sie müssen derselben Identität Tresorzugriff zuweisen.

2. Erstellen Sie für diese Identität eine Zugriffsrichtlinie in Key Vault. Aktivieren Sie in dieser Richtlinie die Berechtigung zum Abrufen von Geheimnissen. Konfigurieren Sie die autorisierte Anwendung oder die applicationId Einstellungen nicht, da sie nicht mit einer verwalteten Identität kompatibel sind.

Verweissyntax

Ein App-Konfigurationsverweis hat die Form @Microsoft.AppConfiguration({referenceString}), wobei {referenceString} durch einen Wert ersetzt wird, wie in der folgenden Tabelle beschrieben.

Hier ist ein Beispiel für einen vollständigen Verweis, der Folgendes enthält Label:

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

Hier ist ein Beispiel, das nicht enthält Label:

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

Jede Konfigurationsänderung an der App, die zu einem Neustart der Website führt, verursacht einen sofortigen Abruf aller referenzierten Schlüssel-Wert-Paare aus dem App-Konfigurationsspeicher.

Abrufen von Anwendungseinstellungen aus App Configuration

Sie können App-Konfigurationsverweise als Werte für Anwendungseinstellungen verwenden, damit Sie Konfigurationsdaten in der App-Konfiguration statt in den Standortkonfigurationseinstellungen beibehalten können. Anwendungseinstellungen und App-Konfigurationsschlüssel/Wertpaare werden beide sicher im Ruhezustand verschlüsselt. Wenn Sie zentrale Konfigurationsverwaltungsfunktionen benötigen, fügen Sie der App-Konfiguration Konfigurationsdaten hinzu.

Um einen App Configuration-Verweis für eine App-Einstellung zu verwenden, legen Sie den Verweis als Wert der Einstellung fest. Ihre App kann wie gewohnt auf den Konfigurationswert über den Schlüssel verweisen. Es sind keine Codeänderungen erforderlich.

Überlegungen zur Einbindung von Azure Files

Apps können die WEBSITE_CONTENTAZUREFILECONNECTIONSTRING-Anwendungseinstellung verwenden, um Azure Files als Dateisystem einzubinden. Diese Einstellung verfügt über zusätzliche Überprüfungsprüfungen, um sicherzustellen, dass die App ordnungsgemäß gestartet werden kann. Die Plattform benötigt eine Inhaltsfreigabe in Azure Files und setzt einen Standardnamen voraus, es sei denn, ein Name wird über die WEBSITE_CONTENTSHARE-Einstellung angegeben. Bei Anforderungen, die diese Einstellungen ändern, versucht die Plattform zu überprüfen, ob die Inhaltsfreigabe vorhanden ist. Wenn die Freigabe nicht vorhanden ist, versucht die Plattform, sie zu erstellen. Wenn die Inhaltsfreigabe nicht gefunden oder erstellt werden kann, wird die Anforderung blockiert.

Wenn Sie App-Konfigurationsverweise für diese Einstellung verwenden, schlägt diese Überprüfung standardmäßig fehl, da die Verbindung selbst nicht aufgelöst werden kann, während die Plattform die eingehende Anforderung verarbeitet. Um dieses Problem zu vermeiden, können Sie die Überprüfung überspringen, indem Sie WEBSITE_SKIP_CONTENTSHARE_VALIDATION auf 1 setzen. Diese Einstellung umgeht sämtliche Überprüfungen, und die Inhaltsfreigabe wird nicht automatisch erstellt. Es liegt in Ihrer Verantwortung sicherzustellen, dass die Freigabe vorab erstellt wird.

Beim Erstellen der Site kann die Inhaltsfreigabe möglicherweise nicht eingebunden werden, wenn die Berechtigungen der verwalteten Identität nicht weitergegeben werden oder keine VNet-Integration eingerichtet wurde. Um das erforderliche Setup zu berücksichtigen, können Sie die Einrichtung von Azure Files auf einen späteren Zeitpunkt in der Bereitstellungsvorlage verschieben. Weitere Informationen finden Sie in der Azure Resource Manager-Bereitstellung im nächsten Abschnitt. App Service verwendet nur ein Standarddateisystem, bis Azure Files eingerichtet ist, und Dateien werden nicht kopiert. Stellen Sie sicher, dass während des Zwischenzeitraums keine Bereitstellungsversuche auftreten, bevor Azure Files bereitgestellt wird.

Azure Resource Manager-Bereitstellung

Wenn Sie Ressourcenbereitstellungen mithilfe von Arm-Vorlagen (Azure Resource Manager) automatisieren, müssen Sie ihre Abhängigkeiten möglicherweise in einer bestimmten Reihenfolge sequenzieren, damit App-Konfigurationsverweise funktionieren. In diesem Szenario müssen Sie Ihre Anwendungseinstellungen als eigene Ressource definieren, anstatt eine siteConfig Eigenschaft in der Websitedefinition zu verwenden. Die Website muss zuerst definiert werden, damit die vom System zugewiesene Identität mit der Website erstellt wird. Die verwaltete Identität wird dann in der Zugriffsrichtlinie verwendet.

Hier ist eine Beispielvorlage für eine Funktions-App mit App-Konfigurationsverweise:

{
    "$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"
            }
        }
    ]
}

Beheben von Problemen mit App Configuration-Verweisen

Wenn ein Verweis nicht ordnungsgemäß aufgelöst wird, wird stattdessen der Verweiswert verwendet. Eine Umgebungsvariable, die die Syntax @Microsoft.AppConfiguration(...) verwendet, wird erstellt. Der Verweis kann zu einem Fehler führen, da die Anwendung einen Konfigurationswert erwartet hat.

Dieser Fehler ist am häufigsten das Ergebnis einer Fehlkonfiguration der App-Konfigurationszugriffsrichtlinie. Es kann aber auch auftreten, wenn in der Referenz ein Syntaxfehler auftritt oder das Konfigurationsschlüssel-Wert-Paar nicht im Speicher vorhanden ist.

Verwandte Inhalte

• Verweisen auf Key Vault-Geheimnisse über App Service