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

Статья
04/17/2024

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

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

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

Создайте хранилище Конфигурации приложений, воспользовавшись кратким руководством.

Примечание.

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

Ссылки Конфигурации приложений будут по умолчанию использовать удостоверение, назначаемое приложению системой, но вы можете указать удостоверение, назначаемое пользователем.
Предоставьте созданному удостоверению необходимый набор прав доступа к хранилищу Конфигурации приложений. Обновите назначения ролей для хранилища. Необходимо назначить удостоверению роль App Configuration Data Reader с областью действия, содержащей ресурс.

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

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

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

Назначьте это удостоверение8 приложению, если вы этого еще не сделали.
Настройте приложение на использование этого удостоверения для операций со ссылками Конфигурации приложений, задав для свойства keyVaultReferenceIdentity идентификатор ресурса удостоверения, назначаемого пользователем. Хотя имя этого свойства содержит название Key Vault, удостоверение будет применяться и к ссылкам Конфигурации приложений.
```
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 в хранилище Конфигурация приложений, приложение также потребует разрешения на доступ к указанному хранилищу ключей.

Примечание.

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

Определите удостоверение, используемое для ссылки на Конфигурация приложений. Доступ к хранилищу должен быть предоставлен тому же удостоверению.
Создайте политику доступа в Key Vault для этого удостоверения. Включите в этой политике разрешения "Get" на получение секретов. Не устанавливайте "авторизованное приложение" или параметр applicationId, так как он не совместим с управляемым удостоверением.

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

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

Компоненты строки ссылки	Description
Endpoint=конечная_точка;	Endpoint — обязательная часть строки ссылки. Значение Endpoint должно содержать URL-адрес ресурса Конфигурации приложений.
Key=имя_ключа;	Key — обязательная часть строки ссылки. Значение Key должно быть именем ключа, который вы хотите назначить параметру приложения.
Label=метка	Компонент Label в строке ссылки является необязательным. Значением Label должна быть метка ключа, указанного в Key.

Например, полная ссылка, включающая Label, будет выглядеть следующим образом:

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

Другой вариант, без Label:

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

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

Примечание.

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

Получение параметров из Конфигурации приложений

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

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

Совет

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

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

При автоматизации развертывания ресурсов с помощью шаблонов Azure Resource Manager вам может потребоваться определенный порядок размещения зависимостей, без которого эта функция не будет работать. Учтите, что параметры приложения должны быть определены как отдельный ресурс, а не с помощью свойства 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"
            }
        }
    ]
}

Примечание.

В этом примере развертывание системы управления версиями зависит от параметров приложения. Такое поведение обычно считается небезопасным, так как обновление параметров приложения выполняется асинхронно. Но в этом примере оно будет синхронным, так как мы добавили параметр приложения WEBSITE_ENABLE_SYNC_UPDATE_SITE. Это означает, что развертывания системы управления версиями начнется только после того, как завершится обновление параметров приложения. Дополнительные параметры приложения описаны в разделе Переменные среды и параметры приложения в службе приложений Azure.

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

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

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

Следующие шаги

Ссылка на секреты Key Vault из Службы приложений

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

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

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

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

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

Получение параметров из Конфигурации приложений

Рекомендации по подключению службы "Файлы Azure"

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

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

Следующие шаги

Дополнительные ресурсы