Alkalmazáskonfigurációs hivatkozások használata az App Service-hez és az Azure Functionshez

Cikk
04/17/2024

Ez a témakör bemutatja, hogyan dolgozhat konfigurációs adatokkal az App Service-ben vagy az Azure Functions-alkalmazásban kódmódosítás nélkül. Azure-alkalmazás konfiguráció egy olyan szolgáltatás, amely központilag kezeli az alkalmazáskonfigurációt. Emellett hatékony naplózási eszköz a konfigurációs értékekhez az idő vagy a kiadások során.

Az alkalmazás hozzáférésének biztosítása az alkalmazáskonfigurációhoz

Az App Service alkalmazáskonfigurációs hivatkozásainak használatának megkezdéséhez először egy App Configuration Store-ra lesz szüksége, és engedélyt kell adnia az alkalmazásnak az áruházban található konfigurációs kulcsértékek eléréséhez.

Az alkalmazáskonfigurációs gyorsútmutatót követve hozzon létre egy Alkalmazáskonfigurációs áruházat.
Hozzon létre egy felügyelt identitást az alkalmazáshoz.

Az alkalmazáskonfigurációs hivatkozások alapértelmezés szerint az alkalmazás rendszer által hozzárendelt identitását használják, de megadhat egy felhasználó által hozzárendelt identitást.
Engedélyezze, hogy az újonnan létrehozott identitás megfelelő hozzáférési engedélyekkel rendelkezzen az Alkalmazáskonfigurációs áruházban. Frissítse az áruház szerepkör-hozzárendeléseit. Szerepkört fog hozzárendelni App Configuration Data Reader ehhez az identitáshoz, amely az erőforrásra terjed ki.

Hozzáférés az Alkalmazáskonfigurációs áruházhoz felhasználó által hozzárendelt identitással

Előfordulhat, hogy egyes alkalmazásoknak hivatkoznia kell a konfigurációra a létrehozáskor, amikor egy rendszer által hozzárendelt identitás még nem érhető el. Ezekben az esetekben előre létrehozhat egy felhasználó által hozzárendelt identitást, és hozzáférést adhat az Alkalmazáskonfigurációs áruházhoz. Kövesse az alábbi lépéseket a felhasználó által hozzárendelt identitás létrehozásához az App Configuration Store-hoz.

Miután engedélyt adott a felhasználó által hozzárendelt identitásra, kövesse az alábbi lépéseket:

Ha még nem tette meg, rendelje hozzá az identitást az alkalmazáshoz.
Konfigurálja az alkalmazást úgy, hogy ezt az identitást használja az alkalmazáskonfiguráció referenciaműveleteihez úgy, hogy a keyVaultReferenceIdentity tulajdonságot a felhasználó által hozzárendelt identitás erőforrás-azonosítójára állítja. Bár a tulajdonság neve keyVault, az identitás az alkalmazáskonfigurációs hivatkozásokra is érvényes lesz.
```
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}'}}"
```

Ez a konfiguráció az alkalmazás összes hivatkozására vonatkozik.

Az alkalmazás hozzáférésének biztosítása a hivatkozott kulcstartókhoz

A nyers konfigurációs értékek tárolása mellett a Azure-alkalmazás Configuration saját formátummal is rendelkezik a Key Vault-hivatkozások tárolásához. Ha az alkalmazáskonfigurációs referencia értéke egy Key Vault-referencia az App Configuration Store-ban, az alkalmazásnak engedéllyel kell rendelkeznie a megadott kulcstartó eléréséhez.

Feljegyzés

A Azure-alkalmazás Configuration Key Vault-referenciák fogalma nem tévesztendő össze az App Service és az Azure Functions Key Vault referenciáinak fogalmával. Az alkalmazás ezek bármilyen kombinációját használhatja, de van néhány fontos különbség. Ha a tárolót hálózatilag korlátozni kell, vagy szüksége van az alkalmazásra, hogy rendszeresen frissítsen a legújabb verziókra, fontolja meg az App Service és az Azure Functions közvetlen megközelítését az alkalmazáskonfigurációs referencia használata helyett.

