Używanie odwołań do konfiguracji aplikacji dla usług App Service i Azure Functions
W tym temacie pokazano, jak pracować z danymi konfiguracji w aplikacji App Service lub Azure Functions bez konieczności wprowadzania jakichkolwiek zmian w kodzie. aplikacja systemu Azure Configuration to usługa do centralnego zarządzania konfiguracją aplikacji. Ponadto jest to skuteczne narzędzie do inspekcji wartości konfiguracji w czasie lub wydaniach.
Udzielanie aplikacji dostępu do usługi App Configuration
Aby rozpocząć korzystanie z odwołań usługi App Configuration w usłudze App Service, musisz najpierw mieć magazyn App Configuration i podać aplikacji uprawnienia dostępu do kluczy konfiguracji w sklepie.
Utwórz magazyn usługi App Configuration, postępując zgodnie z przewodnikiem Szybki start dotyczący usługi App Configuration.
Utwórz tożsamość zarządzaną dla aplikacji.
Odwołania do usługi App Configuration będą domyślnie używać tożsamości przypisanej przez system aplikacji, ale można określić tożsamość przypisaną przez użytkownika.
Włącz nowo utworzoną tożsamość, aby mieć odpowiedni zestaw uprawnień dostępu w magazynie App Configuration. Zaktualizuj przypisania ról dla sklepu. Przypiszesz
App Configuration Data Readerrolę do tej tożsamości w zakresie zasobu.
Uzyskiwanie dostępu do sklepu App Configuration Store przy użyciu tożsamości przypisanej przez użytkownika
Niektóre aplikacje mogą wymagać odwołania do konfiguracji w czasie tworzenia, gdy tożsamość przypisana przez system nie będzie jeszcze dostępna. W takich przypadkach można utworzyć tożsamość przypisaną przez użytkownika i uzyskać dostęp do magazynu App Configuration z wyprzedzeniem. Wykonaj następujące kroki, aby utworzyć tożsamość przypisaną przez użytkownika dla magazynu App Configuration.
Po udzieleniu uprawnień do tożsamości przypisanej przez użytkownika wykonaj następujące kroki:
Przypisz tożsamość do aplikacji, jeśli jeszcze tego nie zrobiono.
Skonfiguruj aplikację tak, aby korzystała z tej tożsamości dla operacji referencyjnych usługi App Configuration, ustawiając
keyVaultReferenceIdentitywłaściwość na identyfikator zasobu tożsamości przypisanej przez użytkownika. Chociaż właściwość ma kluczVault w nazwie, tożsamość będzie również stosowana do odwołań do usługi App Configuration.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}'}}"
Ta konfiguracja będzie stosowana do wszystkich odwołań z tej aplikacji.
Udzielanie aplikacji dostępu do odwołanych magazynów kluczy
Oprócz przechowywania nieprzetworzonych wartości konfiguracji aplikacja systemu Azure Configuration ma własny format przechowywania odwołań usługi Key Vault. Jeśli wartość odwołania do usługi App Configuration jest odwołaniem do usługi Key Vault w sklepie App Configuration, aplikacja będzie również musiała mieć uprawnienia dostępu do określonego magazynu kluczy.
Uwaga
Koncepcja referencyjna aplikacja systemu Azure Configuration Key Vault nie powinna być mylona z koncepcją referencyjną usługi App Service i usługi Azure Functions Key Vault. Aplikacja może używać dowolnej kombinacji tych funkcji, ale należy pamiętać o pewnych ważnych różnicach. Jeśli magazyn musi być ograniczony do sieci lub potrzebujesz aplikacji do okresowej aktualizacji do najnowszych wersji, rozważ użycie podejścia bezpośredniego usługi App Service i usługi Azure Functions zamiast używania odwołania do usługi App Configuration.
Zidentyfikuj tożsamość użytą do dokumentacji usługi App Configuration. Dostęp do magazynu musi być udzielany tej samej tożsamości.
Utwórz zasady dostępu w usłudze Key Vault dla tej tożsamości. Włącz uprawnienie "Pobierz" wpis tajny dla tych zasad. Nie należy konfigurować "autoryzowanej aplikacji" ani
applicationIdustawień, ponieważ nie jest to zgodne z tożsamością zarządzaną.
Składnia referencyjna
Odwołanie do usługi App Configuration ma postać @Microsoft.AppConfiguration({referenceString}), gdzie {referenceString} jest zastępowana poniższymi elementami:
| Części ciągu odwołania | opis |
|---|---|
| Endpoint=endpoint; | Punkt końcowy jest wymaganą częścią ciągu odwołania. Wartość punktu końcowego powinna mieć adres URL zasobu usługi App Configuration. |
| Key=keyName; | Klucz stanowi wymaganą część ciągu odwołania. Wartość klucza powinna być nazwą klucza, który chcesz przypisać do ustawienia Aplikacja. |
| Label=label | Część Etykieta jest opcjonalna w ciągu odwołania. Etykieta powinna być wartością Etykiety dla klucza określonego w kluczu |
Na przykład pełne odwołanie do Label elementu będzie wyglądać następująco:
@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey; Label=myKeysLabel)
Alternatywnie bez żadnego Labelelementu :
@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey)
Każda zmiana konfiguracji w aplikacji, która powoduje ponowne uruchomienie lokacji powoduje natychmiastowe ponowne pobranie wszystkich przywoływanych wartości klucza z magazynu App Configuration.
Uwaga
Automatyczne odświeżanie/ponowne pobieranie tych wartości, gdy wartości klucz-wartości zostały zaktualizowane w usłudze App Configuration, nie jest obecnie obsługiwane.
Ustawienia aplikacji źródłowej z konfiguracji aplikacji
Odwołania do usługi App Configuration mogą służyć jako wartości ustawień aplikacji, co umożliwia przechowywanie danych konfiguracji w usłudze App Configuration zamiast konfiguracji lokacji. Zarówno ustawienia aplikacji, jak i klucz-wartość konfiguracji aplikacji są bezpiecznie szyfrowane w spoczynku. Jeśli potrzebujesz scentralizowanych możliwości zarządzania konfiguracją, dane konfiguracji powinny przejść do konfiguracji aplikacji.
Aby użyć odwołania do usługi App Configuration dla ustawienia aplikacji, ustaw odwołanie jako wartość ustawienia. Aplikacja może odwoływać się do wartości Konfiguracja za pomocą klucza, jak zwykle. Nie są wymagane żadne zmiany kodu.
Napiwek
Większość ustawień aplikacji korzystających z odwołań usługi App Configuration powinna być oznaczona jako ustawienia miejsca, ponieważ powinny istnieć oddzielne magazyny lub etykiety dla każdego środowiska.
Zagadnienia dotyczące instalowania usługi Azure Files
Aplikacje mogą używać WEBSITE_CONTENTAZUREFILECONNECTIONSTRING ustawienia aplikacji do instalowania usługi Azure Files jako systemu plików. To ustawienie ma dodatkowe kontrole poprawności, aby upewnić się, że aplikacja może być poprawnie uruchomiona. Platforma korzysta z udziału zawartości w usłudze Azure Files i zakłada domyślną nazwę, chyba że zostanie określona za pośrednictwem WEBSITE_CONTENTSHARE ustawienia. W przypadku żądań modyfikujących te ustawienia platforma podejmie próbę zweryfikowania, czy ten udział zawartości istnieje, i spróbuje go utworzyć, jeśli nie. Jeśli nie można zlokalizować ani utworzyć udziału zawartości, żądanie zostanie zablokowane.
Jeśli używasz odwołań do usługi App Configuration dla tego ustawienia, to sprawdzanie poprawności nie powiedzie się domyślnie, ponieważ samo połączenie nie może zostać rozwiązane podczas przetwarzania żądania przychodzącego. Aby uniknąć tego problemu, możesz pominąć walidację, ustawiając wartość WEBSITE_SKIP_CONTENTSHARE_VALIDATION "1". To ustawienie spowoduje obejście wszystkich kontroli, a udział zawartości nie zostanie utworzony dla Ciebie. Upewnij się, że został utworzony z wyprzedzeniem.
Uwaga
Jeśli pominiesz walidację i parametry połączenia lub udział zawartości są nieprawidłowe, aplikacja nie będzie mogła uruchomić poprawnie i będzie obsługiwać tylko błędy HTTP 500.
W ramach tworzenia lokacji możliwe jest również, że próba instalowania udziału zawartości może zakończyć się niepowodzeniem z powodu braku propagacji uprawnień tożsamości zarządzanej lub nie skonfigurowano integracji z siecią wirtualną. Konfigurowanie usługi Azure Files można odroczyć do późniejszego użycia w szablonie wdrożenia, aby dostosować je do wymaganej konfiguracji. Aby dowiedzieć się więcej, zobacz Wdrażanie usługi Azure Resource Manager. Usługa App Service będzie używać domyślnego systemu plików do momentu skonfigurowania usługi Azure Files, a pliki nie zostaną skopiowane, dlatego upewnij się, że żadne próby wdrożenia nie zostaną wykonane w okresie przejściowym przed zainstalowaniem usługi Azure Files.
Wdrożenie usługi Azure Resource Manager
Podczas automatyzowania wdrożeń zasobów za pomocą szablonów usługi Azure Resource Manager może być konieczne sekwencjonowanie zależności w określonej kolejności, aby ta funkcja działała. Należy jednak zdefiniować ustawienia aplikacji jako własny zasób, zamiast używać siteConfig właściwości w definicji witryny. Jest to spowodowane tym, że lokacja musi być najpierw zdefiniowana, aby tożsamość przypisana przez system została utworzona za jej pomocą i może być używana w zasadach dostępu.
Poniżej przedstawiono przykładowy pseudo-szablon aplikacji funkcji z odwołaniami do usługi App Configuration:
{
"$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"
}
}
]
}
Uwaga
W tym przykładzie wdrożenie kontroli źródła zależy od ustawień aplikacji. Jest to zwykle niebezpieczne zachowanie, ponieważ aktualizacja ustawień aplikacji zachowuje się asynchronicznie. Jednak ponieważ uwzględniliśmy WEBSITE_ENABLE_SYNC_UPDATE_SITE ustawienie aplikacji, aktualizacja jest synchroniczna. Oznacza to, że wdrożenie kontroli źródła rozpocznie się dopiero po pełnej aktualizacji ustawień aplikacji. Aby uzyskać więcej ustawień aplikacji, zobacz Zmienne środowiskowe i ustawienia aplikacji w usłudze aplikacja systemu Azure Service.
Rozwiązywanie problemów z odwołaniami do konfiguracji aplikacji
Jeśli odwołanie nie zostanie poprawnie rozpoznane, zamiast tego zostanie użyta wartość odwołania. W przypadku ustawień aplikacji zostanie utworzona zmienna środowiskowa, której wartość ma składnię @Microsoft.AppConfiguration(...) . Może to spowodować błąd, ponieważ aplikacja oczekiwała wartości konfiguracji.
Najczęściej ten błąd może być spowodowany błędną konfiguracją zasad dostępu do konfiguracji aplikacji. Może to być jednak spowodowane błędem składniowym w odwołaniu lub wartości klucz-konfiguracja, która nie istnieje w magazynie.