Usare i riferimenti a Configurazione app per il servizio app e Funzioni di Azure
Questo argomento illustra come usare i dati di configurazione nel servizio app o nell'applicazione Funzioni di Azure senza richiedere modifiche al codice. Configurazione App di Azure è un servizio per gestire centralmente la configurazione dell'applicazione. Si tratta anche di uno strumento di controllo efficace per i valori di configurazione nel tempo o nelle versioni.
Concessione dell'accesso dell'app a Configurazione app
Per iniziare a usare i riferimenti a Configurazione app nel servizio app, è necessario innanzitutto un archivio di Configurazione app e occorre fornire all'app l'autorizzazione per accedere ai valori chiave di configurazione nell'archivio.
Creare un archivio di Configurazione app seguendo la guida introduttiva di Configurazione app.
Creare un'identità gestita per l'applicazione.
I riferimenti a Configurazione app useranno l'identità assegnata dal sistema dell'app per impostazione predefinita, ma è possibile specificare un'identità assegnata dall'utente.
Abilitare l'identità appena creata per avere il set corretto di autorizzazioni di accesso nell'archivio di Configurazione app. Aggiornare le assegnazioni di ruolo per l'archivio. Si assegnerà il ruolo
App Configuration Data Readera questa identità, con ambito sulla risorsa.
Accedere ad Archivio di configurazione app con un'identità assegnata dall'utente
Alcune app potrebbero dover fare riferimento alla configurazione in fase di creazione, quando un'identità assegnata dal sistema non è ancora disponibile. In questi casi, è possibile creare un'identità assegnata dall'utente e assegnare in anticipo l'accesso all'archivio di Configurazione app. Seguire questa procedura per creare un'identità assegnata dall'utente per l'archivio di Configurazione app.
Dopo aver concesso le autorizzazioni all'identità assegnata dall'utente, seguire questa procedura:
Assegnare l'identità all'applicazione, se non lo si ha già fatto.
Configurare l'app per usare questa identità per le operazioni di riferimento di Configurazione app impostando la proprietà
keyVaultReferenceIdentitysull'ID risorsa dell'identità assegnata dall'utente. Anche se la proprietà ha keyVault nel nome, l'identità verrà applicata anche ai riferimenti di Configurazione app.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}'}}"
Questa configurazione verrà applicata a tutti i riferimenti di questa app.
Concessione dell'accesso dell'app agli insiemi di credenziali delle chiavi a cui si fa riferimento
Oltre ad archiviare i valori di configurazione non elaborati, Configurazione app di Azure ha un proprio formato per l'archiviazione dei riferimenti a Key Vault. Se il valore di un riferimento a Configurazione app è un riferimento a Key Vault nell'archivio di Configurazione app, l'app dovrà disporre anche dell'autorizzazione per accedere all'insieme di credenziali delle chiavi specificato.
Nota
Il concetto di riferimenti a Key Vault di Configurazione app di Azure non deve essere confuso con il concetto di riferimenti al servizio app e all'insieme di credenziali delle chiavi di Funzioni di Azure. L'app può usare qualsiasi combinazione di queste, ma esistono alcune importanti differenze da notare. Se l'insieme di credenziali deve essere limitato alla rete o se è necessario che l'app venga aggiornata periodicamente alle versioni più recenti, prendere in considerazione l'uso dell'approccio diretto di Servizio app e Funzioni di Azure anziché usare un riferimento a Configurazione app.
Identificare l'identità usata per il riferimento di Configurazione app. L'accesso all'insieme di credenziali deve essere concesso alla stessa identità.
Creare un criterio di accesso in Key Vault per tale identità. Abilitare l'autorizzazione per il segreto "Get" in questi criteri. Non configurare l'"applicazione autorizzata" o le impostazioni di
applicationId, poiché questa operazione non è compatibile con un'identità gestita.
Sintassi del riferimento
Un riferimento di Configurazione app ha il formato @Microsoft.AppConfiguration({referenceString}), dove {referenceString} viene sostituito da quanto segue:
| Parti stringa di riferimento | Descrizione |
|---|---|
| Endpoint=endpoint; | Endpoint è la parte necessaria della stringa di riferimento. Il valore di Endpoint deve avere l'URL della risorsa configurazione app. |
| Key=keyName; | La chiave costituisce la parte richiesta della stringa di riferimento. Il valore di Key deve essere il nome della chiave da assegnare all'impostazione App. |
| Label=label | La parte Etichetta è facoltativa nella stringa di riferimento. L'etichetta deve essere il valore di Etichetta per la chiave specificata in Key |
Ad esempio, un riferimento completo con Label sarà simile al seguente,
@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey; Label=myKeysLabel)
In alternativa, senza Label:
@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey)
Qualsiasi modifica di configurazione all'app che genera un riavvio del sito causa un recupero immediato di tutti i valori chiave di riferimento dall'archivio di Configurazione app.
Nota
L'aggiornamento/recupero automatico di questi valori quando i valori chiave sono stati aggiornati in Configurazione app non è attualmente supportato.
Impostazioni dell'applicazione di origine da Configurazione app
I riferimenti a Configurazione app possono essere usati come valori per Impostazioni applicazione, consentendo di mantenere i dati di configurazione in Configurazione app anziché nella configurazione del sito. Le impostazioni dell'applicazione e i valori delle chiavi di Configurazione app sono entrambi crittografati in modo sicuro a riposo. Se sono necessarie funzionalità di gestione della configurazione centralizzate, i dati di configurazione devono essere inseriti in Configurazione app.
Per usare un riferimento a Configurazione app per un'impostazione dell'app, impostare il riferimento come valore dell'impostazione. L'app può fare riferimento al valore di Configurazione tramite la chiave come di consueto. Non sono necessarie modifiche al codice.
Suggerimento
La maggior parte delle impostazioni dell'applicazione che usano i riferimenti a Configurazione app deve essere contrassegnata come slot, in quanto devono essere presenti archivi o etichette separati per ogni ambiente.
Considerazioni sul montaggio di File di Azure
Le app possono usare l'impostazione dell'applicazione WEBSITE_CONTENTAZUREFILECONNECTIONSTRING per montare File di Azure come file system. Questa impostazione include controlli di convalida aggiuntivi per assicurarsi che l'app possa essere avviata correttamente. La piattaforma si basa sulla presenza di una condivisione di contenuto all'interno di File di Azure e presuppone un nome predefinito, a meno che non ne venga specificato uno tramite l'impostazione WEBSITE_CONTENTSHARE. Per eventuali richieste che modificano queste impostazioni, la piattaforma tenterà di verificare se la condivisione di contenuto esiste e tenterà di crearla in caso contrario. Se non riesce a individuare o creare la condivisione contenuto, la richiesta viene bloccata.
Se si usano riferimenti a Configurazione app per questa impostazione, questo controllo di convalida avrà esito negativo per impostazione predefinita, perché la connessione stessa non può essere risolta durante l'elaborazione della richiesta in ingresso. Per evitare questo problema, è possibile ignorare la convalida impostando WEBSITE_SKIP_CONTENTSHARE_VALIDATION su "1". Questa impostazione ignora tutti i controlli e la condivisione contenuto non verrà creata automaticamente. Assicurarsi che venga creata in anticipo.
Attenzione
Se si ignora la convalida e la stringa di connessione o la condivisione contenuto non sono valide, l'app non sarà in grado di avviarsi correttamente e gestirà solo errori HTTP 500.
Nell'ambito della creazione del sito, è anche possibile che il tentativo di montaggio della condivisione contenuto non sia riuscito a causa di autorizzazioni di identità gestite non propagate o che l'integrazione della rete virtuale non sia configurata. È possibile posticipare la configurazione di File di Azure fino a un secondo momento nel modello di distribuzione per supportare la configurazione necessaria. Per altre informazioni, vedere Distribuzione di Azure Resource Manager. Il servizio app userà un file system predefinito fino alla configurazione di File di Azure e i file non vengono copiati in modo da assicurarsi che non si verifichino tentativi di distribuzione durante il periodo provvisorio prima che File di Azure venga montato.
Distribuzione Azure Resource Manager
Durante l'automazione delle distribuzioni di risorse tramite modelli di Azure Resource Manager, potrebbe essere necessario disporre in sequenza le dipendenze in un determinato ordine per usufruire di questa funzionalità. Si noti che sarà necessario definire le impostazioni di applicazione come risorsa propria, invece di usare una proprietà siteConfig nella definizione del sito. Questo avviene perché il sito deve essere definito per primo, in modo che l'identità assegnata dal sistema venga creata insieme al sito e possa essere usata nei criteri di accesso.
Di seguito è riportato un esempio di pseudo-modelli per un'app per le funzioni con riferimenti a Configurazione app:
{
"$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
In questo esempio, la distribuzione del controllo del codice sorgente dipende dalle impostazioni dell'applicazione. Si tratta in genere di un comportamento non sicuro, dato che l'aggiornamento delle impostazioni dell'applicazione ha un comportamento asincrono. Tuttavia, dato che è stata inclusa l'impostazione dell'applicazione WEBSITE_ENABLE_SYNC_UPDATE_SITE, l'aggiornamento è sincrono. Questo significa che la distribuzione del controllo del codice sorgente inizierà solo dopo l'aggiornamento completo delle impostazioni dell'applicazione. Per altre impostazioni delle ap, vedere Variabili di ambiente e impostazioni dell'app in Servizio app di Azure.
Risoluzione dei problemi relativi ai riferimenti a Configurazione app
Se un riferimento non viene risolto correttamente, verrà invece usato il valore di riferimento. Per le impostazioni dell'applicazione, viene creata una variabile di ambiente il cui valore ha la sintassi @Microsoft.AppConfiguration(...). Questo può causare un errore, perché l'applicazione prevede invece un valore di configurazione.
In genere, questo errore potrebbe essere dovuto a una configurazione errata dei criteri di accesso di Configurazione app. Tuttavia, potrebbe anche essere dovuto a un errore di sintassi nel riferimento o al valore della chiave di configurazione non esistente nell'archivio.