Azonosítsa az alkalmazáskonfigurációs referenciaként használt identitást. A tárolóhoz való hozzáférést ugyanahhoz az identitáshoz kell biztosítani.
Hozzon létre egy hozzáférési szabályzatot a Key Vaultban ehhez az identitáshoz. Engedélyezze a "Get" titkos kód engedélyét ebben a szabályzatban. Ne konfigurálja az "engedélyezett alkalmazást" vagy applicationId a beállításokat, mert ez nem kompatibilis a felügyelt identitással.

Hivatkozás szintaxisa

Az alkalmazáskonfigurációs referencia az alábbi űrlapon @Microsoft.AppConfiguration({referenceString}){referenceString} található:

Hivatkozási sztringrészek	Leírás
Endpoint=endpoint;	A végpont a referenciasztring szükséges része. A végpont értékének rendelkeznie kell az alkalmazáskonfigurációs erőforrás URL-címével.
Key=keyName;	A kulcs a referenciasztring szükséges részét képezi. A kulcs értékének az alkalmazásbeállításhoz hozzárendelni kívánt kulcs nevének kell lennie.
Label=label	A Címke rész nem kötelező a hivatkozási sztringben. A címkének a Kulcsban megadott kulcs címkeértékének kell lennie

Egy teljes hivatkozás Label például a következőhöz hasonló:

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

Másik lehetőségként a következő nélkül Label:

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

Az alkalmazás webhely-újraindítást eredményező konfigurációs módosítása esetén az alkalmazáskonfigurációs áruházból azonnal újra lekérheti az összes hivatkozott kulcsértéket.

Feljegyzés

Ezeknek az értékeknek az automatikus frissítése/újbóli lekérése, ha a kulcsértékek frissültek az Alkalmazáskonfigurációban, jelenleg nem támogatott.

Forrásalkalmazás beállításai az App Configból

Az alkalmazáskonfigurációs hivatkozások az alkalmazásbeállítások értékeiként használhatók, így a helykonfiguráció helyett az Alkalmazáskonfigurációban tárolhatja a konfigurációs adatokat. Az alkalmazásbeállítások és az alkalmazáskonfiguráció kulcsértékei biztonságosan titkosítva vannak inaktív állapotban. Ha központosított konfigurációkezelési képességekre van szüksége, akkor a konfigurációs adatoknak az App Configba kell lépnie.

Ha alkalmazáskonfigurációs hivatkozást szeretne használni egy alkalmazásbeállításhoz, állítsa be a referenciát a beállítás értékeként. Az alkalmazás a szokásos módon hivatkozhat a konfigurációs értékre a kulcsán keresztül. Nincs szükség kódmódosításra.

Tipp.

Az alkalmazáskonfigurációs hivatkozásokat használó legtöbb alkalmazásbeállítást pontbeállításként kell megjelölni, mivel az egyes környezetekhez külön tárolókat vagy címkéket kell használnia.

Az Azure Files csatlakoztatásával kapcsolatos szempontok

Az alkalmazások az WEBSITE_CONTENTAZUREFILECONNECTIONSTRING alkalmazásbeállítással csatlakoztathatják az Azure Filest fájlrendszerként. Ez a beállítás további ellenőrzési ellenőrzésekkel biztosítja, hogy az alkalmazás megfelelően indítható legyen. A platform a tartalommegosztásra támaszkodik az Azure Filesban, és alapértelmezett nevet feltételez, kivéve, ha a WEBSITE_CONTENTSHARE beállítással meg van adva. A beállításokat módosító kérések esetén a platform megpróbálja ellenőrizni, hogy létezik-e ez a tartalommegosztás, és megkísérli létrehozni, ha nem. Ha nem találja vagy nem tudja létrehozni a tartalommegosztást, a kérés le lesz tiltva.

Ha alkalmazáskonfigurációs hivatkozásokat használ ehhez a beállításhoz, ez az ellenőrzés alapértelmezés szerint meghiúsul, mivel maga a kapcsolat nem oldható fel a bejövő kérés feldolgozása során. A probléma elkerülése érdekében kihagyhatja az érvényesítést az "1" beállítással WEBSITE_SKIP_CONTENTSHARE_VALIDATION . Ez a beállítás megkerüli az összes ellenőrzést, és a tartalommegosztás nem jön létre Önnek. Győződjön meg arról, hogy előre létrejött.

