이 문서에서는 코드를 변경하지 않고 Azure App Service 또는 Azure Functions 애플리케이션에서 구성 데이터를 사용하는 방법을 보여 줍니다. Azure App Configuration 은 애플리케이션 구성을 중앙에서 관리하는 데 사용할 수 있는 Azure 서비스입니다. 또한 시간이 지남에 따라 또는 릴리스에서 구성 값을 감사하는 효과적인 도구이기도 합니다.
App Configuration에 앱 액세스 권한 부여
App Service에서 App Configuration 참조를 사용하려면 먼저 App Configuration 저장소를 만들어야 합니다. 그런 다음 스토어에 있는 구성 키/값 쌍에 액세스할 수 있는 권한을 앱에 부여합니다.
App Configuration 저장소를 만들려면 App Configuration 빠른 시작을 완료합니다.
애플리케이션에 대한 관리 ID를 만듭니다.
App Configuration 참조는 기본적으로 앱의 시스템 할당 ID를 사용하지만 사용자가 할당한 ID를 지정할 수 있습니다.
ID에 App Configuration 저장소에 대한 올바른 액세스 권한 집합을 부여합니다. 저장소에 대한 역할 할당을 업데이트합니다. 리소스로 범위가 지정된 이 ID에 App Configuration 데이터 판독기 역할을 할당합니다.
사용자가 할당한 ID로 App Configuration 저장소에 액세스합니다.
경우에 따라 앱은 만들 때 구성을 참조해야 하지만 시스템 할당 ID는 아직 사용할 수 없습니다. 이 시나리오에서는 미리 App Configuration 저장소에 대한 사용자가 할당한 ID를 만들기할 수 있습니다.
사용자가 할당한 ID에 권한을 부여한 후 다음 단계를 완료합니다.
사용자의 애플리케이션에 ID를 할당합니다.
keyVaultReferenceIdentity속성을 사용자가 할당한 ID의 리소스 ID로 설정하여 App Configuration 참조 작업에 이 ID를 사용하도록 앱을 구성합니다. 속성 이름에keyVault가 포함되어 있지만 ID는 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}'}}"
이 구성은 앱의 모든 참조에 적용됩니다.
참조되는 키 자격 증명 모음에 대한 앱 액세스 권한 부여
원시 구성 값을 저장하는 것 외에도 App Configuration에는 Azure Key Vault 참조를 저장하기 위한 고유한 형식이 있습니다. App Configuration 참조 값이 App Configuration 저장소의 Key Vault 참조인 경우 앱에는 참조로 지정된 키 자격 증명에 액세스할 수 있는 권한도 있어야 합니다.
참고
App Configuration Key Vault 참조는App Service 및 Azure Functions Key Vault 참조와 혼동해서는 안 됩니다. 앱에서는 이러한 참조를 원하는 대로 조합하여 사용할 수 있지만 몇 가지 중요한 차이점이 있습니다. 네트워크 제한이 필요한 보관소가 있거나 앱이 정기적으로 최신 버전으로 업데이트되어야 하는 경우, App Configuration 참조를 사용하는 대신 App Service 및 Azure Functions 접근 방식을 고려하는 것이 좋습니다.
앱에 키 볼트에 대한 액세스 권한을 부여하려면 다음 단계를 따르세요.
App Configuration 참조에 사용한 ID를 식별합니다. 동일한 ID에 자격 증명 모음 액세스 권한을 부여해야 합니다.
해당 ID에 대한 Key Vault의 액세스 정책을 만듭니다. 이 정책에 대한 가져오기 비밀 권한을 사용하도록 설정합니다. 권한이 있는 애플리케이션 또는
applicationId설정은 관리 ID와 호환되지 않으므로 구성하지 마세요.
참조 구문
App Configuration 참조는 @Microsoft.AppConfiguration({referenceString}) 형식을 가지며 여기서 {referenceString}은 다음 표에 설명된 값으로 바뀝니다.
| 참조 문자열 부분 | 설명 |
|---|---|
Endpoint = <endpointURL> |
Endpoint (필수). App Configuration 리소스의 URL입니다. |
Key = <myAppConfigKey> |
Key (필수). 앱 설정에 할당할 키의 이름입니다. |
Label = <myKeyLabel> |
Label (선택 사항). 에 지정된 Key키 레이블의 값입니다. |
Label을 포함하는 완전한 참조의 예는 다음과 같습니다.
@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey; Label=myKeyLabel)
Label을 포함하지 않는 예는 다음과 같습니다.
@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey)
앱의 구성이 변경되어 사이트가 다시 시작되면 App Configuration 저장소에서 참조되는 모든 키/값 쌍이 즉시 다시 가져옵니다.
참고
App Configuration에서 키/값 쌍이 업데이트되는 경우 이러한 값의 자동 새로 고침 및 리페치는 현재 지원되지 않습니다.
App Configuration에서 원본 애플리케이션 설정
App Configuration 참조를 애플리케이션 설정 의 값으로 사용할 수 있으므로 사이트 구성 설정 대신 App Configuration에서 구성 데이터를 유지할 수 있습니다. 애플리케이션 설정 및 App Configuration 키/값 쌍은 모두 미사용 시 안전하게 암호화됩니다. 중앙 집중식 구성 관리 기능이 필요한 경우 App Configuration에 구성 데이터를 추가합니다.
앱 설정에 App Configuration 참조를 사용하려면 참조를 설정 값으로 설정합니다. 앱은 평소처럼 키를 통해 구성 값을 참조할 수 있습니다. 코드 변경은 필요하지 않습니다.
팁
App Configuration 참조를 사용하는 대부분의 애플리케이션 설정은 각 환경에 대해 별도의 저장소나 레이블을 가질 수 있도록 슬롯 설정으로 표시되어야 합니다.
Azure Files 탑재를 위한 고려 사항
앱은 WEBSITE_CONTENTAZUREFILECONNECTIONSTRING 애플리케이션 설정을 사용하여 Azure Files를 파일 시스템으로 탑재할 수 있습니다. 이 설정에는 앱이 제대로 시작될 수 있도록 추가적인 유효성 검사가 포함되어 있습니다. 플랫폼은 Azure Files 내에서 콘텐츠 공유를 사용하고 WEBSITE_CONTENTSHARE 설정에 지정하지 않는 한 기본 이름을 가정합니다. 이러한 설정을 수정하는 모든 요청에 대해 플랫폼은 콘텐츠 공유가 존재하는지 유효성을 검사하려고 시도합니다. 공유가 존재하지 않으면 플랫폼은 공유를 만들려고 시도합니다. 콘텐츠 공유를 찾거나 만들 수 없으면 요청이 차단됩니다.
이 설정에 App Configuration 참조를 사용하는 경우 플랫폼이 수신 요청을 처리하는 동안 연결 자체를 확인할 수 없기 때문에 이 유효성 검사는 기본적으로 실패합니다. 이 문제를 방지하려면 WEBSITE_SKIP_CONTENTSHARE_VALIDATION를 1로 설정하여 유효성 검사를 건너뛸 수 있습니다. 이 설정은 모든 검사를 바이패스하며, 콘텐츠 공유가 자동으로 만들어지지 않습니다. 공유가 미리 만들어졌는지 확인해야 합니다.
주의
유효성 검사를 건너뛰고 연결 문자열이나 콘텐츠 공유가 유효하지 않으면 앱이 제대로 시작되지 않고 HTTP 500 오류만 표시합니다.
사이트를 만들 때 관리 ID 권한이 전파되지 않거나 가상 네트워크 통합이 설정되지 않은 경우 콘텐츠 공유를 탑재하지 못할 수 있습니다. 배포 템플릿에서 나중에 필요한 설정을 수용할 때까지 Azure Files 설정을 연기할 수 있습니다. 자세한 내용은 다음 섹션의 Azure Resource Manager 배포를 참조하세요. Azure Files가 설정될 때까지 App Service는 기본 파일 시스템만 사용하며, 파일은 복사되지 않습니다. Azure Files가 탑재되기 전의 중간 기간 동안 배포 시도가 발생하지 않도록 합니다.
Azure Resource Manager 배포
ARM(Azure Resource Manager) 템플릿을 사용하여 리소스 배포를 자동화하는 경우 App Configuration 참조가 작동하도록 특정 순서로 종속성을 시퀀스해야 할 수 있습니다. 해당 시나리오에서는 사이트 정의에서 siteConfig 속성을 사용하는 대신 애플리케이션 설정을 자체 리소스로 정의해야 합니다. 시스템이 할당한 ID가 사이트와 함께 만들어지도록 먼저 사이트를 정의해야 합니다. 관리 ID는 액세스 정책에서 사용됩니다.
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"
}
}
]
}
참고
이 예제에서 원본 제어 배포는 애플리케이션 설정에 따라 다릅니다. 대부분의 시나리오에서는 앱 설정이 비동기적으로 업데이트되므로 이 시퀀스의 보안이 떨어집니다. 그러나 예제에 애플리케이션 설정이 WEBSITE_ENABLE_SYNC_UPDATE_SITE 포함되어 있으므로 업데이트가 동기적입니다. 소스 제어 배포는 애플리케이션 설정이 완전히 업데이트된 후에만 시작됩니다. 앱 설정에 대한 자세한 내용은 Azure App Service의 환경 변수 및 앱 설정을 참조하세요.
앱 구성 참조 문제 해결
참조가 제대로 해결되지 않으면 대신 참조 값이 사용됩니다. 구문을 @Microsoft.AppConfiguration(...) 사용하는 환경 변수가 만들어집니다. 애플리케이션이 구성 값을 기대하고 있었기 때문에 참조로 인해 오류가 발생할 수 있습니다.
이 오류는 가장 일반적으로 App Configuration 액세스 정책이 잘못 구성된 결과입니다. 그러나 참조에 구문 오류가 있거나 구성 키/값 쌍이 저장소에 없는 경우에도 발생할 수 있습니다.