Usar as referências da Configuração de Aplicativos para o Serviço de Aplicativo e as funções do Azure (versão prévia)
Este tópico mostra como trabalhar com dados de configuração no aplicativo do Serviço de Aplicativo ou do Azure Functions sem exigir alterações de código. A Configuração de Aplicativos do Azure é um serviço para gerenciar de modo centralizado as configurações de aplicativo. Além disso, é uma ferramenta de auditoria eficaz para valores de configuração ao longo do tempo ou de versões.
Permitir que o aplicativo acesse a Configuração de Aplicativos
Para começar a usar referências de Configuração de Aplicativos no Serviço de Aplicativo, primeiro você precisará de um repositório de Configuração de Aplicativos e dar permissão ao aplicativo para acessar os pares chave-valor de configuração no repositório.
Crie um repositório de Configuração de Aplicativos seguindo o guia de início rápido da Configuração de Aplicativos.
Observação
As referências da Configuração de Aplicativos ainda não dão suporte a repositórios de configuração restritos à rede.
Crie uma Identidade gerenciada para seu aplicativo.
As referências à Configuração de Aplicativos usarão a identidade atribuída pelo sistema do aplicativo por padrão, mas você pode especificar uma identidade atribuída pelo usuário.
Habilite a identidade recém-criada para ter o conjunto certo de permissões de acesso no repositório da Configuração de Aplicativos. Atualize as atribuições de função do repositório. Você atribuirá a função
App Configuration Data Readera essa identidade, com escopo do recurso.
Acessar o repositório da Configuração de Aplicativos com uma identidade atribuída pelo usuário
Alguns aplicativos precisam referenciar a configuração no momento da criação, quando uma identidade atribuída pelo sistema ainda não está disponível. Nesses casos, uma identidade atribuída pelo usuário pode ser criada e receber acesso ao repositório da Configuração de Aplicativos com antecedência. Siga estas etapas para criar uma identidade atribuída pelo usuário para o repositório da Configuração de Aplicativos.
Depois de conceder permissões à identidade atribuída pelo usuário, siga estas etapas:
Atribua a identidade ao seu aplicativo, caso ainda não tenha feito isso.
Configure o aplicativo para usar essa identidade para operações de referência da Configuração de Aplicativos configurando a propriedade
keyVaultReferenceIdentitycomo a ID do recurso da identidade atribuída pelo usuário. Embora a propriedade tenha keyVault no nome, a identidade também será aplicada a referências da Configuração de Aplicativos.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 aplicará a todas as referências desse aplicativo.
Autorizando o seu aplicativo a acessar cofres de chaves referenciadas
Além de armazenar valores brutos de configuração, a Configuração de Aplicativos do Azure tem seu próprio formato para armazenar referências do Key Vault. Se o valor de uma referência da Configuração de Aplicativos for uma referência do Key Vault no repositório de Configuração de Aplicativos, seu aplicativo também precisará ter permissão para acessar o cofre de chaves que está sendo especificado.
Observação
O conceito de referências de Key Vault da Configuração de Aplicativos do Azure não deve ser confundido com o conceito de referências de Key Vault do Serviço de Aplicativo e do Azure Functions. Seu aplicativo pode usar qualquer uma dessas combinações, mas é necessário observar algumas diferenças importante. Se for necessário restringir o acesso à rede do seu cofre ou atualizar o aplicativo periodicamente para as versões mais recentes, considere usar a abordagem direto do Serviço de Aplicativo e do Azure Functions em vez de usar uma referência da Configuração de Aplicativos.
Identifique a identidade que você usou para a referência da Configuração de Aplicativos. Deve conceder acesso ao cofre para essa mesma identidade.
Crie uma política de acesso no Key Vault para essa identidade. Ative a permissão secreta "Obter" nesta política. Não defina o "aplicativo autorizado" ou as configurações
applicationId, pois isso não é compatível com uma identidade gerenciada.
Sintaxe de referência
Uma referência da Configuração de Aplicativos tem o formato @Microsoft.AppConfiguration({referenceString}), em que {referenceString} é substituído pela opção abaixo:
| Partes da cadeia de caracteres de referência | Descrição |
|---|---|
| Endpoint = endpoint; | O endpoint é a parte necessária da cadeia de caracteres de referência. O valor de endpoint deve ter a URL do recurso da Configuração de Aplicativos. |
| Key = keyName; | A chave forma a parte necessária da cadeia de caracteres de referência. O valor de Key deve ser o nome da chave que você deseja atribuir à configuração do aplicativo. |
| Label = label | A parte Label é opcional na cadeia de caracteres de referência. Label deve ser o valor do rótulo da chave especificada em Key |
Por exemplo, uma referência completa com Label seria semelhante ao seguinte:
@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey; Label=myKeysLabel)
Como alternativa, sem nenhum Label:
@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey)
Qualquer alteração de configuração no aplicativo que resulta em uma reinicialização do site causa uma nova busca imediata de todos os pares chave-valor referenciados do repositório da Configuração de Aplicativos.
Observação
Atualmente, não há suporte para atualização/busca automática desses valores quando os valores-chave foram atualizados na Configuração de Aplicativos.
Definições de Aplicativo de origem da Configuração de Aplicativos
As referências da Configuração de Aplicativos podem ser usadas como valores para Definições de Aplicativo, permitindo que você mantenha os dados de configuração nas Configuração de Aplicativos, não no site. Os pares chave-valor da Definições de Aplicativo e da Configuração de Aplicativos são criptografados com segurança em repouso. Se você precisar de funcionalidades centralizadas de gerenciamento de configuração, os dados de configuração deverão entrar na Configuração de Aplicativo.
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. O aplicativo pode referenciar o valor da configuração por meio da chave, como de costume. Nenhuma alteração de código é necessária.
Dica
A maioria das definições de aplicativos que usam referências da Configuração de Aplicativos deve ser marcada como configurações de slot, pois deve haver cofres separados para cada ambiente.
Considerações sobre montagem de 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 nos Arquivos do Azure e assume um nome padrão, a menos que um seja especificado por meio da configuração WEBSITE_CONTENTSHARE. Para todas as solicitações que modificam essas configurações, a plataforma tentará validar se esse compartilhamento de conteúdo existe e tentará criá-lo se não existir. Se ela não puder localizar nem criar o compartilhamento de conteúdo, a solicitação será bloqueada.
Ao usar referências da Configuração de Aplicativos para essa configuração, essa verificação de validação falhará por padrão, pois a conexão em si não poderá ser resolvida durante o processamento da solicitação de entrada. Para evitar esse problema, você pode ignorar a validação definindo WEBSITE_SKIP_CONTENTSHARE_VALIDATION como "1". Isso vai ignorar todas as verificações, e o compartilhamento de conteúdo não será criado para você. Você deve garantir que ele seja criado com antecedência.
Cuidado
Se você ignorar a validação e a cadeia de conexão ou o compartilhamento de conteúdo for inválido, o aplicativo não poderá iniciar corretamente e só atenderá a erros HTTP 500.
Como parte da criação do site, também é possível que a tentativa de montagem do compartilhamento de conteúdo falhe porque as permissões de identidade gerenciada não foram propagadas ou a integração de rede virtual não foi 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. Confira Modos de implantação do Azure Resource Manager para saber mais. O Serviço de Aplicativo usará um sistema de arquivos padrão até que o serviço Arquivos do Azure seja configurado e os arquivos não sejam copiados, portanto, garanta que nenhuma tentativa de implantação ocorra durante o período provisório até que o Arquivos do Azure seja montado.
Implantação do Azure Resource Manager
Ao automatizar implantações de recursos por meio dos modelos do Azure Resource Manager, talvez seja necessário sequenciar suas dependências em uma ordem específica para que esse recurso funcione. Observe que você precisará definir as definições de aplicativo como um recurso próprio, em vez de usar uma propriedade siteConfig na definição do site. Isso ocorre porque o site precisa ser definido primeiro para que a identidade atribuída pelo sistema seja criada com ele e possa ser usada na política de acesso.
Veja abaixo um exemplo de pseudo-modelo de um aplicativo de funções com referências da Configuração de Aplicativos:
{
"$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"
}
}
]
}
Observação
Neste exemplo, a implantação do controle de origem depende das configurações do aplicativo. Esse comportamento normalmente é inseguro, pois a atualização da configuração do aplicativo se comporta de maneira assíncrona. No entanto, como incluímos a configuração do aplicativo WEBSITE_ENABLE_SYNC_UPDATE_SITE, a atualização é síncrona. Isso significa que a implantação do controle de origem só será iniciada quando as configurações do aplicativo tiverem sido totalmente atualizadas. Para obter mais configurações de aplicativo, confira Variáveis de ambiente e configurações de aplicativo no Serviço de Aplicativo do Azure.
Solução de 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 em seu lugar. Isso significa que, para as definições de aplicativo, seria criada uma variável de ambiente cujo valor teria a sintaxe @Microsoft.AppConfiguration(...). Isso pode causar um erro, pois o aplicativo espera um valor de configuração.
O mais comum é que esse erro ocorra devido a uma configuração incorreta da política de acesso da Configuração de Aplicativos. No entanto, também pode ser devido a um erro de sintaxe na referência ou a um par chave-valor da Configuração não existente no repositório.