Použití odkazů na App Configuration pro App Service a Azure Functions

Článek
04/17/2024

V tomto tématu se dozvíte, jak pracovat s konfiguračními daty ve službě App Service nebo aplikaci Azure Functions bez nutnosti změn kódu. Aplikace Azure Configuration je služba pro centrální správu konfigurace aplikace. Kromě toho je to efektivní nástroj pro auditování hodnot konfigurace v průběhu času nebo vydaných verzí.

Udělení přístupu aplikace ke službě App Configuration

Abyste mohli začít používat reference ke službě App Configuration ve službě App Service, budete nejdřív potřebovat App Configuration Store a poskytnout aplikaci oprávnění pro přístup ke konfiguračním hodnotám klíčů v obchodě.

Pomocí rychlého startu app Configuration vytvořte úložiště App Configuration.
Vytvořte spravovanou identitu pro vaši aplikaci.

Odkazy na konfiguraci aplikací budou ve výchozím nastavení používat identitu přiřazenou systémem aplikace, ale můžete zadat identitu přiřazenou uživatelem.
Povolte nově vytvořenou identitu, aby měla v App Configuration Storu správnou sadu přístupových oprávnění. Aktualizujte přiřazení rolí pro úložiště. App Configuration Data Reader K této identitě přiřadíte roli s vymezeným oborem prostředku.

Přístup ke Službě App Configuration Store s identitou přiřazenou uživatelem

Některé aplikace můžou při vytváření potřebovat odkazovat na konfiguraci, pokud by identita přiřazená systémem ještě nebyla dostupná. V těchto případech je možné předem vytvořit identitu přiřazenou uživatelem a získat přístup ke službě App Configuration Store. Podle těchto kroků vytvořte identitu přiřazenou uživatelem pro App Configuration Store.

Jakmile udělíte oprávnění k identitě přiřazené uživatelem, postupujte takto:

Pokud jste to ještě neudělali, přiřaďte identitu k aplikaci.

Nakonfigurujte aplikaci tak, aby používala tuto identitu pro referenční operace konfigurace aplikace nastavením vlastnosti na ID prostředku identity přiřazené uživatelem keyVaultReferenceIdentity . I když vlastnost má v názvu keyVault, identita se použije i na odkazy na 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}'}}"

Tato konfigurace se použije pro všechny odkazy z této aplikace.

Udělení přístupu aplikace k odkazovaným trezorům klíčů

Kromě ukládání nezpracovaných konfiguračních hodnot má Aplikace Azure Configuration vlastní formát pro ukládání odkazů na Key Vault. Pokud je hodnota odkazu na službu App Configuration odkazem na službu Key Vault v App Configuration Storu, bude muset mít vaše aplikace také oprávnění pro přístup k zadanému trezoru klíčů.

Poznámka:

Koncept odkazů služby Configuration Key Vault na Aplikace Azure by se neměl zaměňovat s konceptem odkazů na službu App Service a Azure Functions Key Vault. Vaše aplikace může používat libovolnou kombinaci, ale je potřeba si uvědomit několik důležitých rozdílů. Pokud je potřeba omezit trezor nebo potřebujete, aby se aplikace pravidelně aktualizovala na nejnovější verze, zvažte použití přímého přístupu služby App Service a Azure Functions místo odkazu na konfiguraci aplikace.

Identifikujte identitu, kterou jste použili pro referenční informace ke službě App Configuration. Přístup k trezoru musí být udělen stejné identitě.
Vytvořte zásadu přístupu ve službě Key Vault pro danou identitu. U této zásady povolte oprávnění k získání tajného kódu. Nekonfigurujte "autorizovanou aplikaci" ani applicationId nastavení, protože není kompatibilní se spravovanou identitou.

Syntaxe odkazů

Odkaz na App Configuration je ve formátu @Microsoft.AppConfiguration({referenceString}), kde {referenceString} se nahrazuje následujícím kódem:

Části referenčního řetězce	Popis
Endpoint=endpoint;	Koncový bod je požadovaná část referenčního řetězce. Hodnota pro koncový bod by měla mít adresu URL vašeho prostředku App Configuration.
Key=keyName;	Klíč tvoří požadovanou část referenčního řetězce. Hodnota pro klíč by měla být název klíče, který chcete přiřadit k nastavení aplikace.
Label=label	Část Popisek je volitelná v referenčním řetězci. Popisek by měl být hodnota Popisek pro klíč zadaný v klíči.

Například úplný odkaz s následujícím kódem Label by vypadal takto:

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

Alternativně bez jakýchkoli Label:

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

Jakákoli změna konfigurace aplikace, která vede k restartování webu, způsobí okamžité opětovné načtení všech odkazovaných hodnot klíčů z App Configuration Storu.

Poznámka:

Automatická aktualizace a opětovné načtení těchto hodnot, pokud byly hodnoty klíčů aktualizovány v konfiguraci aplikace, se v současné době nepodporuje.

Nastavení zdrojové aplikace z konfigurace aplikace

Odkazy na konfiguraci aplikací se dají použít jako hodnoty pro nastavení aplikace, takže místo konfigurace webu můžete uchovávat konfigurační data v Konfiguraci aplikace. Nastavení aplikace a hodnoty klíče konfigurace aplikace jsou bezpečně šifrované v klidovém stavu. Pokud potřebujete centralizované možnosti správy konfigurace, měla by konfigurační data přejít do konfigurace aplikace.

