Dela via

Använda appkonfigurationsreferenser för Azure App Service och Azure Functions

Den här artikeln visar hur du arbetar med konfigurationsdata i Azure App Service- eller Azure Functions-program utan att göra några kodändringar. Azure App Configuration är en Azure-tjänst som du kan använda för att hantera programkonfigurationen centralt. Det är också ett effektivt verktyg för att granska dina konfigurationsvärden över tid eller mellan versioner.

Bevilja appåtkomst till App Configuration

Om du vill komma igång med att använda appkonfigurationsreferenser i App Service skapar du först ett appkonfigurationsarkiv. Sedan beviljar du behörighet till din app för att få åtkomst till de konfigurationsnyckel/värde-par som finns i butiken.

  1. Om du vill skapa ett appkonfigurationsarkiv slutför du snabbstarten Appkonfiguration.

  2. Skapa en hanterad identitet för ditt program.

    Appkonfigurationsreferenser använder appens systemtilldelade identitet som standard, men du kan ange en användartilldelad identitet.

  3. Bevilja identiteten rätt uppsättning åtkomstbehörigheter till App Configuration Store. Uppdatera rolltilldelningarna för ditt lager. Tilldela rollen App Configuration Data Reader till den här identiteten, som är begränsad till resursen.

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

I vissa fall kan appar behöva referera till konfigurationen när du skapar dem, men en systemtilldelad identitet är ännu inte tillgänglig. I det här scenariot kan du skapa en användartilldelad identitet för App Configuration Store i förväg.

När du har beviljat behörigheter till den användartilldelade identiteten slutför du följande steg:

  1. Tilldela en identitet till din applikation.

  2. 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. Här är koden:

    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 i appen.

Ge din app åtkomst till refererade nyckelvalv

Förutom att lagra raw-konfigurationsvärden har App Configuration ett eget format för lagring av Azure 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 i referensen.

Anmärkning

Key Vault-referenser för appkonfiguration bör inte förväxlas med Key Vault-referenser för App Service och Azure Functions. Din app kan använda valfri kombination av dessa referenser, men det finns några viktiga skillnader. 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 App Service- och Azure Functions-metoden i stället för att använda en appkonfigurationsreferens.

Så här ger du din app åtkomst till ett nyckelvalv:

  1. Identifiera den identitet som du använde för appkonfigurationsreferensen. Du måste ge samma identitet åtkomst till valvet.

  2. 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 de inte är kompatibla med en hanterad identitet.

Referenssyntax

En appkonfigurationsreferens har formuläret @Microsoft.AppConfiguration({referenceString}), där {referenceString} ersätts med ett värde enligt beskrivningen i följande tabell:

Referenssträngsdel beskrivning
Endpoint = <endpointURL> Endpoint (krävs). URL:en för appkonfigurationsresursen.
Key = <myAppConfigKey> Key (krävs). Namnet på nyckeln som du vill tilldela till appinställningen.
Label = <myKeyLabel> Label (valfritt). Värdet för nyckeletiketten som anges i Key.

Här är ett exempel på en fullständig referens som innehåller Label:

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

Här är ett exempel som inte innehåller Label:

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

Alla konfigurationsändringar i appen som resulterar i en platsomstart leder till en omedelbar reetch av alla refererade nyckel/värde-par från App Configuration Store.

Anmärkning

Automatisk uppdatering och refetch av dessa värden när nyckel/värde-paren uppdateras i App Configuration stöds inte för närvarande.

Inställningar för källprogram från App Configuration

Du kan använda appkonfigurationsreferenser som värden för programinställningar så att du kan behålla konfigurationsdata i App Configuration i stället för i platskonfigurationsinställningarna. Både programinställningar och nyckel/värde-par för appkonfiguration krypteras säkert i vila. Om du behöver centraliserade funktioner för konfigurationshantering lägger du till konfigurationsdata i App Configuration.

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

Tips

De flesta programinställningar som använder App Configuration-referenser bör markeras som slotinställningar så att du har separata lagringar eller etiketter för varje miljö.

Överväganden för att montera 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 starta korrekt. Plattformen förlitar sig på att ha en innehållsresurs i Azure Files och förutsätter ett standardnamn om inget anges i inställningen WEBSITE_CONTENTSHARE . För alla begäranden som ändrar de här inställningarna försöker plattformen verifiera att innehållsresursen finns. Om delningen inte finns försöker plattformen skapa delningen. Om den inte kan hitta eller skapa innehållsdelningen blockeras begäran.

Om du använder appkonfigurationsreferenser för den här inställningen misslyckas verifieringskontrollen som standard eftersom själva anslutningen inte kan matchas medan plattformen bearbetar den inkommande begäran. För att undvika det här problemet kan du hoppa över valideringen genom att ange WEBSITE_SKIP_CONTENTSHARE_VALIDATION till 1. Den här inställningen kringgår alla kontroller och innehållsdelningen skapas inte automatiskt. Du måste se till att delningen skapas i förväg.

Försiktighet

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

När du skapar en webbplats kan montering av innehållsdelningen misslyckas om behörigheter för hanterade identiteter inte tillämpas eller om 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-distributionen i nästa avsnitt. App Service använder bara ett standardfilsystem tills Azure Files har konfigurerats och filer kopieras inte över. Kontrollera att inga distributionsförsök görs under övergångsperioden innan Azure Files monteras.

Azure Resource Manager-driftsättning

Om du automatiserar resursdistributioner med hjälp av ARM-mallar (Azure Resource Manager) kan du behöva sekvensera dina beroenden i en specifik ordning för att appkonfigurationsreferenser ska fungera. I det scenariot måste du definiera dina programinställningar som en egen resurs i stället för att använda en siteConfig egenskap i webbplatsdefinitionen. Platsen måste definieras först så att den systemtilldelade identiteten skapas i samband med platsen. Den hanterade identiteten används sedan i åtkomstpolicyn.

Här är en exempelmall för en funktionsapp som har 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"
            }
        }
    ]
}

Anmärkning

I det här exemplet beror distributionen av källkontroll på programinställningarna. I de flesta fall är den här sekvensen mindre säker eftersom appinställningarna uppdateras asynkront. Men eftersom exemplet innehåller programinställningen WEBSITE_ENABLE_SYNC_UPDATE_SITE är uppdateringen synkron. Distributionen av källkontroll påbörjas först när programinställningarna har uppdaterats fullständigt. Mer information om appinställningar finns i Miljövariabler och appinställningar i Azure App Service.

Felsöka appkonfigurationsreferenser

Om en referens inte löses korrekt används referensvärdet i stället. En miljövariabel som använder syntaxen @Microsoft.AppConfiguration(...) skapas. Referensen kan orsaka ett fel eftersom programmet förväntade sig ett konfigurationsvärde.

Det här felet beror oftast på en felkonfiguration av appkonfigurationens åtkomstprincip. Men det kan också inträffa om det finns ett syntaxfel i referensen eller om konfigurationsnyckeln/värdeparet inte finns i lagret.

Relaterat innehåll