Использование ссылок на конфигурацию приложений для Службы приложений Azure и функций Azure

В этой статье показано, как работать с данными конфигурации в службе приложений Azure или приложениях Функций Azure без внесения изменений в код. Конфигурация приложений Azure — это служба Azure, которую можно использовать для централизованного управления конфигурацией приложений. Это также эффективный инструмент для аудита значений конфигурации со временем или между различными версиями.

Предоставление приложению доступа к конфигурации приложений

Чтобы приступить к использованию ссылок на конфигурацию приложений в Службе приложений, сначала создайте хранилище конфигурации приложений. Затем вы предоставляете приложению разрешения на доступ к парам ключей и значений конфигурации, которые находятся в магазине.

1. Чтобы создать хранилище конфигурации приложений, выполните краткое руководство по конфигурации приложений.

2. Создайте для приложения управляемое удостоверение.

   Ссылки на конфигурацию приложений по умолчанию используют назначаемое системой удостоверение, но вы можете указать удостоверение, назначаемое пользователем.

3. Предоставьте идентификации правильный набор разрешений доступа в хранилище конфигураций приложений. Обновите назначения ролей для вашего магазина. Назначьте этому удостоверению роль Читателя данных конфигурации приложения с областью действия, охватывающей ресурс.

Получите доступ к хранилищу конфигураций приложений с использованием пользовательской идентификации

В некоторых случаях приложениям может потребоваться ссылаться на конфигурацию при создании приложений, но системно назначенное удостоверение пока недоступно. В этом сценарии можно заранее создать назначаемое пользователем удостоверение для хранилища конфигурации приложений.

После предоставления разрешений на пользовательское удостоверение выполните следующие действия.

1. присвоить удостоверение вашему приложению.

2. Настройте приложение на использование этого удостоверения для операций со ссылками Конфигурации приложений, установив в свойство keyVaultReferenceIdentity идентификатор ресурса назначенного пользователем удостоверения. Хотя свойство имеет keyVault в имени, идентификатор также применяется к ссылкам на конфигурации приложений. Вот этот код:

   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}'}}"
   

Эта конфигурация применяется ко всем ссылкам в приложении.

Предоставление приложению доступа к хранилищам ключей, на которые ссылается ссылка

Помимо хранения необработанных значений конфигурации, конфигурация приложений имеет собственный формат для хранения ссылок Azure Key Vault. Если значение ссылки на конфигурацию приложений является ссылкой на Key Vault в магазине конфигурации приложений, приложение также должно иметь разрешения на доступ к хранилищу ключей, указанному в ссылке.

Чтобы предоставить приложению доступ к хранилищу ключей:

1. Определите идентификатор, который вы использовали для ссылки на конфигурацию приложения. Вы должны предоставить доступ к хранилищу тому же удостоверению.

2. Создайте политику доступа в Key Vault для этого удостоверения. Включите разрешение Get secret для этой политики. Не настраивайте авторизованное приложение или applicationId параметры, так как это несовместимо с управляемым удостоверением.

Синтаксис ссылок

Ссылка на конфигурацию приложений содержит форму @Microsoft.AppConfiguration({referenceString}), где {referenceString} заменяется значением, как описано в следующей таблице:

Ниже приведен пример полной ссылки, включающей Label:

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

Ниже приведен пример, который не содержит Label:

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

Любое изменение конфигурации в приложении, которое приводит к перезапуску сайта, вызывает немедленную повторную выборку всех ссылочных пар ключ/значение из хранилища конфигурации приложения.

Параметры исходного приложения из конфигурации приложений

Вы можете использовать ссылки на конфигурацию приложений в качестве значений для параметров приложения , чтобы сохранить данные конфигурации в конфигурации приложений вместо параметров конфигурации сайта. Параметры приложения и пары ключ/значение конфигурации приложения надежно шифруются в состоянии покоя. Если вам нужны централизованные возможности управления конфигурацией, добавьте данные конфигурации в конфигурацию приложений.

Чтобы использовать ссылку Конфигурации приложений в качестве параметра приложения, укажите эту ссылку в значении этого параметра. Приложение может ссылаться на значение конфигурации с помощью ключа, как обычно. Изменения кода не требуются.

Рекомендации по монтированию Azure Files

Приложения могут использовать параметр WEBSITE_CONTENTAZUREFILECONNECTIONSTRING приложения для подключения Azure Files в качестве файловой системы. Этот параметр содержит дополнительные проверки, чтобы убедиться, что приложение может запуститься правильно. Платформа опирается на контент-ресурс в Azure Files и предполагает имя по умолчанию, если не указано иное в параметре WEBSITE_CONTENTSHARE. Для любых запросов, изменяющих эти параметры, платформа пытается проверить, существует ли общий доступ к контенту. Если общая папка не существует, платформа пытается создать общую папку. Если невозможно обнаружить или создать общий доступ к контенту, запрос блокируется.

Если для этого параметра используются ссылки на конфигурацию приложений, проверка завершается ошибкой по умолчанию, так как само подключение не может быть разрешено, пока платформа обрабатывает входящий запрос. Чтобы избежать этой проблемы, можно пропустить проверку, присвоив WEBSITE_SKIP_CONTENTSHARE_VALIDATION значение 1. Этот параметр обходит все проверки, и общий доступ к содержимому не создается автоматически. Необходимо заранее создать ресурс для общего доступа.

При создании сайта монтаж общей папки содержимого может оказаться неудачным, если разрешения управляемого удостоверения не распространяются или если интеграция с виртуальной сетью не настроена. Вы можете отложить настройку Файлов Azure до более позднего этапа в шаблоне развертывания, чтобы выполнить необходимые требования. Дополнительные сведения см. в развертывании Azure Resource Manager в следующем разделе. Служба приложений использует только файловую систему по умолчанию, пока не будет настроена служба файлов Azure, а файлы не копируются. Убедитесь, что попытки развертывания не выполняются в течение промежуточного периода до подключения файлов Azure.

Развертывание Azure Resource Manager

При автоматизации развертываний ресурсов с помощью шаблонов Azure Resource Manager (ARM) может потребоваться настроить последовательность зависимостей в определенном порядке, чтобы ссылки на App Configuration работали. В этом сценарии необходимо определить параметры приложения в качестве собственного ресурса, а не использовать свойство siteConfig в определении сайта. Сначала необходимо определить сайт, чтобы удостоверение, назначаемое системой, могло быть создано вместе с сайтом. Затем управляемое удостоверение используется в политике доступа.

Ниже приведен пример шаблона для приложения-функции с ссылками на конфигурацию приложений:

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

Устранение неполадок со ссылками на конфигурацию приложений

Если ссылка не устранена должным образом, вместо этого используется значение ссылки. Создается переменная среды, использующая синтаксис @Microsoft.AppConfiguration(...) . Ссылка может вызвать ошибку, потому что приложение ожидало значения из конфигурации.

Эта ошибка чаще всего приводит к неправильной настройке политики доступа к конфигурации приложений. Но это также может произойти, если в ссылке возникла синтаксическая ошибка или если пара ключей и значений конфигурации не существует в хранилище.

Связанный контент

• Ссылка на секреты Key Vault из App Service