Pokud chcete použít odkaz na konfiguraci aplikace pro nastavení aplikace, nastavte odkaz jako hodnotu nastavení. Vaše aplikace může odkazovat na hodnotu Konfigurace prostřednictvím jejího klíče jako obvykle. Nejsou vyžadovány žádné změny kódu.

Tip

Většina nastavení aplikací používajících odkazy na App Configuration by měla být označena jako nastavení slotu, protože pro každé prostředí byste měli mít samostatná úložiště nebo popisky.

Důležité informace o připojení služby Azure Files

Aplikace můžou pomocí WEBSITE_CONTENTAZUREFILECONNECTIONSTRING nastavení aplikace připojit službu Azure Files jako systém souborů. Toto nastavení obsahuje další kontroly ověření, aby se zajistilo, že je možné aplikaci správně spustit. Platforma spoléhá na to, že má sdílenou složku obsahu ve službě Azure Files a předpokládá výchozí název, pokud ho nezadáte prostřednictvím WEBSITE_CONTENTSHARE nastavení. U všech požadavků, které tato nastavení upravují, se platforma pokusí ověřit, jestli tato sdílená složka obsahu existuje, a pokud ne, pokusí se ji vytvořit. Pokud sdílenou složku obsahu nemůžete najít nebo vytvořit, žádost se zablokuje.

Pokud pro toto nastavení použijete odkazy na službu App Configuration, tato kontrola ověření ve výchozím nastavení selže, protože samotné připojení se při zpracování příchozího požadavku nedá vyřešit. Pokud se chcete tomuto problému vyhnout, můžete ověření přeskočit nastavením WEBSITE_SKIP_CONTENTSHARE_VALIDATION na 1. Toto nastavení vynechá všechny kontroly a sdílená složka obsahu se pro vás nevytvořila. Měli byste se ujistit, že je vytvořený předem.

Upozornění

Pokud přeskočíte ověření a buď připojovací řetězec nebo sdílená složka obsahu jsou neplatné, aplikace nebude moct správně spustit a bude obsluhovat pouze chyby HTTP 500.

V rámci vytváření lokality je také možné, že pokus o připojení sdílené složky obsahu může selhat kvůli tomu, že se nešířila oprávnění spravované identity nebo se nenastavila integrace virtuální sítě. Nastavení služby Azure Files můžete odložit až později v šabloně nasazení tak, aby vyhovovala požadovanému nastavení. Další informace najdete v nasazení Azure Resource Manageru. Služba App Service bude používat výchozí systém souborů, dokud se nenastaví služba Azure Files a soubory se nezkopírují, takže se ujistěte, že během přechodného období před připojením služby Azure Files nedojde k žádným pokusům o nasazení.

Nasazení podle modelu Azure Resource Manager

Při automatizaci nasazení prostředků pomocí šablon Azure Resource Manageru možná budete muset sekvencovat závislosti v určitém pořadí, aby tato funkce fungovala. Nezapomeňte, že místo použití siteConfig vlastnosti v definici webu budete muset definovat nastavení aplikace jako vlastní prostředek. Důvodem je to, že lokalita musí být definována jako první, aby se s ní vytvořila identita přiřazená systémem a dá se použít v zásadách přístupu.

Níže je příklad pseudosou šablony pro aplikaci funkcí s odkazy na 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"
            }
        }
    ]
}

Poznámka:

V tomto příkladu nasazení správy zdrojového kódu závisí na nastavení aplikace. Toto chování je obvykle nebezpečné, protože se aktualizace nastavení aplikace chová asynchronně. Vzhledem k tomu, že jsme zahrnuli WEBSITE_ENABLE_SYNC_UPDATE_SITE nastavení aplikace, je aktualizace synchronní. To znamená, že nasazení správy zdrojového kódu začne jenom po úplné aktualizaci nastavení aplikace. Další nastavení aplikace najdete v tématu Proměnné prostředí a nastavení aplikace ve službě Aplikace Azure Service.

Řešení potíží s odkazy na konfiguraci aplikací

Pokud se odkaz nepřeloží správně, použije se místo toho hodnota odkazu. Pro nastavení aplikace by byla vytvořena proměnná prostředí, jejíž hodnota má @Microsoft.AppConfiguration(...) syntaxi. Může to způsobit chybu, protože aplikace místo toho očekávala konfigurační hodnotu.

Tato chyba může být nejčastěji způsobená chybnou konfigurací zásad přístupu ke konfiguraci aplikace. Důvodem může být také chyba syntaxe v odkazu nebo hodnota klíče konfigurace, která v úložišti neexistuje.

Další kroky

Odkaz na tajné kódy trezoru klíčů ze služby App Service

Sdílet prostřednictvím

Použití odkazů na App Configuration pro App Service a Azure Functions

Udělení přístupu aplikace ke službě App Configuration

Přístup ke Službě App Configuration Store s identitou přiřazenou uživatelem

Udělení přístupu aplikace k odkazovaným trezorům klíčů

Syntaxe odkazů

Nastavení zdrojové aplikace z konfigurace aplikace

Důležité informace o připojení služby Azure Files

Nasazení podle modelu Azure Resource Manager

Řešení potíží s odkazy na konfiguraci aplikací

Další kroky

Váš názor

Další materiály