Come ospitare il carico di lavoro in Azure

Questo articolo descrive come ospitare il carico di lavoro Fabric Extensibility Toolkit in Azure usando un'architettura solo front-end. Extensibility Toolkit usa un approccio di distribuzione nativo del cloud con i servizi di Azure ottimizzati per le applicazioni Web statiche.

Panoramica dell'architettura

Fabric Extensibility Toolkit usa un'architettura incentrata sulla distribuzione front-end con i servizi di Azure:

Architettura di Extensibility Toolkit

L'architettura di Extensibility Toolkit include le caratteristiche seguenti:

Implementazione solo front-end: il carico di lavoro si svolge interamente nel browser senza necessitare di un back-end separato
Hosting di siti web statici: utilizza siti web statici di Azure Storage per l'hosting
Frontdoor di Azure: fornisce la rete CDN globale, la terminazione SSL e il routing
Servizi gestiti: utilizza Entra ID, Key Vault e identità gestita per la sicurezza
Processo di distribuzione singolo: usa gli script di PowerShell forniti per la distribuzione

Servizi di Azure usati

Frontdoor di Azure

Frontdoor di Azure funge da punto di ingresso globale per il carico di lavoro. Offre:

Bilanciamento del carico globale: instrada gli utenti alla posizione perimetrale più vicina
Terminazione SSL: gestisce automaticamente i certificati HTTPS
Web Application Firewall (WAF): protegge da vulnerabilità Web comuni
Memorizzazione nella cache: migliora le prestazioni memorizzando nella cache gli asset statici nelle posizioni perimetrali

Per l'Extensibility Toolkit, Front Door instrada il traffico verso il tuo sito Web statico ospitato su Azure Storage, garantendo alta disponibilità e bassa latenza in tutto il mondo.

Account di archiviazione di Azure (sito Web statico)

Un account di archiviazione di Azure con hosting di siti web statici ospita la tua applicazione di lavoro costruita. In questo modo sono disponibili le opzioni seguenti:

Hosting conveniente: pagare solo per l'archiviazione e la larghezza di banda usata
Scalabilità automatica: gestisce i picchi di traffico senza configurazione
Disponibilità globale: il contenuto viene gestito dall'infrastruttura di archiviazione globale di Azure
Distribuzione basata su file: caricare file per distribuire le versioni

L'Extensibility Toolkit compila l'applicazione React in HTML statico, JavaScript, CSS e assetti distribuiti direttamente nell'account di archiviazione.

Azure Key Vault (Archivio chiavi di Azure)

Azure Key Vault gestisce la configurazione e i segreti sensibili:

Segreti client: memorizza in modo sicuro i segreti delle applicazioni di Entra ID
Chiavi API: gestisce le chiavi API del servizio esterno
Configurazione: archivia le impostazioni specifiche dell'ambiente
Certificati: gestisce i certificati SSL, se necessario

I carichi di lavoro accedono a Key Vault tramite identità gestita per un'autenticazione sicura priva di credenziali.

Azure Entra ID (Azure Active Directory)

L'ID Entra di Azure fornisce l'autenticazione e l'autorizzazione:

Registrazione dell'app: registra il tuo carico di lavoro come applicazione Entra
Flussi OAuth 2.0: gestiscono l'autenticazione utente con Fabric
Autorizzazioni API: gestisce l'accesso alle API Fabric e Microsoft Graph
Gestione dei token: fornisce token di accesso sicuro per le chiamate API

Identità gestita

L'identità gestita fornisce l'autenticazione sicura da servizio a servizio:

Nessuna gestione delle credenziali: elimina la necessità di archiviare i segreti nel codice
Gestione dei token: Azure gestisce l'acquisizione e il rinnovo dei token
Accesso sicuro: si connette a Key Vault e ad altri servizi di Azure in modo sicuro
Ciclo di vita delle identità: associato alle risorse di Azure per la pulizia

Processo di distribuzione

Prerequisiti

Prima di eseguire la distribuzione in Azure, assicurarsi di disporre di:

Sottoscrizione di Azure con autorizzazioni appropriate
Interfaccia della riga di comando di Azure installata ed autenticata
Repository di Fabric Extensibility Toolkit clonato localmente
Il carico di lavoro creato utilizzando .\scripts\Build\BuildRelease.ps1

Uso dello script di distribuzione

Extensibility Toolkit include uno script di distribuzione di PowerShell in scripts\Deploy\DeployToAzureWebApp.ps1 che automatizza il processo di distribuzione.

Distribuzione di base

# Deploy to an existing Azure Web App
.\scripts\Deploy\DeployToAzureWebApp.ps1 -WebAppName "my-fabric-workload" -ResourceGroupName "fabric-workload-rg"

Opzioni di distribuzione aggiuntive

# Deploy to staging slot with custom settings
.\scripts\Deploy\DeployToAzureWebApp.ps1 `
    -WebAppName "my-fabric-workload" `
    -ResourceGroupName "fabric-workload-rg" `
    -SlotName "staging" `
    -Force $true `
    -CreateBackup $true `
    -RestartAfterDeploy $true

Parametri dello script di distribuzione

Parametro	Description	Obbligatorio	Predefinito
`WebAppName`	Nome dell'app Web di Azure in cui eseguire la distribuzione	Yes	-
`ResourceGroupName`	Gruppo di risorse contenente l'app Web	Yes	-
`ReleasePath`	Percorso dei file dell'applicazione compilati	NO	`..\..\release\app`
`DeploymentMethod`	Metodo di distribuzione (ZipDeploy, FTP, LocalGit)	NO	`ZipDeploy`
`SlotName`	Slot di distribuzione per la gestione temporanea	NO	-
`Force`	Ignorare le richieste di conferma	NO	`$false`
`CreateBackup`	Creare il backup prima della distribuzione	NO	`$true`
`RestartAfterDeploy`	Riavviare l'app dopo la distribuzione	NO	`$true`

Funzionalità dello script di distribuzione

Lo script di distribuzione offre funzionalità di distribuzione complete:

Convalida e sicurezza

Controllo dei prerequisiti: convalida l'installazione e l'autenticazione dell'interfaccia della riga di comando di Azure
Convalida delle risorse: conferma che l'app Web di destinazione esiste ed è accessibile
Convalida della compilazione: assicura che la directory di versione contenga i file necessari
Creazione del backup: crea il backup della distribuzione per le funzionalità di rollback

Flusso di lavoro per la distribuzione

Creazione di pacchetti ZIP: comprime l'applicazione incorporata nel pacchetto di distribuzione
Report sulle dimensioni: mostra le dimensioni del pacchetto di distribuzione per la verifica
Monitoraggio dello stato di avanzamento: fornisce aggiornamenti dello stato della distribuzione in tempo reale
Gestione degli errori: messaggi di errore dettagliati con indicazioni sulla risoluzione dei problemi

Post-implementazione

Controllo integrità: convalida che l'applicazione distribuita risponde correttamente
Creazione di report URL: fornisce un collegamento diretto all'applicazione distribuita
Indicazioni sul manifesto: mostra i passaggi successivi per il caricamento del manifesto in Fabric
Metriche temporali: Riporta la durata totale della distribuzione

Distribuzione manuale

È anche possibile distribuire manualmente l'applicazione front-end usando i comandi di Azure PowerShell:

Compilare l'applicazione

Prima di tutto, compilare l'applicazione front-end per l'ambiente di test:

npm run build:test

Creare un pacchetto di distribuzione

Passare alla build\Frontend cartella nel progetto
Selezionare tutti i file e la assets cartella nella directory di compilazione
Creare un .zip file contenente tutti i file selezionati

Eseguire la distribuzione con Azure PowerShell

# Connect to Azure
Connect-AzAccount

# Set your subscription context
Set-AzContext -Subscription "<subscription_id>"

# Deploy the zip file to your web app
Publish-AzWebApp -ResourceGroupName <resource_group_name> -Name <web_app_name> -ArchivePath <zip_file_path>

Parametri di distribuzione manuale

Parametro	Description	Example
`<subscription_id>`	ID sottoscrizione di Azure	`aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e`
`<resource_group_name>`	Gruppo di risorse contenente l'app Web	`fabric-workload-rg`
`<web_app_name>`	Nome dell'app Web di Azure	`my-fabric-workload`
`<zip_file_path>`	Percorso completo del file ZIP della distribuzione	`C:\path\to\deployment.zip`

Annotazioni

Per la distribuzione manuale sono necessarie le autorizzazioni di Azure appropriate e il modulo Azure PowerShell installato nel computer.

Considerazioni sulla sicurezza

Flusso di autenticazione

Il workload si autentica con Fabric utilizzando il flusso standard OAuth 2.0.

