Använda App Configuration-referenser för App Service och Azure Functions

Artikel
04/17/2024

Det här avsnittet visar hur du arbetar med konfigurationsdata i apptjänsten eller Azure Functions-programmet utan att kräva några kodändringar. Azure App Configuration är en tjänst för att centralt hantera programkonfiguration. Dessutom är det ett effektivt granskningsverktyg för dina konfigurationsvärden över tid eller versioner.

Bevilja din app åtkomst till App Configuration

För att komma igång med att använda appkonfigurationsreferenser i App Service behöver du först ett appkonfigurationsarkiv och ge din app behörighet att komma åt konfigurationsnyckelvärdena i butiken.

Skapa ett appkonfigurationsarkiv genom att följa snabbstarten Appkonfiguration.
Skapa en hanterad identitet för ditt program.

Appkonfigurationsreferenser använder appens systemtilldelade identitet som standard, men du kan ange en användartilldelad identitet.
Aktivera den nyligen skapade identiteten för att ha rätt uppsättning åtkomstbehörigheter i App Configuration Store. Uppdatera rolltilldelningarna för ditt lager. Du tilldelar App Configuration Data Reader rollen till den här identiteten, som är begränsad till resursen.

Få åtkomst till App Configuration Store med en användartilldelad identitet

Vissa appar kan behöva referera till konfigurationen vid skapandetillfället, när en systemtilldelad identitet ännu inte skulle vara tillgänglig. I dessa fall kan en användartilldelad identitet skapas och ges åtkomst till App Configuration Store i förväg. Följ de här stegen för att skapa användartilldelad identitet för App Configuration Store.

När du har beviljat behörighet till den användartilldelade identiteten följer du dessa steg:

Tilldela identiteten till ditt program om du inte redan har gjort det.

Konfigurera appen så att den använder den här identiteten för appkonfigurationsreferensåtgärder genom att ange keyVaultReferenceIdentity egenskapen till resurs-ID för den användartilldelade identiteten. Även om egenskapen har keyVault i namnet gäller identiteten även för appkonfigurationsreferenser.

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

Den här konfigurationen gäller för alla referenser från den här appen.

Bevilja din app åtkomst till refererade nyckelvalv

Förutom att lagra raw-konfigurationsvärden har Azure App Configuration ett eget format för lagring av Key Vault-referenser. Om värdet för en appkonfigurationsreferens är en Key Vault-referens i App Configuration Store måste din app också ha behörighet att komma åt nyckelvalvet som anges.

Kommentar

Key Vault-referenskonceptet för Azure App Configuration bör inte förväxlas med referenskonceptet För App Service och Azure Functions Key Vault. Din app kan använda valfri kombination av dessa, men det finns några viktiga skillnader att notera. Om ditt valv behöver vara nätverksbegränsat eller om du behöver appen för att regelbundet uppdatera till de senaste versionerna bör du överväga att använda direktmetoden App Service och Azure Functions i stället för att använda en appkonfigurationsreferens.

Identifiera den identitet som du använde för appkonfigurationsreferensen. Åtkomst till valvet måste beviljas samma identitet.
Skapa en åtkomstprincip i Key Vault för den identiteten. Aktivera behörigheten Hämta hemlighet för den här principen. Konfigurera inte det "auktoriserade programmet" eller applicationId inställningarna eftersom detta inte är kompatibelt med en hanterad identitet.

Referenssyntax

En appkonfigurationsreferens är av formuläret @Microsoft.AppConfiguration({referenceString}), där {referenceString} ersätts med nedan:

Referenssträngdelar	beskrivning
Endpoint=endpoint;	Slutpunkten är den del av referenssträngen som krävs. Värdet för Endpoint ska ha URL:en för din appkonfigurationsresurs.
Key=keyName;	Nyckeln utgör den del av referenssträngen som krävs. Värdet för Nyckel ska vara namnet på den nyckel som du vill tilldela till appinställningen.
Etikett=etikett	Etikettdelen är valfri i referenssträngen. Etiketten ska vara värdet för Etikett för nyckeln som anges i Nyckel

En fullständig referens med Label skulle till exempel se ut så här:

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

Alternativt utan :Label

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

Alla konfigurationsändringar i appen som resulterar i en platsomstart leder till en omedelbar återhämtning av alla refererade nyckelvärden från App Configuration Store.

Kommentar

Automatisk uppdatering/återhämtning av dessa värden när nyckelvärdena har uppdaterats i App Configuration stöds inte för närvarande.

Inställningar för källprogram från appkonfiguration

