Verwenden von App Configuration-Verweisen für App Service und Azure Functions

Artikel
03/30/2023

Dieses Thema zeigt Ihnen, wie Sie mit Konfigurationsdaten in Ihrer App Service- oder Azure Functions-Anwendung arbeiten können, ohne dass Codeänderungen erforderlich sind. Azure App Configuration ist ein Dienst zum zentralen Verwalten der Anwendungskonfiguration. Darüber hinaus ist es ein effektives Überwachungstool für Ihre Konfigurationswerte im Zeit- oder Versionsverlauf.

Gewähren von App Configuration-Zugriff für Ihre App

Um mit der Verwendung von App Configuration-Verweisen in App Service zu beginnen, benötigen Sie zunächst einen App Configuration-Speicher und müssen dann Ihrer App die Berechtigung zum Zugriff auf die Konfigurationsschlüsselwerte im Speicher erteilen.

Erstellen Sie einen App Configuration-Speicher, indem Sie den Schnellstart zu App Configuration befolgen.
Erstellen Sie eine verwaltete Identität für Ihre App.

App Configuration-Verweise verwenden standardmäßig die systemseitig zugewiesene Identität der App. Sie können aber auch eine benutzerseitig zugewiesene Identität angeben.
Erteilen Sie der neu erstellten Identität die geeigneten Zugriffsberechtigungen für den App Configuration-Speicher. Aktualisieren Sie die Rollenzuweisungen für Ihren Speicher. Sie weisen dieser Identität die Rolle App Configuration Data Reader zu, deren Geltungsbereich die Ressource einschließt.

Zugreifen auf App Configuration-Speicher über eine benutzerseitig zugewiesene Identität

Einige Apps müssen zum Erstellungszeitpunkt auf eine Konfiguration verweisen, wenn noch keine systemseitig zugewiesene Identität verfügbar ist. In diesen Fällen kann eine benutzerseitig zugewiesene Identität erstellt werden, der im Voraus Zugriff auf den App Configuration-Speicher gewährt wird. Führen Sie die folgenden Schritte aus, um eine benutzerseitig zugewiesene Identität für den App Configuration-Speicher zu erstellen.

Nachdem Sie der benutzerseitig zugewiesenen Identität Berechtigungen erteilt haben, führen Sie die folgenden Schritte aus:

Weisen Sie die Identität Ihrer Anwendung zu, sofern noch nicht erfolgt.

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 der Name der Eigenschaft „keyVault“ enthält, gilt die Identität auch für App Configuration-Verweise.

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 aus dieser App.

Gewähren von App-Zugriff auf Schlüsseltresore, auf die verwiesen wird

Zusätzlich zum Speichern von Rohkonfigurationswerten verfügt Azure App Configuration über ein eigenes Format zum Speichern von Key Vault-Verweisen. Wenn der Wert eines App Configuration-Verweises ein Key Vault-Verweis im App Configuration-Speicher ist, muss Ihre App auch über die Berechtigung verfügen, auf den angegebenen Schlüsseltresor zuzugreifen.

Hinweis

Das Konzept der Key Vault-Verweise von Azure App Configuration darf nicht mit dem Konzept der Key Vault-Verweise von App Service und Azure Functions verwechselt werden. Ihre App kann eine beliebige Kombination dieser Verweise verwenden, es sind jedoch einige wichtige Unterschiede zu beachten. Wenn Ihr Tresor auf ein Netzwerk beschränkt werden muss oder Sie die App regelmäßig auf die neuesten Versionen aktualisieren müssen, sollten Sie den direkten Ansatz von App Service und Azure Functions statt eines App Configuration-Verweises verwenden.

Identifizieren Sie die Identität, die Sie für den App Configuration-Verweis verwendet haben. Der Zugriff auf den Tresor muss derselben Identität gewährt werden.
Erstellen Sie für diese Identität eine Zugriffsrichtlinie in Key Vault. Aktivieren Sie die „Get“-Geheimnisberechtigung für diese Richtlinie. Konfigurieren Sie nicht die Einstellungen „Autorisierte Anwendung“ oder applicationId, da dies mit einer verwalteten Identität nicht kompatibel ist.

Verweissyntax

Ein App Configuration-Verweis besitzt das Format @Microsoft.AppConfiguration({referenceString}), wobei {referenceString} wie folgt ersetzt wird:

Teile der Verweiszeichenfolge	Beschreibung
Endpoint=Endpunkt;	Endpoint ist der erforderliche Teil der Verweiszeichenfolge. Der Wert für Endpoint muss die URL Ihrer App Configuration-Ressource aufweisen.
Key=Schlüsselname;	Key ist der erforderliche Teil der Verweiszeichenfolge. Der Wert für Key muss dem Namen des Schlüssels entsprechen, den Sie der App-Einstellung zuweisen möchten.
Label=Bezeichnung	Label ist ein optionaler Teil in der Verweiszeichenfolge. Label muss dem Wert von „Label“ für den in Key angegebenen Schlüssel entsprechen.

Ein vollständiger Verweis mit Label kann beispielsweise wie folgt aussehen:

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

Alternativ ohne Label:

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

Konfigurationsänderungen an der App, die zu einem Websiteneustart führen, verursachen eine sofortige Neuabfrage aller referenzierten Schlüsselwerte aus dem App Configuration-Speicher.

Hinweis

Das automatische Aktualisieren oder erneute Abrufen dieser Werte bei einer Aktualisierung der Schlüsselwerte in App Configuration wird derzeit nicht unterstützt.

Einbinden von Anwendungseinstellungen aus App Config

App Configuration-Verweise können als Werte für Anwendungseinstellungen verwendet werden, sodass Sie Konfigurationsdaten in App Configuration statt in der Websitekonfiguration aufbewahren können. Anwendungseinstellungen und App Configuration-Schlüsselwerte werden im Ruhezustand sicher verschlüsselt. Wenn Sie zentrale Konfigurationsverwaltungsfunktionen benötigen, sollten die Konfigurationsdaten in App Config gespeichert werden.

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

Tipp

Die meisten Anwendungseinstellungen, die App Configuration-Verweise verwenden, sollten als Sloteinstellungen markiert werden, da Sie für jede Umgebung separate Speicher oder Bezeichnungen verwenden sollten.

Überlegungen zum Einbinden 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ü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, überprüft die Plattform, ob diese Inhaltsfreigabe vorhanden ist. Wenn dies nicht der Fall ist, wird versucht, sie zu erstellen. Wenn die Inhaltsfreigabe nicht gefunden oder erstellt werden kann, wird die Anforderung blockiert.

Wenn für diese Einstellung App Configuration-Verweise verwendet werden, schlägt diese Überprüfung standardmäßig fehl, weil die Verbindung selbst bei der Verarbeitung der eingehenden Anforderung nicht aufgelöst werden kann. Um dieses Problem zu vermeiden, können Sie die Überprüfung überspringen, indem Sie WEBSITE_SKIP_CONTENTSHARE_VALIDATION auf „1“ festlegen. Durch diese Einstellung werden alle Überprüfungen umgangen, und die Inhaltsfreigabe wird nicht für Sie erstellt. Stellen Sie sicher, dass sie im Voraus erstellt wird.

Achtung

Wenn Sie die Überprüfung überspringen und entweder die Verbindungszeichenfolge oder die Inhaltsfreigabe ungültig ist, kann die App nicht ordnungsgemäß gestartet werden und gibt nur HTTP 500-Fehler aus.

Im Rahmen der Erstellung der Website ist es auch möglich, dass der Einbindungsversuch der Inhaltsfreigabe fehlschlägt, weil Berechtigungen für verwaltete Identitäten nicht weitergegeben oder die VNet-Integration nicht 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 unter Azure Resource Manager-Bereitstellung. Bis zur Einrichtung von Azure Files verwendet App Service ein Standarddateisystem, und Dateien werden nicht kopiert. Daher müssen Sie sicherstellen, dass während des Übergangszeitraums keine Bereitstellungsversuche erfolgen, bevor Azure Files eingebunden wird.

Azure Resource Manager-Bereitstellung

Wenn Sie Ressourcenbereitstellungen über Azure Resource Manager-Vorlagen automatisieren, müssen Sie möglicherweise Ihre Abhängigkeiten in einer bestimmten Reihenfolge sortieren, damit diese Funktion funktioniert. Beachten Sie, dass Sie Ihre Anwendungseinstellungen als eigene Ressource definieren müssen, anstatt eine siteConfig-Eigenschaft in der Websitedefinition zu verwenden. Grund dafür ist, dass zuerst die Website definiert werden muss, damit die systemseitig zugeordnete Identität gleichzeitig erstellt und in der Zugriffsrichtlinie verwendet werden kann.

Nachfolgend finden Sie eine Beispiel-Pseudovorlage für eine Funktions-App mit App Configuration-Verweisen:

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

Hinweis

In diesem Beispiel hängt die Bereitstellung der Quellcodeverwaltung von den Anwendungseinstellungen ab. Dies ist normalerweise ein unsicheres Verhalten, da sich das App-Einstellungsupdate asynchron verhält. Da wir aber die Anwendungseinstellung WEBSITE_ENABLE_SYNC_UPDATE_SITE integriert haben, verläuft das Update synchron. Dies bedeutet, dass die Bereitstellung der Quellcodeverwaltung erst dann beginnt, wenn die Anwendungseinstellungen vollständig aktualisiert wurden. Weitere App-Einstellungen finden Sie unter Umgebungsvariablen und App-Einstellungen in Azure App Service.

Behandeln von Problemen mit App Configuration-Verweisen

Wird ein Verweis nicht ordnungsgemäß aufgelöst, wird stattdessen der Verweiswert verwendet. Für Anwendungseinstellungen wird eine Umgebungsvariable erstellt, deren Wert die @Microsoft.AppConfiguration(...)-Syntax aufweist. Dies kann zu einem Fehler führen, da die Anwendung stattdessen einen Konfigurationswert erwartet.

Meistens ist dieser Fehler auf eine Fehlkonfiguration der App Configuration-Zugriffsrichtlinie zurückzuführen. Er kann jedoch auch auftreten, weil im Verweis ein Syntaxfehler vorliegt oder der Konfigurationsschlüsselwert nicht im Speicher vorhanden ist.

Nächste Schritte

Verweisen auf Key Vault-Geheimnisse über App Service

Teilen über

Verwenden von App Configuration-Verweisen für App Service und Azure Functions

Gewähren von App Configuration-Zugriff für Ihre App

Zugreifen auf App Configuration-Speicher über eine benutzerseitig zugewiesene Identität

Gewähren von App-Zugriff auf Schlüsseltresore, auf die verwiesen wird

Verweissyntax

Einbinden von Anwendungseinstellungen aus App Config

Überlegungen zum Einbinden von Azure Files

Azure Resource Manager-Bereitstellung

Behandeln von Problemen mit App Configuration-Verweisen

Nächste Schritte

Feedback

Zusätzliche Ressourcen