Figyelemfelhívás

Ha kihagyja az érvényesítést, és a kapcsolati sztring vagy a tartalommegosztás érvénytelen, az alkalmazás nem fog megfelelően elindulni, és csak HTTP 500-hibákat fog kiszolgálni.

A webhely létrehozása során előfordulhat, hogy a tartalommegosztás csatlakoztatásának kísérlete meghiúsulhat a felügyelt identitásengedélyek propagálása vagy a virtuális hálózati integráció nem beállítása miatt. Az Azure Files beállítását az üzembe helyezési sablon későbbi szakaszáig elhalaszthatja, hogy megfeleljen a szükséges beállításnak. További információért tekintse meg az Azure Resource Manager üzembe helyezését . Az App Service az Azure Files beállításáig egy alapértelmezett fájlrendszert használ, és a fájlok nem lesznek átmásolva, ezért győződjön meg arról, hogy az Azure Files csatlakoztatása előtti időközi időszakban nem történik üzembe helyezési kísérlet.

Az Azure Resource Manager üzembe helyezése

Ha azure Resource Manager-sablonokkal automatizálja az erőforrás-telepítéseket, előfordulhat, hogy a függőségeket egy adott sorrendbe kell rendeznie a funkció működéséhez. Fontos megjegyezni, hogy az alkalmazásbeállításokat saját erőforrásként kell definiálnia, nem pedig a webhelydefiníció egyik siteConfig tulajdonságát. Ennek az az oka, hogy először a helyet kell definiálni, hogy a rendszer által hozzárendelt identitás létrejönjön vele, és használható legyen a hozzáférési szabályzatban.

Az alábbiakban egy példa pszeudosablont talál egy alkalmazáskonfigurációs hivatkozásokkal rendelkező függvényalkalmazáshoz:

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

Feljegyzés

Ebben a példában a forrásvezérlő üzembe helyezése az alkalmazás beállításaitól függ. Ez általában nem biztonságos viselkedés, mivel az alkalmazásbeállítás frissítése aszinkron módon működik. Mivel azonban az WEBSITE_ENABLE_SYNC_UPDATE_SITE alkalmazásbeállítást is belefoglaltuk, a frissítés szinkronban van. Ez azt jelenti, hogy a forrásvezérlő üzembe helyezése csak az alkalmazásbeállítások teljes frissítése után kezdődik. További alkalmazásbeállításokért tekintse meg a környezeti változókat és az alkalmazásbeállításokat a Azure-alkalmazás Service-ben.

Alkalmazáskonfigurációs hivatkozások hibaelhárítása

Ha a hivatkozás nem oldódott meg megfelelően, a rendszer a referenciaértéket fogja használni. Az alkalmazásbeállításokhoz létrejön egy környezeti változó, amelynek az értéke szintaxist @Microsoft.AppConfiguration(...) használ. Ez hibát okozhat, mivel az alkalmazás ehelyett konfigurációs értéket várt.

Ez a hiba leggyakrabban az alkalmazáskonfiguráció hozzáférési szabályzatának helytelen konfigurációja miatt lehet. Ennek oka lehet azonban az is, hogy szintaxishiba történt a hivatkozásban, vagy a konfigurációs kulcs értéke nem szerepel a tárolóban.

Következő lépések

Key Vault-titkos kulcsok hivatkozása az App Service-ből

Megosztás a következőn keresztül:

Alkalmazáskonfigurációs hivatkozások használata az App Service-hez és az Azure Functionshez

Az alkalmazás hozzáférésének biztosítása az alkalmazáskonfigurációhoz

Hozzáférés az Alkalmazáskonfigurációs áruházhoz felhasználó által hozzárendelt identitással

Az alkalmazás hozzáférésének biztosítása a hivatkozott kulcstartókhoz

Hivatkozás szintaxisa

Forrásalkalmazás beállításai az App Configból

Az Azure Files csatlakoztatásával kapcsolatos szempontok

Az Azure Resource Manager üzembe helyezése

Alkalmazáskonfigurációs hivatkozások hibaelhárítása

Következő lépések

Visszajelzés

További források