Appkonfigurationsreferenser kan användas som värden för programinställningar, så att du kan behålla konfigurationsdata i AppKonfiguration i stället för platskonfigurationen. Både programinställningar och appkonfigurationsnyckelvärden krypteras säkert i vila. Om du behöver centraliserade konfigurationshanteringsfunktioner bör konfigurationsdata gå till App Config.

Om du vill använda en appkonfigurationsreferens för en appinställning anger du referensen som värdet för inställningen. Appen kan referera till konfigurationsvärdet via dess nyckel som vanligt. Inga kodändringar krävs.

Dricks

De flesta programinställningar som använder appkonfigurationsreferenser bör markeras som platsinställningar, eftersom du bör ha separata butiker eller etiketter för varje miljö.

Överväganden för Montering av Azure Files

Appar kan använda programinställningen WEBSITE_CONTENTAZUREFILECONNECTIONSTRING för att montera Azure Files som filsystem. Den här inställningen har ytterligare verifieringskontroller för att säkerställa att appen kan startas korrekt. Plattformen förlitar sig på att ha en innehållsresurs i Azure Files och förutsätter ett standardnamn om inget anges via inställningen WEBSITE_CONTENTSHARE . För alla begäranden som ändrar de här inställningarna försöker plattformen verifiera om den här innehållsresursen finns och försöker skapa den om inte. Om den inte kan hitta eller skapa innehållsresursen blockeras begäran.

Om du använder appkonfigurationsreferenser för den här inställningen misslyckas den här verifieringskontrollen som standard eftersom själva anslutningen inte kan matchas när den inkommande begäran bearbetas. För att undvika det här problemet kan du hoppa över valideringen genom att ange WEBSITE_SKIP_CONTENTSHARE_VALIDATION "1". Den här inställningen kringgår alla kontroller och innehållsresursen skapas inte åt dig. Du bör se till att den skapas i förväg.

Varning

Om du hoppar över valideringen och antingen niska veze eller innehållsresursen är ogiltig kan appen inte starta korrekt och endast hantera HTTP 500-fel.

Som en del av skapandet av webbplatsen är det också möjligt att försök att montera innehållsresursen kan misslyckas på grund av att hanterade identitetsbehörigheter inte sprids eller att integreringen av det virtuella nätverket inte har konfigurerats. Du kan skjuta upp konfigurationen av Azure Files till senare i distributionsmallen för att hantera den nödvändiga konfigurationen. Mer information finns i Azure Resource Manager-distribution . App Service använder ett standardfilsystem tills Azure Files har konfigurerats och filer kopieras inte över så se till att inga distributionsförsök görs under mellantiden innan Azure Files monteras.

Azure Resource Manager-distribution

När du automatiserar resursdistributioner via Azure Resource Manager-mallar kan du behöva sekvensera dina beroenden i en viss ordning för att den här funktionen ska fungera. Observera att du måste definiera dina programinställningar som en egen resurs i stället för att använda en siteConfig egenskap i webbplatsdefinitionen. Det beror på att webbplatsen måste definieras först så att den systemtilldelade identiteten skapas med den och kan användas i åtkomstprincipen.

Nedan visas ett exempel på en pseudomall för en funktionsapp med appkonfigurationsreferenser:

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

Kommentar

I det här exemplet beror distributionen av källkontroll på programinställningarna. Det här är normalt osäkert beteende eftersom uppdateringen av appinställningen fungerar asynkront. Men eftersom vi har inkluderat programinställningen WEBSITE_ENABLE_SYNC_UPDATE_SITE är uppdateringen synkron. Det innebär att distributionen av källkontroll bara påbörjas när programinställningarna har uppdaterats helt. Fler appinställningar finns i Miljövariabler och appinställningar i Azure App Service.

Felsöka appkonfigurationsreferenser

Om en referens inte matchas korrekt används referensvärdet i stället. För programinställningarna skapas en miljövariabel vars värde har syntaxen @Microsoft.AppConfiguration(...) . Det kan orsaka ett fel eftersom programmet förväntade sig ett konfigurationsvärde i stället.

Det här felet kan oftast bero på en felkonfiguration av appkonfigurationens åtkomstprincip. Men det kan också bero på ett syntaxfel i referensen eller att nyckelvärdet Konfiguration inte finns i arkivet.

Nästa steg

Referera till Key Vault-hemligheter från App Service

Dela via

Använda App Configuration-referenser för App Service och Azure Functions

Bevilja din app åtkomst till App Configuration

Få åtkomst till App Configuration Store med en användartilldelad identitet

Bevilja din app åtkomst till refererade nyckelvalv

Referenssyntax

Inställningar för källprogram från appkonfiguration

Överväganden för Montering av Azure Files

Azure Resource Manager-distribution

Felsöka appkonfigurationsreferenser

Nästa steg

Feedback

Ytterligare resurser