Compartir a través de

Uso de referencias de App Configuration para Azure App Service y Azure Functions

En este artículo se muestra cómo trabajar con datos de configuración en aplicaciones de Azure App Service o Azure Functions sin realizar ningún cambio en el código. Azure App Configuration es un servicio de Azure que puede usar para administrar de forma centralizada la configuración de la aplicación. También es una herramienta eficaz para auditar los valores de configuración a lo largo del tiempo o entre versiones.

Conceder acceso de la aplicación a App Configuration

Para empezar a usar referencias de App Configuration en App Service, primero debe crear una tienda de App Configuration. A continuación, se conceden permisos a su aplicación para acceder a los pares clave-valor de configuración que se encuentran en el almacén.

  1. Para crear un almacén de App Configuration, complete el inicio rápido de App Configuration.

  2. Cree una identidad administrada para la aplicación.

    Las referencias de App Configuration usan la identidad asignada por el sistema de la aplicación de forma predeterminada, pero puede especificar una identidad asignada por el usuario.

  3. Conceda a la identidad el conjunto correcto de permisos de acceso al almacén de App Configuration. Actualice las asignaciones de roles del almacén. Asigne el rol Lector de datos de App Configuration a esta identidad, con ámbito sobre el recurso.

Acceso al almacén de App Configuration con una identidad asignada por el usuario

En algunos casos, es posible que las aplicaciones necesiten hacer referencia a la configuración al crearlas, pero una identidad asignada por el sistema aún no está disponible. En este escenario, puede crear una identidad asignada al usuario para la tienda de Configuración de Aplicaciones por adelantado.

Después de conceder permisos a la identidad asignada por el usuario, complete estos pasos:

  1. Asigne la identidad a la aplicación.

  2. Configure la aplicación para que use esta identidad en las operaciones de referencias de App Configuration estableciendo la propiedad keyVaultReferenceIdentity en el identificador de recurso de la identidad asignada por el usuario. Aunque la propiedad incluya keyVault en el nombre, la identidad también se aplica a las referencias de App Configuration. Este es el código:

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

Esta configuración se aplica a todas las referencias de la aplicación.

Concesión de acceso a la aplicación a los almacenes de claves con referencia

Además de almacenar valores de configuración sin procesar, App Configuration tiene su propio formato para almacenar referencias de Azure Key Vault. Si el valor de una referencia de App Configuration es una referencia de Key Vault en el almacén de App Configuration, la aplicación también debe tener permisos para acceder al almacén de claves especificado en la referencia.

Nota:

Las referencias de Key Vault de App Configuration no deben confundirse con las referencias de App Service y Azure Functions Key Vault. La aplicación puede usar cualquier combinación de estas referencias, pero hay algunas diferencias importantes. Si el almacén debe estar restringido a la red o necesita que la aplicación actualice periódicamente a las versiones más recientes, considere la posibilidad de usar el enfoque de App Service y Azure Functions en lugar de usar una referencia de App Configuration.

Para conceder a la aplicación acceso a un almacén de claves:

  1. Identifique la identidad que usó para la referencia de App Configuration. Debe conceder acceso al almacén a la misma identidad.

  2. Cree una directiva de acceso en Key Vault para esa identidad. Habilite el permiso secreto Get en esta directiva. No configure la aplicación autorizada ni la applicationId configuración porque no son compatibles con una identidad administrada.

Sintaxis de referencia

Una referencia de App Configuration tiene el formato @Microsoft.AppConfiguration({referenceString}), donde {referenceString} se reemplaza por un valor como se describe en la tabla siguiente:

Parte de cadena de referencia Descripción
Endpoint = <endpointURL> Endpoint (obligatorio). La URL del recurso de configuración de aplicaciones.
Key = <myAppConfigKey> Key (obligatorio). Nombre de la clave que quiere asignar a la configuración de la aplicación.
Label = <myKeyLabel> Label (opcional). Valor de la etiqueta de clave especificada en Key.

Este es un ejemplo de una referencia completa que incluye Label:

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

Este es un ejemplo que no incluye Label:

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

Cualquier cambio de configuración en la aplicación provoca un reinicio del sitio que provoca una captura inmediata de todos los pares clave-valor a los que se hace referencia desde el almacén de App Configuration.

Nota:

La actualización y recuperación automáticas de estos valores cuando los pares clave-valor se actualizan en App Configuration no están admitidas actualmente.

Obtener la configuración de la aplicación desde App Configuration

