Distribuire l'istanza di Gestione API di Azure in una rete virtuale - modalità interna
SI APPLICA A: Sviluppatore | Premium
Gestione API di Azure può essere distribuito (inserito) all'interno di una rete virtuale di Azure per accedere ai servizi back-end all'interno della rete. Per le opzioni, i requisiti e le considerazioni sulla connettività della rete virtuale, vedere:
- Uso di una rete virtuale con Gestione API di Azure
- Requisiti delle risorse di rete per l'inserimento di Gestione API in una rete virtuale
Questo articolo illustra come configurare la connettività di rete virtuale per l'istanza di Gestione API nella modalità interna. In questa modalità è possibile accedere solo agli endpoint di Gestione API seguenti all'interno di una rete virtuale il cui accesso viene controllato.
- Il gateway API
- Il portale per sviluppatori
- Gestione diretta
- Git
Nota
- Nessuno degli endpoint di Gestione API è registrato nel DNS pubblico. Gli endpoint rimangono inaccessibili finché non si configura DNS per la rete virtuale.
- Per usare il gateway self-hosted in questa modalità, abilitare anche la connettività privata all'endpoint di configurazione del gateway self-hosted.
Usare Gestione API in modalità interna per:
- Consentire un accesso esterno sicuro da parte di terzi alle API ospitate in un data center privato, tramite connessioni VPN di Azure o Azure ExpressRoute.
- Abilitare scenari cloud ibridi esponendo le API basate su cloud e locali tramite un gateway comune.
- Gestire le API ospitate in più aree geografiche usando un singolo endpoint del gateway.
Per le configurazioni specifiche della modalità esterna, in cui gli endpoint di Gestione API sono accessibili dalla rete Internet pubblica e i servizi back-end si trovano nella rete, vedere Distribuire l'istanza di Gestione API di Azure in una rete virtuale - modalità esterna.
Nota
È consigliabile usare il modulo Azure Az PowerShell per interagire con Azure. Per iniziare, vedere Installare Azure PowerShell. Per informazioni su come eseguire la migrazione al modulo AZ PowerShell, vedere Eseguire la migrazione di Azure PowerShell da AzureRM ad Az.
Prerequisiti
Esaminare i requisiti delle risorse di rete per l'inserimento di Gestione API in una rete virtuale prima di iniziare.
Alcuni prerequisiti variano a seconda della versione (stv2 o stv1) della piattaforma di calcolo che ospita l'istanza di Gestione API.
Suggerimento
Quando si usa il portale per creare o aggiornare la connessione di rete di un'istanza di Gestione API esistente, l'istanza è ospitata nella piattaforma di calcolo stv2.
- Un'istanza di Gestione API. Per altre informazioni, vedere Create an Azure API Management instance (Creare un'istanza di Gestione API di Azure).
Una rete virtuale e subnet devono trovarsi nella stessa area e nella stessa sottoscrizione dell'istanza di Gestione API.
- La subnet usata per connettersi all'istanza di Gestione API può contenere altri tipi di risorse di Azure.
- La subnet non deve avere alcuna delega abilitata. L'impostazione Delegare subnet a un servizio per la subnet deve essere impostata su Nessuna.
Un gruppo di sicurezza di rete collegato alla subnet precedente. Un gruppo di sicurezza di rete (NSG) è necessario per consentire in modo esplicito la connettività in ingresso, perché il servizio di bilanciamento del carico usato internamente da Gestione API è sicuro per impostazione predefinita e rifiuta tutto il traffico in ingresso. Per una configurazione specifica, vedere Configurare le regole del gruppo di sicurezza di rete, più avanti in questo articolo.
Per determinati scenari, abilitare endpoint di servizio nella subnet a servizi dipendenti, ad esempio Archiviazione di Azure o Azure SQL. Per altre informazioni, vedere Forzare il tunneling del traffico verso il firewall locale usando ExpressRoute o un'appliance virtuale di rete, più avanti in questo articolo.
(Facoltativo) Un indirizzo IPv4 pubblico dello SKU Standard.
Importante
- A partire da maggio 2024, la risorsa di indirizzo IP pubblico non è più necessaria durante la distribuzione (inserimento) di un'istanza di Gestione API in una rete virtuale in modalità interna o si esegue la migrazione della configurazione della rete virtuale interna a una nuova subnet. In modalità rete virtuale esterna la specifica di un indirizzo IP pubblico è facoltativa. Se non ne viene specificato uno, verrà automaticamente configurato e usato un indirizzo IP pubblico gestito da Azure per il traffico API di runtime. Specificare l'indirizzo IP pubblico solo se si vuole possedere e controllare l'indirizzo IP pubblico usato per le comunicazioni in ingresso o in uscita su Internet.
Se specificato, l'indirizzo IP deve trovarsi nella stessa area e nella stessa sottoscrizione dell'istanza di Gestione API e della rete virtuale.
Quando si crea una risorsa di IP pubblico, assicurarsi di assegnare un'etichetta di nome DNS a tale risorsa. In generale, è consigliabile usare lo stesso nome DNS dell'istanza di Gestione API. Se lo si cambia, ridistribuire l'istanza in modo che venga applicata la nuova etichetta DNS.
Per ottenere prestazioni ottimali di rete, è consigliabile usare la preferenza di routing predefinita: rete Microsoft.
Quando si crea un IP pubblico in un'area in cui si prevede di abilitare la ridondanza della zona per l'istanza di Gestione API, configurare l'impostazione Ridondanza della zona.
Il valore dell'indirizzo IP viene assegnato come indirizzo IPv4 pubblico virtuale dell'istanza di Gestione API in tale area.
Per le distribuzioni di Gestione API in più aree, configurare le risorse di rete virtuale separatamente per ogni posizione.
Abilitare la connessione della rete virtuale
Abilitare la connettività di rete virtuale usando il portale di Azure (piattaforma stv2)
Passare al portale di Azure per trovare l'istanza di Gestione API. Cercare e selezionare Servizi Gestione API.
Scegliere l'istanza di Gestione API.
Selezionare Rete>Rete virtuale.
Selezionare il tipo di accesso interno.
Nell'elenco di posizioni (aree) in cui viene eseguito il provisioning del servizio Gestione API:
- Scegliere una Posizione.
- Selezionare la Rete virtuale e la Subnet.
- L'elenco di reti virtuali viene popolato con le reti virtuali di Resource Manager disponibili nelle sottoscrizioni di Azure, configurate nell'area che si sta configurando.
Selezionare Applica. La pagina Rete virtuale dell'istanza di Gestione API viene aggiornata con le nuove opzioni di reti virtuali e subnet.
Continuare a configurare le impostazioni delle reti virtuali per le posizioni rimanenti dell'istanza di Gestione API.
Nella barra di spostamento in alto selezionare Salva.
L'aggiornamento dell'istanza di Gestione API può richiedere da 15 a 45 minuti. Il livello Developer ha tempi di inattività durante il processo. Gli SKU Basic e superiori non hanno tempi di inattività durante il processo.
Dopo aver completato la distribuzione, l'indirizzo IP virtuale privato e indirizzo IP virtuale pubblico del servizio Gestione API vengono visualizzati nel pannello Panoramica. Per altre informazioni sugli indirizzi IP, vedere Routing in questo articolo.
Nota
Poiché l'URL del gateway non è registrato nel DNS pubblico, la console di test disponibile nel portale di Azure non funzionerà per il servizio distribuito interno della rete virtuale. In questo caso, usare la console di test disponibile nel portale per sviluppatori.
Abilitare la connettività usando un modello di Resource Manager ( piattaformastv2)
Modello di Azure Resource Manager (API versione 2021-08-01)
Abilitare la connettività usando i cmdlet di Azure PowerShell (piattaforma stv1)
Creare o aggiornare un'istanza di Gestione API in una rete virtuale.
Configurare regole per i gruppi di sicurezza di rete
Configurare regole di rete personalizzate nella subnet di Gestione API per filtrare il traffico da e verso l'istanza di Gestione API. Sono consigliabili le regole NSG minime seguenti per garantire il corretto funzionamento e accesso all'istanza. Esaminare attentamente l'ambiente per determinare altre regole che potrebbero essere necessarie.
Importante
A seconda dell'uso della memorizzazione nella cache e di altre funzionalità, potrebbe essere necessario configurare regole del gruppo di sicurezza di rete aggiuntive oltre le regole minime riportate nella tabella seguente. Per informazioni dettagliate sulle impostazioni, vedere Informazioni di riferimento sulla configurazione della rete virtuale.
- Per la maggior parte degli scenari, usare i tag del servizio indicati anziché gli indirizzi IP del servizio per specificare origini e destinazioni di rete.
- Impostare la priorità di queste regole su un valore più alto rispetto a quello delle regole predefinite.
| Porte di origine/destinazione | Direction | Protocollo di trasporto | Tag di servizio Origine/Destinazione |
Scopo | Tipo di rete virtuale |
|---|---|---|---|---|---|
| * / [80], 443 | In entrata | TCP | Internet / VirtualNetwork | Comunicazione tra client e Gestione API | Solo esterno |
| */3443 | In entrata | TCP | ApiManagement / VirtualNetwork | Endpoint di gestione per il portale di Azure e PowerShell | Esterno e interno |
| * / 6390 | In ingresso | TCP | AzureLoadBalancer / VirtualNetwork | Bilanciamento del carico di infrastruttura di Azure | Esterno e interno |
| * / 443 | In entrata | TCP | AzureTrafficManager / VirtualNetwork | Routing di Gestione traffico di Azure per la distribuzione in più aree | Solo esterno |
| * / 443 | In uscita | TCP | VirtualNetwork / Archiviazione | Dipendenza da Archiviazione di Azure per la funzionalità di base del servizio | Esterno e interno |
| * / 1433 | In uscita | TCP | VirtualNetwork / SQL | Accesso agli endpoint SQL di Azure per la funzionalità di base del servizio | Esterno e interno |
| * / 443 | In uscita | TCP | VirtualNetwork / AzureKeyVault | Accesso ad Azure Key Vault per la funzionalità di base del servizio | Esterno e interno |
| * / 1886, 443 | In uscita | TCP | VirtualNetwork / AzureMonitor | Pubblicazione di Log di diagnostica e metriche, Integrità risorse e Application Insights | Esterno e interno |
Configurazione del DNS
In modalità rete virtuale interna è necessario gestire il proprio DNS per abilitare l'accesso in ingresso agli endpoint di Gestione API.
Consigliamo:
- Configurare una zona DNS privata di Azure.
- Collegare la zona DNS privata di Azure alla rete virtuale in cui è stato distribuito il servizio Gestione API.
Di seguito viene descritto come configurare una zona privata in DNS di Azure.
Nota
Il servizio Gestione API non è in ascolto delle richieste in arrivo agli indirizzi IP. Risponde solo alle richieste per il nome host configurato negli endpoint. Questi endpoint includono:
- Gateway API
- Il portale di Azure
- Il portale per sviluppatori
- L'endpoint di gestione diretta
- Git
Accesso con i nomi host predefiniti
Quando si crea un servizio Gestione API, (contosointernalvnet, ad esempio) per impostazione predefinita vengono configurati i seguenti endpoint:
| Endpoint | Configurazione endpoint |
|---|---|
| API Gateway | contosointernalvnet.azure-api.net |
| Portale per sviluppatori | contosointernalvnet.portal.azure-api.net |
| Il nuovo portale per sviluppatori | contosointernalvnet.developer.azure-api.net |
| L'endpoint di gestione diretta | contosointernalvnet.management.azure-api.net |
| Git | contosointernalvnet.scm.azure-api.net |
Accesso con i nomi di dominio personalizzati
Se non si vuole accedere al servizio Gestione API con i nomi host predefiniti, configurare nomi di dominio personalizzati per tutti gli endpoint di servizio, come mostrato nella figura seguente:
Configurare i record DNS
È quindi possibile creare record nel server DNS per accedere agli endpoint accessibili solo dall'interno della rete virtuale. Eseguire il mapping dei record dell'endpoint all'indirizzo IP virtuale privato per il servizio.
A scopo di test, è possibile aggiornare il file hosts in una macchina virtuale in una subnet connessa alla rete virtuale in cui viene distribuito Gestione API. Supponendo che l'indirizzo IP virtuale privato per il servizio sia 10.1.0.5, è possibile eseguire il mapping del file hosts come segue. Il file di mapping hosts si trova in %SystemDrive%\drivers\etc\hosts (Windows) o /etc/hosts (Linux, macOS).
| Indirizzo IP virtuale interno | Configurazione endpoint |
|---|---|
| 10.1.0.5 | contosointernalvnet.azure-api.net |
| 10.1.0.5 | contosointernalvnet.portal.azure-api.net |
| 10.1.0.5 | contosointernalvnet.developer.azure-api.net |
| 10.1.0.5 | contosointernalvnet.management.azure-api.net |
| 10.1.0.5 | contosointernalvnet.scm.azure-api.net |
È quindi possibile accedere a tutti gli endpoint di Gestione API dalla macchina virtuale creata.
Definizione dei percorsi di trasferimento
Gli indirizzi IP virtuali seguenti sono configurati per un'istanza di Gestione API in una rete virtuale interna.
| Indirizzo IP virtuale | Descrizione |
|---|---|
| Indirizzo IP virtuale privato | Un indirizzo IP con bilanciamento del carico dall'interno dell'intervallo di subnet (DIP) dell'istanza di Gestione API, su cui è possibile accedere al gateway API, al portale per sviluppatori, alla gestione e agli endpoint Git. Registrare questo indirizzo con i server DNS usati dalla rete virtuale. |
| Indirizzo IP virtuale pubblico | Usato solo per il traffico del piano di controllo verso l'endpoint di gestione sulla porta 3443. Può essere bloccato al tag del servizio apiManagement. |
Gli indirizzi IP pubblici e privati con bilanciamento del carico sono disponibili nel pannello Panoramica del portale di Azure.
Per altre informazioni e considerazioni, vedere indirizzi IP di Gestione API di Azure.
Indirizzi VIP e DIP
Gli indirizzi IP (DIP) dinamici verranno assegnati a ogni macchina virtuale sottostante nel servizio e usati per accedere a endpoint e risorse nella rete virtuale e nelle reti virtuali con peering. L'IP pubblico del servizio Gestione API verrà usato per accedere alle risorse pubbliche.
Se le restrizioni IP elencano le risorse protette all'interno della rete virtuale o delle reti virtuali con peering, è consigliabile specificare l'intero intervallo di subnet in cui viene distribuito il servizio Gestione API per concedere o limitare l'accesso dal servizio.
Altre informazioni sulle dimensioni di subnet consigliate.
Esempio
Se si distribuisce 1 unità di capacità di Gestione API nel livello Premium in una rete virtuale interna, verranno usati 3 indirizzi IP: 1 per l'indirizzo VIP privato e uno per i DIP per due macchine virtuali. Se si aumenta il numero di unità fino a 4, verranno usati altri indirizzi IP per i DIP aggiuntivi della subnet.
Se l'endpoint di destinazione ha elencato solo un set fisso di DIP, si verificheranno errori di connessione se si aggiungono nuove unità in futuro. Per questo motivo e poiché la subnet è interamente sotto il controllo dell'utente, è consigliabile inserire l'intera subnet nell'elenco del back-end.
Forzare il tunneling del traffico al firewall locale usando ExpressRoute o un'appliance virtuale di rete
Il tunneling forzato consente di reindirizzare o "forzare" tutto il traffico associato a Internet dalla subnet all'ambiente locale per l'ispezione e il controllo. In genere, si configura e si definisce una route predefinita (0.0.0.0/0), forzando tutto il traffico dalla subnet di Gestione API a passare attraverso un firewall locale o un'appliance virtuale di rete. Questo flusso di traffico interrompe la connettività con Gestione API perché il traffico in uscita è bloccato in locale o convertito tramite NAT in un set non riconoscibile di indirizzi che non usano più i diversi endpoint di Azure. Per risolvere questo problema, utilizzare i metodi riportati di seguito:
Abilitare gli endpoint di servizio nella subnet in cui è distribuito il servizio Gestione API per:
- Azure SQL (obbligatorio solo nell'area primaria se il servizio Gestione API viene distribuito in più aree)
- Archiviazione di Azure
- Hub eventi di Azure
- Azure Key Vault (obbligatorio quando Gestione API viene distribuito nella piattaforma
stv2)
L'abilitazione degli endpoint direttamente dalla subnet di Gestione API a questi servizi consente di usare la rete backbone di Microsoft Azure che fornisce il routing ottimale per il traffico del servizio. Se si usano gli endpoint di servizio con Gestione API con tunneling forzato, il tunneling del traffico dei servizi di Azure sopra indicati non viene forzato. Tuttavia, l'altro tunneling del traffico relativo alle dipendenze del servizio Gestione API viene forzato. Assicurarsi che il firewall o l'appliance virtuale non blocchi questo traffico e che il servizio Gestione API funzioni correttamente.
Nota
È consigliabile abilitare gli endpoint di servizio direttamente dalla subnet di Gestione API ai servizi dipendenti, ad esempio Azure SQL e Archiviazione di Azure che li supportano. Tuttavia, alcune organizzazioni potrebbero avere i requisiti per forzare il tunneling di tutto il traffico dalla subnet di Gestione API. In questo caso, assicurarsi di configurare il firewall o l'appliance virtuale per consentire questo traffico. Sarà necessario consentire l'intervallo di indirizzi IP completo di ogni servizio dipendente e mantenere questa configurazione aggiornata quando cambia l'infrastruttura di Azure. Il servizio Gestione API può anche riscontrare latenza o timeout imprevisti a causa del tunneling forzato di questo traffico di rete.
Tutto il traffico del piano di controllo da Internet all'endpoint di gestione del servizio Gestione API viene instradato attraverso un set specifico di indirizzi IP in ingresso ospitati da Gestione API, inclusi nel tag del servizio ApiManagement. Quando il traffico viene sottoposto a tunneling forzato, le risposte non verranno mappate in modo simmetrico a questi indirizzi IP di origine in ingresso e la connettività all'endpoint di gestione andrà persa. Per superare questa limitazione, configurare una route definita dall'utente (UDR) per il tag del servizio ApiManagement con il tipo di hop successivo impostato su "Internet" per indirizzare il traffico ad Azure.
Nota
Consentire al traffico di gestione di Gestione API di ignorare un firewall locale o un'appliance virtuale di rete non è considerato un rischio significativo per la sicurezza. La configurazione consigliata per la subnet di Gestione API consente il traffico di gestione in ingresso sulla porta 3443 solo dal set di indirizzi IP di Azure inclusi nel tag del servizio ApiManagement. La configurazione UDR consigliata è solo per il percorso di ritorno del traffico di Azure.
(Modalità rete virtuale esterna) Il traffico del piano dati per i client che tentano di raggiungere il gateway di Gestione API e il portale per sviluppatori da Internet verrà eliminato anche per impostazione predefinita a causa del routing asimmetrico introdotto dal tunneling forzato. Per ogni client che richiede l'accesso, configurare una route definita dall'utente esplicita con il tipo hop successivo "Internet" per ignorare il firewall o l'appliance di rete virtuale.
Per le altre dipendenze del servizio Gestione API con tunneling forzato, risolvere il nome host e raggiungere l'endpoint. tra cui:
- Metriche e monitoraggio dell'integrità
- Diagnostica del portale di Azure
- Relay SMTP
- CAPTCHA del portale per sviluppatori
- Server del servizio di gestione delle chiavi di Azure
Per altre informazioni, vedere Informazioni di riferimento sulla configurazione della rete virtuale.
Problemi comuni di configurazione di rete
Questa sezione è stata spostata. Vedere Informazioni di riferimento sulla configurazione della rete virtuale.
Risoluzione dei problemi
Distribuzione iniziale non riuscita del servizio Gestione API in una subnet
- Distribuire una macchina virtuale nella stessa subnet.
- Connettersi alla macchina virtuale e convalidare la connettività a una delle risorse seguenti nella sottoscrizione di Azure:
- BLOB di Archiviazione di Azure
- Database SQL di Microsoft Azure
- Tabella di archiviazione di Azure
- Azure Key Vault (per un'istanza di Gestione API ospitata nella piattaforma
stv2)
Importante
Dopo aver convalidato la connettività, rimuovere tutte le risorse nella subnet prima di distribuire Gestione API nella subnet (obbligatorio quando Gestione API è ospitata nella piattaforma stv1).
Verificare lo stato della rete
Dopo aver distribuito Gestione API nella subnet, usare il portale per verificare la connettività dell'istanza alle dipendenze, ad esempio Archiviazione di Azure.
Nel portale, nel menu a sinistra, in Distribuzione e infrastruttura, selezionare Rete>Stato rete.
| Filtro | Descrizione |
|---|---|
| Obbligatorio | Selezionare questa opzione per esaminare la connettività dei servizi di Azure necessaria per Gestione API. L'errore indica che l'istanza non è in grado di eseguire operazioni di base per gestire le API. |
| Facoltativo | Selezionare questa opzione per esaminare la connettività facoltativa dei servizi. L'errore indica solo che la funzionalità specifica non funzionerà (ad esempio SMTP). L'errore può causare una riduzione delle prestazioni nell'uso e nel monitoraggio dell'istanza di Gestione API e nella fornitura del contratto di servizio di cui è stato eseguito il commit. |
Per risolvere i problemi di connettività, selezionare:
Metriche: per esaminare le metriche relative allo stato della connettività di rete
Diagnosi: per eseguire un verificatore di rete virtuale in un periodo di tempo specificato
Per risolvere i problemi di connettività, esaminare le impostazioni di configurazione di rete e correggere le impostazioni di rete necessarie.
Aggiornamenti incrementali
Quando si apportano modifiche alla rete, fare riferimento all'API NetworkStatus per verificare che il servizio Gestione API non abbia perso l'accesso alle risorse critiche. Lo stato della connettività dovrebbe essere aggiornato ogni 15 minuti.
Per applicare una modifica di configurazione di rete all'istanza di Gestione API tramite il portale:
- Nel menu a sinistra relativo all'istanza, in Distribuzione e infrastruttura, selezionare Rete>Stato rete.
- Selezionare Applica configurazione di rete.
Collegamenti di navigazione delle risorse
Un'istanza di Gestione API ospitata nella piattaforma di calcolo stv1, quando viene distribuita in una subnet di rete virtuale di Resource Manager, riserva la subnet creando un collegamento di spostamento delle risorse. Se la subnet contiene già una risorsa da un provider diverso, la distribuzione ha esito negativo. Quando, analogamente, si elimina un servizio Gestione API o si sposta il servizio in una subnet diversa, il collegamento di spostamento delle risorse viene rimosso.
Problemi riscontrati nella riassegnazione dell'istanza di Gestione API alla subnet precedente
- Blocco della rete virtuale: quando si sposta un'istanza di Gestione API nella subnet originale, la riassegnazione immediata potrebbe non essere possibile a causa del blocco della rete virtuale, che richiede fino a un'ora per essere rimosso. Se la subnet originale include altri servizi di Gestione API basati sulla piattaforma
stv1(basati sul servizio cloud), è necessario eliminarli e attendere per la distribuzione di un servizio basato sulla piattaformastv2nella stessa subnet. - Blocco del gruppo di risorse: un altro scenario da considerare è la presenza di un blocco di ambito a livello di gruppo di risorse o superiore, che ostacola il processo di eliminazione del collegamento di spostamento delle risorse. Per risolvere questo problema, rimuovere il blocco di ambito e consentire un ritardo di circa 4-6 ore per il collegamento del servizio Gestione API dalla subnet originale prima della rimozione del blocco, abilitando la distribuzione nella subnet desiderata.
Risolvere i problemi di connessione a Microsoft Graph dall'interno di una rete virtuale
La connettività di rete a Microsoft Graph è necessaria per funzionalità che includono l'accesso utente al portale per sviluppatori usando il provider di identità Microsoft Entra.
Per risolvere i problemi di connettività a Microsoft Graph dall'interno di una rete virtuale:
Assicurarsi che il gruppo di sicurezza di rete e altre regole di rete siano configurate per la connettività in uscita dall'istanza di Gestione API a Microsoft Graph (usando il tag di servizio AzureActiveDirectory).
Verificare la risoluzione DNS e l'accesso alla rete per
graph.microsoft.comdall'interno della rete virtuale. Ad esempio, effettuare il provisioning di una nuova macchina virtuale all'interno della rete virtuale, connettersi e provare il comandoGET https://graph.microsoft.com/v1.0/$metadatada un browser o usando cURL, PowerShell o altri strumenti.
Passaggi successivi
Altre informazioni su: