Usar referências da Configuração de Aplicativos para os Serviço de Aplicativo do Azure e o Azure Functions

Este artigo mostra como trabalhar com dados de configuração no Serviço de Aplicativo do Azure ou aplicativos do Azure Functions sem fazer alterações de código. A Configuração de Aplicativos do Azure é um serviço do Azure que você pode usar para gerenciar centralmente a configuração do aplicativo. Também é uma ferramenta eficaz para auditar seus valores de configuração ao longo do tempo ou entre versões.

Conceder acesso de aplicativo à Configuração de Aplicativos

Para começar a usar referências de Configuração de Aplicativos no Serviço de Aplicativo, primeiro crie um repositório de Configuração de Aplicativos. Em seguida, você concede permissões ao seu aplicativo para acessar os pares de chave/valor de configuração que estão na loja.

1. Para criar um repositório de Configuração de Aplicativos, conclua o início rápido da Configuração de Aplicativos.

2. Crie uma Identidade gerenciada para seu aplicativo.

   As referências de Configuração de Aplicativo usam a identidade atribuída pelo sistema do aplicativo por padrão, mas você pode especificar uma identidade atribuída pelo usuário.

3. Conceda à identidade o conjunto correto de permissões de acesso para o repositório de Configuração de Aplicativos. Atualize as atribuições de função do repositório. Atribua a função Leitor de dados das Configuração de Aplicativos a essa identidade, com escopo sobre o recurso.

Acessar o repositório de Configuração de Aplicativos com uma identidade atribuída pelo usuário

Em alguns casos, os aplicativos podem precisar fazer referência à configuração quando você os cria, mas uma identidade atribuída pelo sistema ainda não está disponível. Nesse cenário, você pode criar uma identidade atribuída pelo usuário para o repositório de Configuração de Aplicativos com antecedência.

Depois de conceder permissões à identidade atribuída pelo usuário, conclua estas etapas:

1. Atribua a identidade ao seu aplicativo.

2. Configure o aplicativo para usar essa identidade para operações de referência da Configuração de Aplicativos configurando a propriedade keyVaultReferenceIdentity como a ID do recurso da identidade atribuída pelo usuário. Embora a propriedade tenha keyVault no nome, a identidade também se aplica às referências da Configuração de Aplicativos. O código é o seguinte:

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

Essa configuração se aplica a todas as referências no aplicativo.

Conceder ao aplicativo acesso a cofres de chaves referenciados

Além de armazenar valores brutos de configuração, a Configuração de Aplicativos tem seu próprio formato para armazenar referências do Azure Key Vault. Se o valor de uma referência de Configuração de Aplicativo for uma referência do Key Vault no repositório de Configuração de Aplicativos, seu aplicativo também deverá ter permissões para acessar o cofre de chaves especificado na referência.

Conceder ao aplicativo acesso a um cofre de chaves:

1. Identifique a identidade que você usou para a referência da Configuração de Aplicativos. Você deve conceder acesso ao cofre à mesma identidade.

2. Crie uma política de acesso no Key Vault para essa identidade. Ative a permissão secreta Get nesta política. Não defina o aplicativo autorizado ou as applicationId configurações porque elas não são compatíveis com uma identidade gerenciada.

Sintaxe de referência

Uma referência de Configuração de Aplicativo tem o formulário @Microsoft.AppConfiguration({referenceString}), em que {referenceString} é substituído por um valor, conforme descrito na tabela a seguir:

Aqui está um exemplo de uma referência completa que inclui Label:

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

Aqui está um exemplo que não inclui Label:

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

Qualquer alteração de configuração no aplicativo que resulta na reinicialização do site provoca uma atualização imediata de todos os pares chave/valor referenciados da loja de Configuração de Aplicativos.

Configurações do aplicativo de origem da Configuração de Aplicativos

Você pode usar referências de Configuração de Aplicativo como valores para as configurações do aplicativo para que você possa manter os dados de configuração na Configuração de Aplicativos em vez de nas configurações do site. As configurações do aplicativo e os pares chave/valor da Configuração de Aplicativos são ambos criptografados de forma segura em repouso. Se você precisar de recursos centralizados de gerenciamento de configuração, adicione dados de configuração à Configuração de Aplicativos.

Para usar uma referência da Configuração de Aplicativos para uma definição de aplicativo, defina a referência como o valor da definição. Seu aplicativo pode referenciar o valor de configuração por meio de sua chave como de costume. Nenhuma alteração de código é necessária.

Considerações para montar arquivos do Azure

Os aplicativos podem usar a configuração de aplicativo WEBSITE_CONTENTAZUREFILECONNECTIONSTRING para montar Arquivos do Azure como o sistema de arquivos. Essa configuração tem verificações de validação adicionais para garantir que o aplicativo possa ser iniciado corretamente. A plataforma depende de ter um compartilhamento de conteúdo dentro do Azure Files, e assume um nome padrão, a menos que um nome específico seja definido na configuração WEBSITE_CONTENTSHARE. Para quaisquer solicitações que modifiquem essas configurações, a plataforma tenta validar se o compartilhamento de conteúdo existe. Se o compartilhamento não existir, a plataforma tentará criar o compartilhamento. Se ela não puder localizar nem criar o compartilhamento de conteúdo, a solicitação será bloqueada.

Se você usar referências de Configuração de Aplicativo para essa configuração, essa verificação de validação falhará por padrão porque a conexão em si não pode ser resolvida enquanto a plataforma processa a solicitação de entrada. Para evitar esse problema, você pode ignorar a validação definindo WEBSITE_SKIP_CONTENTSHARE_VALIDATION como 1. Essa configuração ignora todas as verificações e o compartilhamento de conteúdo não é criado automaticamente. Você deve garantir que o compartilhamento seja criado com antecedência.

Quando você cria um site, a montagem do compartilhamento de conteúdo pode falhar se as permissões de identidade gerenciada não forem propagadas ou se a integração de rede virtual não estiver configurada. Você pode adiar a configuração de Arquivos do Azure até mais tarde no modelo de implantação para realizar essa configuração necessária. Para obter mais informações, consulte a implantação do Azure Resource Manager na próxima seção. O Serviço de Aplicativo usa apenas um sistema de arquivos padrão até que os Arquivos do Azure sejam configurados e os arquivos não sejam copiados. Verifique se nenhuma tentativa de implantação ocorre durante o período provisório antes que os Arquivos do Azure sejam montados.

Implantação do Azure Resource Manager

Se você automatizar implantações de recursos usando modelos do ARM (Azure Resource Manager), talvez seja necessário sequenciar suas dependências em uma ordem específica para fazer as referências de Configuração de Aplicativo funcionarem. Nesse cenário, você deve definir as configurações do aplicativo como seu próprio recurso em vez de usar uma propriedade siteConfig na definição do site. O site deve ser definido primeiro para que a identidade atribuída pelo sistema seja criada com o site. Em seguida, a identidade gerenciada é usada na política de acesso.

Aqui está um modelo de exemplo para um aplicativo de funções que tem referências de Configuração de Aplicativo:

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

Solucionar problemas de referências da Configuração de Aplicativos

Se uma referência não for resolvida corretamente, o valor de referência será usado. Uma variável de ambiente que usa a sintaxe @Microsoft.AppConfiguration(...) é criada. A referência pode causar um erro porque o aplicativo estava esperando um valor de configuração.

Esse erro geralmente é o resultado de uma configuração incorreta da política de acesso da Configuração de Aplicativo. Mas também pode ocorrer se houver um erro de sintaxe na referência ou se o par chave/valor de configuração não existir no repositório.

Conteúdo relacionado

• Referenciar segredos do Key Vault por meio do Serviço de Aplicativo