Alkalmazáskonfigurációs hivatkozások használata az App Service-hez és az Azure Functionshez (előzetes verzió)
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.
Feljegyzés
Az alkalmazáskonfigurációs hivatkozások még nem támogatják a hálózat által korlátozott konfigurációs tárolókat.
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 Readerehhez 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
keyVaultReferenceIdentitytulajdonsá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
applicationIda 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-Gépház az App Configból
Az alkalmazáskonfigurációs hivatkozások az Alkalmazás Gépház é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ás Gépház é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.