Puede usar referencias de App Configuration como valores para la configuración de la aplicación para poder mantener los datos de configuración en App Configuration en lugar de en la configuración del sitio. La configuración de la aplicación y los pares clave-valor de App Configuration se cifran de forma segura en reposo. Si necesita funcionalidades de administración de configuración centralizadas, agregue datos de configuración a App Configuration.

Para usar una referencia de App Configuration para una configuración de la aplicación, establezca la referencia como valor de la configuración. La aplicación puede hacer referencia al valor de configuración mediante su clave como es habitual. No se requiere ningún cambio de código.

Sugerencia

La mayoría de las opciones de configuración de la aplicación que usan referencias de App Configuration deben marcarse como valores de ranura para que tenga almacenes o etiquetas independientes para cada entorno.

Consideraciones para montar Azure Files

Las aplicaciones pueden usar la configuración de la aplicación WEBSITE_CONTENTAZUREFILECONNECTIONSTRING para montar Azure Files como el sistema de archivos. Esta configuración tiene comprobaciones de validación adicionales para asegurarse de que la aplicación puede iniciarse correctamente. La plataforma se basa en tener una compartición de contenido en Azure Files y asume un nombre predeterminado a menos que se especifique uno en la WEBSITE_CONTENTSHARE configuración. En el caso de las solicitudes que modifiquen esta configuración, la plataforma intenta validar que existe el recurso compartido de contenido. Si el recurso compartido no existe, la plataforma intenta crearlo. Si no se puede encontrar o crear el recurso compartido de contenido, la solicitud se bloquea.

Si usa referencias de App Configuration para esta configuración, esta comprobación de validación produce un error de forma predeterminada porque la propia conexión no se puede resolver mientras la plataforma procesa la solicitud entrante. Para evitar este problema, puede omitir la validación estableciendo WEBSITE_SKIP_CONTENTSHARE_VALIDATION en 1. Esta configuración omite todas las comprobaciones y el recurso compartido de contenido no se crea automáticamente. Debe asegurarse de que el recurso compartido se haya creado de antemano.

Precaución

Si omite la validación y la cadena de conexión o el recurso compartido de contenido no son válidos, la aplicación no se puede iniciar correctamente y solo sirve errores HTTP 500.

Al crear un sitio, es posible que se produzca un error en el montaje del recurso compartido de contenido si no se propagan los permisos de identidad administrada o si la integración de red virtual no está configurada. Puede aplazar la configuración de Azure Files hasta más adelante en la plantilla de implementación para admitir la configuración necesaria. Para más información, consulte la implementación de Azure Resource Manager en la sección siguiente. App Service solo usa un sistema de archivos predeterminado hasta que Azure Files está configurado y los archivos no se copian. Asegúrese de que no se produzca ningún intento de implementación durante el período provisional antes de montar Azure Files.

Implementación de Azure Resource Manager

Si automatiza las implementaciones de recursos mediante plantillas de Azure Resource Manager (ARM), es posible que tenga que secuenciar las dependencias en un orden específico para que las referencias de App Configuration funcionen. En ese escenario, debe definir la configuración de la aplicación como un recurso independiente en lugar de usar una propiedad siteConfig en la definición de sitio. El sitio debe definirse primero para que la identidad asignada por el sistema se cree con el sitio. A continuación, la identidad administrada se usa en la directiva de acceso.

Esta es una plantilla de ejemplo para una aplicación de funciones que tiene referencias de 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"
            }
        }
    ]
}

Nota:

En este ejemplo, la implementación del control de código fuente depende de la configuración de la aplicación. En la mayoría de los escenarios, esta secuencia es menos segura porque la configuración de la aplicación se actualiza de forma asincrónica. Pero dado que el ejemplo incluye la configuración de la WEBSITE_ENABLE_SYNC_UPDATE_SITE aplicación, la actualización es sincrónica. La implementación del control de código fuente comienza solo después de que la configuración de la aplicación se actualice por completo. Para más información sobre la configuración de la aplicación, consulte Variables de entorno y configuración de la aplicación en Azure App Service.

Solución de problemas de las referencias de App Configuration

Si una referencia no se resuelve correctamente, se usa el valor de referencia en su lugar. Se crea una variable de entorno que usa la sintaxis @Microsoft.AppConfiguration(...) . La referencia puede provocar un error porque la aplicación esperaba un valor de configuración.

Este error suele ser el resultado de una configuración incorrecta de la directiva de acceso de App Configuration. Pero también puede producirse si hay un error de sintaxis en la referencia o si el par clave-valor de configuración no existe en el almacén.

Contenido relacionado