L'utente accede al carico di lavoro tramite Fabric
Fabric reindirizza all'applicazione ospitata in Azure
L'app reindirizza all'ID Entra per l'autenticazione
Entra ID restituisce il token di autenticazione
L'app usa il token per accedere alle API di Fabric

Configurazione sicura

Variabili di ambiente: configurazione dello Store in Impostazioni app di Azure, non nel codice
Integrazione di Key Vault: accedere ai segreti tramite identità gestita
Solo HTTPS: applica HTTPS per tutte le comunicazioni
Configurazione CORS: Configurare i criteri CORS appropriati per i domini di Fabric

Procedure consigliate

Privilegi minimi: concedere autorizzazioni minime necessarie all'identità gestita
Rotazione dei segreti: ruotare regolarmente i segreti archiviati in Key Vault
Sicurezza di rete: usare endpoint privati laddove possibile
Monitoraggio: abilitare Application Insights per il monitoraggio della sicurezza

Configurazione dopo la distribuzione

Configurazione del servizio app di Azure

Dopo la distribuzione, configurare il servizio app di Azure:

# Set environment variables for your workload
az webapp config appsettings set --name "my-fabric-workload" --resource-group "fabric-workload-rg" --settings \
    "FABRIC_CLIENT_ID=your-client-id" \
    "FABRIC_TENANT_ID=your-tenant-id" \
    "KEY_VAULT_URL=https://your-keyvault.vault.azure.net/"

Configurazione di Key Vault

Archiviare la configurazione sensibile in Key Vault:

# Store client secret
az keyvault secret set --vault-name "your-keyvault" --name "FabricClientSecret" --value "your-client-secret"

# Store API keys
az keyvault secret set --vault-name "your-keyvault" --name "ExternalApiKey" --value "your-api-key"

Configurazione dell'identità gestita

Configurare l'identità gestita per l'accesso a Key Vault:

# Enable system-assigned managed identity
az webapp identity assign --name "my-fabric-workload" --resource-group "fabric-workload-rg"

# Grant access to Key Vault
az keyvault set-policy --name "your-keyvault" \
    --object-id "managed-identity-principal-id" \
    --secret-permissions get list

Distribuzione del manifesto

Dopo aver distribuito l'applicazione in Azure, è necessario caricare il pacchetto manifesto in Fabric:

Creare un pacchetto di manifesto

Prima di tutto, costruire il pacchetto manifest:

.\scripts\Build\BuildManifestPackage.ps1

Verrà creato release\ManifestPackage.1.0.0.nupkg contenente il manifesto del carico di lavoro.

Caricare nel portale di amministrazione di Fabric

Aprire il portale di amministrazione di Microsoft Fabric
Vai a Gestione del carico di lavoro>Caricamento del carico di lavoro
Caricare il ManifestPackage.1.0.0.nupkg file
Configurare le impostazioni e le autorizzazioni del carico di lavoro
Attivare il carico di lavoro per il tenant

Aggiornare il manifesto per la distribuzione di Azure

Prima di compilare il pacchetto manifesto per la distribuzione di Azure, assicurarsi che i valori nel .env file (ad esempio FRONTEND_URL, FRONTEND_APPIDe qualsiasi altra variabile richiesta) siano impostati correttamente per l'ambiente Azure. Questi valori verranno sostituiti nel tuo WorkloadManifest.xml durante il processo di compilazione.

Per un elenco completo delle variabili di ambiente necessarie e indicazioni su come impostarle, vedere i requisiti di pubblicazione generali.

Monitoraggio e risoluzione dei problemi

Approfondimenti sulle Applicazioni

Abilitare Application Insights per il monitoraggio:

Monitoraggio delle prestazioni: tenere traccia dei tempi di caricamento delle pagine e delle interazioni degli utenti
Rilevamento degli errori: monitorare gli errori JavaScript e le richieste non riuscite
Analisi dell'utilizzo: comprendere come gli utenti interagiscono con il carico di lavoro
Telemetria personalizzata: aggiungere metriche personalizzate per la logica di business

Problemi e soluzioni comuni

Errori di distribuzione

Errori di autenticazione: verificare l'accesso CLI di Azure con az account show
Risorsa non trovata: verificare che il nome e il gruppo di risorse dell'app Web siano corretti
Autorizzazione negata: verificare che l'account abbia il ruolo di Collaboratore nel gruppo di risorse