Delen via

App Configuration-verwijzingen gebruiken voor Azure App Service en Azure Functions

In dit artikel wordt beschreven hoe u met configuratiegegevens in Azure App Service- of Azure Functions-toepassingen kunt werken zonder codewijzigingen aan te brengen. Azure App Configuration is een Azure-service die u kunt gebruiken om de configuratie van toepassingen centraal te beheren. Het is ook een effectief hulpprogramma voor het controleren van uw configuratiewaarden in de loop van de tijd of in verschillende releases.

App-toegang verlenen tot App Configuration

Als u wilt beginnen met het gebruik van App Configuration-verwijzingen in App Service, maakt u eerst een App Configuration-opslag. Vervolgens verleent u machtigingen aan uw app voor toegang tot de configuratiesleutel-/waardeparen die zich in de store bevinden.

  1. Voltooi de snelstartgids voor App Configuration om een App Configuration-opslag te maken.

  2. Maak een beheerde identiteit voor uw toepassing.

    App Configuration-verwijzingen gebruiken standaard de door het systeem toegewezen identiteit van de app, maar u kunt een door de gebruiker toegewezen identiteit opgeven.

  3. Verleent de identiteit de juiste toegangsmachtigingen voor de App Configuration opslag. Werk de roltoewijzingen voor uw winkel bij. Wijs de rol App Configuration-gegevenslezer toe aan deze identiteit, binnen het bereik van de resource.

Toegang tot het App Configuration-archief met een door de gebruiker toegewezen identiteit

In sommige gevallen moeten apps mogelijk verwijzen naar de configuratie wanneer u ze maakt, maar er is nog geen door het systeem toegewezen identiteit beschikbaar. In dit scenario kunt u vooraf een door de gebruiker toegewezen identiteit voor de App Configuration-opslag maken.

Nadat u machtigingen hebt verleend aan de door de gebruiker toegewezen identiteit, voert u de volgende stappen uit:

  1. Wijs de identiteit toe aan uw toepassing.

  2. Configureer de app voor het gebruik van deze identiteit voor referentiebewerkingen voor App Configuration door de keyVaultReferenceIdentity eigenschap in te stellen op de resource-id van de door de gebruiker toegewezen identiteit. Hoewel de eigenschap keyVault in de naam heeft, is de identiteit ook van toepassing op verwijzingen naar App Configuration. Hier volgt de 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}'}}"

Deze configuratie is van toepassing op alle verwijzingen in de app.

Verleen uw app toegang tot de genoemde sleutelkluizen

Naast het opslaan van onbewerkte configuratiewaarden heeft App Configuration een eigen indeling voor het opslaan van Azure Key Vault-verwijzingen. Als de waarde van een App Configuration-verwijzing een Key Vault-verwijzing is in de App Configuration-opslag, moet uw app ook machtigingen hebben voor toegang tot de sleutelkluis die is opgegeven in de referentie.

Notitie

Verwijzingen naar App Configuration Key Vault moeten niet worden verward met Verwijzingen naar App Service en Azure Functions Key Vault. Uw app kan elke combinatie van deze verwijzingen gebruiken, maar er zijn enkele belangrijke verschillen. Als uw kluis netwerkbeperking moet hebben of als u de app nodig hebt om periodiek bij te werken naar de nieuwste versies, kunt u overwegen om de App Service- en Azure Functions-benadering te gebruiken in plaats van een App Configuration-verwijzing te gebruiken.

Verleen uw app toegang tot een sleutelkluis:

  1. Identificeer de identiteit die u hebt gebruikt als referentie voor App Configuration. U moet de toegang tot de kluis verlenen aan dezelfde identiteit.

  2. Maak een toegangsbeleid in Key Vault voor die identiteit. Schakel de Geheim ophalen toestemming in voor dit beleid. Configureer de geautoriseerde toepassing of de applicationId instellingen niet omdat deze niet compatibel zijn met een beheerde identiteit.

Verwijzingssyntaxis

Een App Configuration-verwijzing heeft het formulier @Microsoft.AppConfiguration({referenceString}), waarbij {referenceString} deze wordt vervangen door een waarde zoals beschreven in de volgende tabel:

Onderdeel van de referentiestring Beschrijving
Endpoint = <endpointURL> Endpoint (vereist). De URL van uw App Configuration-resource.
Key = <myAppConfigKey> Key (vereist). De naam van de sleutel die u wilt toewijzen aan de app-instelling.
Label = <myKeyLabel> Label (optioneel). De waarde van het sleutellabel dat is opgegeven in Key.

Hier volgt een voorbeeld van een volledige verwijzing met:Label

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

Hier is een voorbeeld dat niet Label bevat:

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

Elke configuratiewijziging in de app die resulteert in het opnieuw opstarten van een site, veroorzaakt een onmiddellijke refetch van alle sleutel-/waardeparen waarnaar wordt verwezen vanuit het App Configuration-archief.

Notitie

Automatisch vernieuwen en opnieuw ophalen van deze waarden wanneer de sleutel-/waardeparen worden bijgewerkt in App Configuration wordt momenteel niet ondersteund.

Brontoepassingsinstellingen van App Configuration

U kunt App Configuration-verwijzingen gebruiken als waarden voor toepassingsinstellingen , zodat u configuratiegegevens in App Configuration kunt bewaren in plaats van in de siteconfiguratie-instellingen. Toepassingsinstellingen en sleutel-waardeparen van App Configuration zijn beide veilig versleuteld in rust. Als u gecentraliseerde configuratiebeheermogelijkheden nodig hebt, voegt u configuratiegegevens toe aan App Configuration.

Als u een App Configuration-verwijzing wilt gebruiken voor een app-instelling, stelt u de verwijzing in als de waarde van de instelling. Uw app kan naar de configuratiewaarde verwijzen via de bijbehorende sleutel zoals gebruikelijk. Er zijn geen codewijzigingen vereist.

Aanbeveling

De meeste applicatie-instellingen die gebruikmaken van App Configuration-verwijzingen moeten worden gemarkeerd als slotinstellingen, zodat u voor elke omgeving afzonderlijke winkels of labels hebt.

Overwegingen voor het koppelen van Azure Files

Apps kunnen de WEBSITE_CONTENTAZUREFILECONNECTIONSTRING toepassingsinstelling gebruiken om Azure Files als bestandssysteem te koppelen. Deze instelling bevat extra validatiecontroles om ervoor te zorgen dat de app correct kan worden gestart. Het platform is afhankelijk van het hebben van een inhoudsshare in Azure Files en er wordt uitgegaan van een standaardnaam, tenzij er een is opgegeven in de WEBSITE_CONTENTSHARE instelling. Voor aanvragen die deze instellingen wijzigen, probeert het platform te valideren dat de inhoudsshare bestaat. Als de share niet bestaat, probeert het platform de share te maken. Als de inhoudsshare niet kan worden gevonden of gemaakt, wordt de aanvraag geblokkeerd.

Als u App Configuration-verwijzingen voor deze instelling gebruikt, mislukt deze validatiecontrole standaard omdat de verbinding zelf niet kan worden opgelost terwijl het platform de binnenkomende aanvraag verwerkt. Om dit probleem te voorkomen, kunt u de validatie overslaan door de instelling in te stellen WEBSITE_SKIP_CONTENTSHARE_VALIDATION op 1. Met deze instelling worden alle controles overgeslagen en wordt de inhoudsshare niet automatisch gemaakt. U moet ervoor zorgen dat het deel vooraf wordt gemaakt.

Let op

Als u validatie overslaat en de verbindingsreeks of de inhoudsshare ongeldig is, kan de app niet goed worden gestart en worden alleen HTTP 500-fouten weergegeven.

Wanneer u een site maakt, kan het koppelen van de inhoudsopslag mislukken als beheerde identiteitsmachtigingen niet zijn doorgevoerd of als de integratie van het virtuele netwerk niet is geconfigureerd. U kunt het instellen van Azure Files uitstellen tot later in de implementatiesjabloon om ruimte te bieden voor de vereiste installatie. Zie de Implementatie van Azure Resource Manager in de volgende sectie voor meer informatie. App Service maakt alleen gebruik van een standaardbestandssysteem totdat Azure Files is ingesteld en bestanden niet worden gekopieerd. Zorg ervoor dat er tijdens de tussentijdse periode geen implementatiepogingen worden uitgevoerd voordat Azure Files wordt gekoppeld.

Implementatie van Azure Resource Manager

Als u resource-implementaties automatiseert met behulp van ARM-sjablonen (Azure Resource Manager), moet u mogelijk uw afhankelijkheden in een specifieke volgorde rangschikken om App Configuration-verwijzingen te laten werken. In dat scenario moet u uw toepassingsinstellingen definiëren als hun eigen resource in plaats van een siteConfig eigenschap in de sitedefinitie te gebruiken. De site moet eerst worden gedefinieerd, zodat de door het systeem toegewezen identiteit met de site kan worden gemaakt. De beheerde identiteit wordt vervolgens gebruikt in het toegangsbeleid.

Hier volgt een voorbeeldsjabloon voor een functie-app met app-configuratieverwijzingen:

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

Notitie

In dit voorbeeld is de implementatie van broncodebeheer afhankelijk van de toepassingsinstellingen. In de meeste scenario's is deze reeks minder veilig omdat app-instellingen asynchroon worden bijgewerkt. Maar omdat het voorbeeld de WEBSITE_ENABLE_SYNC_UPDATE_SITE toepassingsinstelling bevat, is de update synchroon. De implementatie van broncodebeheer begint pas nadat de toepassingsinstellingen volledig zijn bijgewerkt. Zie Omgevingsvariabelen en app-instellingen in Azure App Service voor meer informatie over app-instellingen.

Problemen met app-configuratieverwijzingen oplossen

Als een verwijzing niet juist is opgelost, wordt in plaats daarvan de referentiewaarde gebruikt. Er wordt een omgevingsvariabele gemaakt die gebruikmaakt van de syntaxis @Microsoft.AppConfiguration(...) . De verwijzing kan een fout veroorzaken omdat de toepassing een configuratiewaarde verwachtte.

Deze fout is meestal het gevolg van een onjuiste configuratie van het app-configuratiebeleid. Maar het kan ook gebeuren als er een syntaxisfout in de verwijzing staat of als het configuratiesleutel-waarde paar niet bestaat in de opslagplaats.

Verwante inhoud