App Configuration-verwijzingen gebruiken voor App Service en Azure Functions (preview)
In dit onderwerp wordt beschreven hoe u kunt werken met configuratiegegevens in uw App Service- of Azure Functions-toepassing zonder dat er codewijzigingen nodig zijn. Azure-app Configuration is een service voor het centraal beheren van de toepassingsconfiguratie. Daarnaast is het een effectief controleprogramma voor uw configuratiewaarden in de loop van de tijd of releases.
Uw app toegang verlenen tot App Configuration
Als u aan de slag wilt met het gebruik van App Configuration-verwijzingen in App Service, hebt u eerst een App Configuration-archief nodig en geeft u uw app toestemming voor toegang tot de configuratiesleutelwaarden in de store.
Maak een App Configuration-archief door de quickstart voor App Configuration te volgen.
Notitie
App Configuration-verwijzingen bieden nog geen ondersteuning voor netwerkgebonden configuratiearchieven.
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.
Schakel de zojuist gemaakte identiteit in om de juiste set toegangsmachtigingen in het App Configuration-archief te hebben. Werk de roltoewijzingen voor uw winkel bij. U wijst de rol toe
App Configuration Data Readeraan deze identiteit, binnen het bereik van de resource.
Toegang tot App Configuration Store met een door de gebruiker toegewezen identiteit
Sommige apps moeten mogelijk verwijzen naar de configuratie tijdens het maken, wanneer een door het systeem toegewezen identiteit nog niet beschikbaar zou zijn. In deze gevallen kan vooraf een door de gebruiker toegewezen identiteit worden gemaakt en toegang krijgen tot het App Configuration-archief. Volg deze stappen om een door de gebruiker toegewezen identiteit te maken voor het App Configuration-archief.
Nadat u machtigingen hebt verleend voor de door de gebruiker toegewezen identiteit, voert u de volgende stappen uit:
Wijs de identiteit toe aan uw toepassing als u dat nog niet hebt gedaan.
Configureer de app voor het gebruik van deze identiteit voor referentiebewerkingen voor App Configuration door de
keyVaultReferenceIdentityeigenschap 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 App Configuration-verwijzingen.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 van deze app.
Uw app toegang verlenen tot sleutelkluizen waarnaar wordt verwezen
Naast het opslaan van onbewerkte configuratiewaarden heeft Azure-app Configuration een eigen indeling voor het opslaan van Key Vault-verwijzingen. Als de waarde van een App Configuration-verwijzing een Key Vault-verwijzing is in het App Configuration-archief, moet uw app ook gemachtigd zijn om toegang te krijgen tot de sleutelkluis die wordt opgegeven.
Notitie
Het concept Azure-app Configuration Key Vault-verwijzingen mag niet worden verward met het concept Van App Service- en Azure Functions Key Vault-verwijzingen. Uw app kan elke combinatie hiervan gebruiken, maar er zijn enkele belangrijke verschillen om rekening mee te houden. Als uw kluis moet worden beperkt door het netwerk of als u de app nodig hebt om periodiek bij te werken naar de nieuwste versies, kunt u overwegen de directe benadering van App Service en Azure Functions te gebruiken in plaats van een App Configuration-verwijzing te gebruiken.
Identificeer de identiteit die u hebt gebruikt voor de naslaginformatie over App Configuration. Toegang tot de kluis moet worden verleend aan dezelfde identiteit.
Maak een toegangsbeleid in Key Vault voor die identiteit. Schakel de geheime machtiging Ophalen in voor dit beleid. Configureer de 'geautoriseerde toepassing' of
applicationIdinstellingen niet, omdat dit niet compatibel is met een beheerde identiteit.
Verwijzingssyntaxis
Een App Configuration-verwijzing is van het formulier @Microsoft.AppConfiguration({referenceString}), waarbij {referenceString} deze wordt vervangen door hieronder:
| Verwijzingstekenreeksonderdelen | Beschrijving |
|---|---|
| Eindpunt=eindpunt; | Eindpunt is het vereiste onderdeel van de referentietekenreeks. De waarde voor Eindpunt moet de URL van uw App Configuration-resource hebben. |
| Key=keyName; | Sleutel vormt het vereiste deel van de referentietekenreeks. De waarde voor sleutel moet de naam zijn van de sleutel die u wilt toewijzen aan de app-instelling. |
| Label=label | Het labelonderdeel is optioneel in de referentietekenreeks. Label moet de waarde van het label zijn voor de sleutel die is opgegeven in Sleutel |
Een volledige verwijzing met Label ziet er bijvoorbeeld als volgt uit:
@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey; Label=myKeysLabel)
U kunt ook zonder Label:
@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey)
Elke configuratiewijziging in de app die resulteert in het opnieuw opstarten van een site, zorgt ervoor dat alle sleutelwaarden waarnaar wordt verwezen, onmiddellijk opnieuw worden opgehaald uit het App Configuration-archief.
Notitie
Deze waarden automatisch vernieuwen/opnieuw ophalen wanneer de sleutelwaarden zijn bijgewerkt in App Configuration, wordt momenteel niet ondersteund.
Brontoepassing Instellingen van app-configuratie
App Configuration-verwijzingen kunnen worden gebruikt als waarden voor application Instellingen, zodat u configuratiegegevens in App Configuration kunt bewaren in plaats van de siteconfiguratie. Sleutelwaarden voor toepassing Instellingen en App Configuration worden beide veilig versleuteld at rest. Als u gecentraliseerde configuratiebeheermogelijkheden nodig hebt, moeten configuratiegegevens naar app-configuratie gaan.
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.
Tip
De meeste toepassingsinstellingen die gebruikmaken van App Configuration-verwijzingen, moeten worden gemarkeerd als site-instellingen, omdat u afzonderlijke winkels of labels voor elke omgeving moet hebben.
Overwegingen voor 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 via de WEBSITE_CONTENTSHARE instelling. Voor aanvragen die deze instellingen wijzigen, probeert het platform te valideren of deze inhoudsshare bestaat en wordt geprobeerd deze te maken als dat niet het geval is. 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 tijdens het verwerken van de binnenkomende aanvraag. U kunt dit probleem voorkomen door de validatie over te slaan door in te stellen WEBSITE_SKIP_CONTENTSHARE_VALIDATION op '1'. Met deze instelling worden alle controles overgeslagen en wordt de inhoudsshare niet voor u gemaakt. Zorg ervoor dat deze vooraf is gemaakt.
Let op
Als u de validatie overslaat en de verbindingsreeks of inhoudsshare ongeldig is, kan de app niet goed worden gestart en worden alleen HTTP 500-fouten weergegeven.
Als onderdeel van het maken van de site is het ook mogelijk dat het koppelen van de inhoudsshare kan mislukken omdat machtigingen voor beheerde identiteiten niet worden doorgegeven of dat de integratie van het virtuele netwerk niet is ingesteld. U kunt het instellen van Azure Files uitstellen tot later in de implementatiesjabloon om ruimte te bieden voor de vereiste installatie. Zie Azure Resource Manager-implementatie voor meer informatie. App Service gebruikt een standaardbestandssysteem totdat Azure Files is ingesteld en bestanden worden niet gekopieerd, dus zorg ervoor dat er geen implementatiepogingen plaatsvinden tijdens de tussentijdse periode voordat Azure Files wordt gekoppeld.
Implementatie van Azure Resource Manager
Wanneer u resource-implementaties automatiseert via Azure Resource Manager-sjablonen, moet u mogelijk uw afhankelijkheden in een bepaalde volgorde rangschikken om deze functie te laten werken. Opmerking: u moet uw toepassingsinstellingen definiëren als hun eigen resource in plaats van een siteConfig eigenschap in de sitedefinitie te gebruiken. Dit komt doordat de site eerst moet worden gedefinieerd, zodat de door het systeem toegewezen identiteit wordt gemaakt en kan worden gebruikt in het toegangsbeleid.
Hieronder ziet u een voorbeeld van een pseudosjabloon 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. Dit is normaal gesproken onveilig gedrag, omdat de update van de app-instelling zich asynchroon gedraagt. Omdat we echter de WEBSITE_ENABLE_SYNC_UPDATE_SITE toepassingsinstelling hebben opgenomen, is de update synchroon. Dit betekent dat de implementatie van broncodebeheer pas begint zodra de toepassingsinstellingen volledig zijn bijgewerkt. Zie Omgevingsvariabelen en app-instellingen in Azure-app Service voor meer app-instellingen.
Problemen met app-configuratieverwijzingen oplossen
Als een verwijzing niet juist is opgelost, wordt de verwijzingswaarde gebruikt. Voor de toepassingsinstellingen wordt een omgevingsvariabele gemaakt waarvan de waarde de @Microsoft.AppConfiguration(...) syntaxis heeft. Het kan een fout veroorzaken, omdat de toepassing in plaats daarvan een configuratiewaarde verwachtte.
Deze fout kan meestal worden veroorzaakt door een onjuiste configuratie van het app-configuratiebeleid. Dit kan echter ook worden veroorzaakt door een syntaxisfout in de verwijzing of de configuratiesleutelwaarde die niet in het archief aanwezig is.