Panoramica del gateway self-hosted

SI APPLICA A: Sviluppatore | Premium

Il gateway self-hosted è una versione facoltativa e in contenitori del gateway gestito predefinito incluso in ogni istanza di Gestione API. È utile per scenari come l'inserimento di gateway negli stessi ambienti in cui si ospitano le API. Usare il gateway self-hosted per migliorare il flusso del traffico API e soddisfare i requisiti di sicurezza e conformità delle API.

Questo articolo illustra come la funzionalità gateway self-hosted di Gestione API di Azure abilita la gestione API ibrida e multicloud. Presenta anche l'architettura generale della funzionalità e ne descrive le funzionalità.

Per una panoramica delle differenze tra gateway gestiti e ospitati autonomamente, vedere API gateway in API Management.

Gestione API ibrida e multicloud

La funzionalità gateway self-hosted espande il supporto di Gestione API per ambienti ibridi e multicloud e consente di gestire in modo efficiente e sicuro le API ospitate in locale e tra cloud da una singola istanza di Gestione API in Azure.

Con il gateway self-hosted, è possibile distribuire una versione in contenitori del componente gateway di Gestione API negli stessi ambienti in cui si ospitano le API. Tutti i gateway self-hosted vengono gestiti dall'istanza di Gestione API con cui sono federati, offrendo così la visibilità e l'esperienza di gestione unificata in tutte le API interne ed esterne.

Ogni istanza di Gestione API è costituita dai componenti chiave seguenti:

Un piano di gestione, esposto come API, usato per configurare il servizio tramite il portale di Azure, PowerShell e altre tecnologie supportate
Un gateway (o piano dei dati), responsabile dell'intermediazione delle richieste API, dell'applicazione delle politiche e della raccolta dei dati di telemetria.
Portale per sviluppatori usato dagli sviluppatori per individuare, apprendere ed eseguire l'onboarding per l'uso delle API

Per impostazione predefinita, tutti questi componenti vengono distribuiti in Azure, causando il flusso di tutto il traffico API (come frecce nere solide nell'immagine seguente) attraverso Azure indipendentemente dalla posizione in cui sono ospitati i back-end che implementano le API. La semplicità operativa di questo modello comporta un aumento della latenza, dei problemi di conformità e, in alcuni casi, costi aggiuntivi per il trasferimento dei dati.

La distribuzione di gateway self-hosted negli stessi ambienti in cui le implementazioni dell'API back-end sono ospitate consente al traffico API di passare direttamente alle API back-end, riducendo la latenza, ottimizzando i costi di trasferimento dei dati e consentendo la conformità mantenendo al tempo stesso i vantaggi di avere un singolo punto di gestione, osservabilità e individuazione per tutte le API dell'organizzazione, indipendentemente dalla posizione in cui sono ospitate le implementazioni.

Imballaggio

Il gateway self-hosted è disponibile come immagine del contenitore Docker basata su Linux dal Registro artefatti Microsoft. Può essere distribuito in Docker, Kubernetes o in qualsiasi altra soluzione di orchestrazione dei contenitori in esecuzione in un cluster server locale, infrastruttura cloud o, a scopo di valutazione e sviluppo, in un personal computer. È anche possibile distribuire il gateway self-hosted come esensione cluster in un Cluster Kubernetes con abilitazione di Azure Arc.

Immagini del contenitore

Sono disponibili un'ampia gamma di immagini del contenitore per i gateway self-hosted:

Convenzione tag	Recommendation	Esempio	Tag in sequenza	Consigliato per la produzione
`{major}.{minor}.{patch}`	Usare questo tag per eseguire sempre la stessa versione del gateway.	`2.0.0`	❌	✔️
`v{major}`	Usare questo tag per eseguire sempre una versione principale del gateway con ogni nuova funzionalità e patch.	`v2`	✔️	❌
`v{major}-preview`	Usare questo tag se si desidera sempre eseguire l'immagine del contenitore di anteprima più recente.	`v2-preview`	✔️	❌
`latest`	Usare questo tag se si desidera valutare il gateway self-hosted.	`latest`	✔️	❌
`beta` ¹	Usare questo tag per valutare le versioni di anteprima del gateway self-hosted.	`beta`	✔️	❌

Qui è disponibile un elenco completo dei tag disponibili.

¹Le versioni di anteprima non sono ufficialmente supportate e sono solo a scopo sperimentale. Vedere i criteri di supporto del gateway self-hosted.

Uso dei tag nelle opzioni di distribuzione ufficiali

Le opzioni di distribuzione nel portale di Azure usano il v2 tag che consente di usare la versione più recente dell'immagine del contenitore del gateway self-hosted v2 con tutti gli aggiornamenti e le patch delle funzionalità.

Note

I frammenti di comando e YAML vengono forniti come riferimento. Se si vuole, è possibile usare un tag più specifico.

Quando si installa un gateway con un chart Helm, l'assegnazione di tag alle immagini è ottimizzata. La versione dell'applicazione del grafico Helm aggiunge il gateway a una determinata versione e non si basa su latest.

Per ulteriori informazioni, vedere Installare un gateway self-hosted per la gestione delle API su Kubernetes con Helm.

Rischio correlato all'usare tag in sequenza

I tag in sequenza sono potenzialmente aggiornati quando viene rilasciata una nuova versione dell'immagine del contenitore. L'uso di questo tipo di tag consente agli utenti del contenitore di ricevere aggiornamenti all'immagine del contenitore senza dover aggiornare le distribuzioni.

Quando si usa questo tipo di tag, è possibile eseguire versioni diverse in parallelo senza notarlo, ad esempio quando si eseguono azioni di ridimensionamento dopo l'aggiornamento del v2 tag.

Esempio: il v2 tag viene rilasciato con l'immagine del 2.0.0 contenitore. Quando 2.1.0 viene rilasciato, il v2 tag verrà collegato all'immagine 2.1.0 .

Importante

Prendere in considerazione l'uso di un tag di versione specifico nell'ambiente di produzione per evitare aggiornamenti involontari a una versione più recente.

Connettività ad Azure

I gateway self-hosted richiedono una connettività TCP/IP in uscita verso Azure sulla porta 443. Ogni gateway self-hosted deve essere associato a una singola istanza di Gestione API ed è configurato tramite il relativo piano di gestione. Un gateway self-hosted usa la connettività ad Azure per:

La segnalazione dello stato inviando messaggi heartbeat ogni minuto.
Regolarmente (ogni 10 secondi) verificare e applicare gli aggiornamenti della configurazione ogni volta che sono disponibili.
Invio di metriche a Monitoraggio di Azure, se configurato per farlo.
Invio di eventi ad Application Insights, se configurato per farlo.

Dipendenze FQDN

Per funzionare correttamente, ogni gateway self-hosted ha bisogno di connettività in uscita sulla porta 443 verso i seguenti endpoint associati alla sua istanza di API Management basata sul cloud:

Punto finale	Obbligatorio?	Note
Nome host dell'endpoint di configurazione	`<api-management-service-name>.configuration.azure-api.net` ¹	Sono supportati anche i nomi host personalizzati i quali possono essere usati al posto del nome host predefinito.
Indirizzo IP pubblico dell'istanza di API Management	✔️	L'indirizzo IP della posizione primaria è sufficiente.
Indirizzi IP pubblici dei tag di servizio di archiviazione di Azure	Facoltativo²	Gli indirizzi IP devono corrispondere alla posizione primaria dell'istanza di Gestione API.
Nome host dell'account di archivio Blob di Azure	Facoltativo²	Account associato all'istanza (`<blob-storage-account-name>.blob.core.windows.net`).
Nome host dell'account di archiviazione tabelle di Azure	Facoltativo²	Account associato all’istanza (`<table-storage-account-name>.table.core.windows.net`).
Endpoint per Azure Resource Manager	Facoltativo³	L'endpoint obbligatorio è `management.azure.com`.
Endpoint per l'integrazione di Microsoft Entra	Facoltativo⁴	Gli endpoint obbligatori sono `<region>.login.microsoft.com` e `login.microsoftonline.com`.
Endpoint per l'integrazione di Azure Application Insights	Facoltativo⁵	Gli endpoint minimi necessari sono `rt.services.visualstudio.com:443`, `dc.services.visualstudio.com:443`e `{region}.livediagnostics.monitor.azure.com:443`. Per altre informazioni, vedere la Documentazione di Monitoraggio di Azure.
Endpoint per l'integrazione di Hub eventi	Facoltativo⁵	Per altre informazioni, vedere la documentazione di Hub eventi di Azure.
Endpoint per l'integrazione della cache esterna	Facoltativo⁵	Questo requisito dipende dalla cache esterna usata.

¹Per informazioni su un'istanza di Gestione API in una rete virtuale interna, vedere Connettività in una rete virtuale interna.
²È necessario solo in v2 quando il controllo API o le quote vengono usate nei criteri.
³È necessario solo quando si usa l'autenticazione Microsoft Entra per verificare le autorizzazioni di controllo degli accessi in base al ruolo.
⁴Obbligatorio solo quando si utilizza l'autenticazione o i criteri di Microsoft Entra correlati a Microsoft Entra.
⁵Obbligatorio solo quando la funzionalità viene usata e richiede informazioni su indirizzo IP pubblico, porta e nome host.

Importante

I nomi host DNS devono essere risolvibili negli indirizzi IP e gli indirizzi IP corrispondenti devono essere raggiungibili.
I nomi degli account di archiviazione associati sono elencati nella pagina Stato della connettività di rete del servizio nel portale di Azure.
Gli indirizzi IP pubblici sottostanti gli account di archiviazione associati sono dinamici e possono cambiare senza preavviso.

Connettività in una rete virtuale interna

Connettività privata. Se il gateway self-hosted viene distribuito in una rete virtuale, abilitare la connettività privata all'endpoint di configurazione v2 dalla posizione del gateway self-hosted, ad esempio usando un DNS privato in una rete con peering.
Connettività Internet. Se il gateway self-hosted deve connettersi all'endpoint di configurazione v2 tramite Internet, configurare un nome host personalizzato per l'endpoint di configurazione ed esporre l'endpoint utilizzando Azure Application Gateway.

Opzioni di autenticazione

Le impostazioni di configurazione del contenitore del gateway forniscono le opzioni seguenti per l'autenticazione della connessione tra il gateway self-hosted e l'endpoint di configurazione dell'istanza di Gestione API basata sul cloud.

Opzione	Considerazioni
Autenticazione Microsoft Entra	Configurare una o più app Microsoft Entra per l'accesso al gateway. Gestire l'accesso separatamente per ogni app. Configurare tempi di scadenza più lunghi per i segreti in base ai criteri dell'organizzazione. Usare le procedure standard di Microsoft Entra per assegnare o revocare le autorizzazioni utente o di gruppo alle app e per ruotare i segreti.
Token di accesso al gateway. (nota anche come chiave di autenticazione).	Il token scade almeno ogni 30 giorni e deve essere rinnovato nei contenitori. Supportato da una chiave del gateway che può essere ruotata in modo indipendente, ad esempio per revocare l'accesso. La rigenerazione della chiave del gateway invalida tutti i token di accesso creati con esso.

Suggerimento

Vedi Gestione API di Azure come origine di Azure Event Grid per informazioni sugli eventi di Event Grid generati da un gateway autonomo quando un token di accesso al gateway è vicino alla scadenza o è scaduto. Usare questi eventi per assicurarsi che i gateway distribuiti siano sempre in grado di eseguire l'autenticazione con l'istanza di Gestione API associata.

Errori di connettività

Quando si perde la connettività ad Azure, il gateway self-hosted non è in grado di ricevere aggiornamenti della configurazione, segnalarne lo stato o caricare i dati di telemetria.

Il gateway self-hosted è progettato per "non riuscire in modo statico" e può sopravvivere alla perdita temporanea di connettività ad Azure. Può essere distribuito con o senza backup della configurazione locale. Con il backup della configurazione, i gateway self-hosted salvano regolarmente una copia di backup della configurazione scaricata più recente in un volume permanente collegato al contenitore o al pod.

Quando il backup della configurazione è disattivato e la connettività ad Azure viene interrotta:

I gateway self-hosted in esecuzione continuano a funzionare utilizzando una copia in memoria della configurazione.
I gateway self-hosted arrestati non saranno in grado di avviare.

Quando il backup della configurazione è attivato e la connettività ad Azure viene interrotta:

L'esecuzione di gateway self-hosted continuerà a funzionare usando una copia in memoria della configurazione.
I gateway self-hosted interrotti possono essere riavviati usando una copia di backup della configurazione.

Quando viene ripristinata la connettività, ogni gateway self-hosted interessato dall'interruzione si riconnette automaticamente con l'istanza di Gestione API associata e scarica tutti gli aggiornamenti di configurazione che si sono verificati mentre il gateway era offline.

Security

Limitazioni

Le funzionalità seguenti disponibili nei gateway gestiti non sono disponibili nei gateway self-hosted:

Ripresa della sessione TLS.
Rinegoziazione del certificato client. Per usare l'autenticazione del certificato client, i consumer di API devono presentare i certificati come parte dell'handshake TLS iniziale. Per garantire questo comportamento, abilitare l'impostazione Negotiate Client Certificate (Negotiate Client Certificate) quando si configura un nome host personalizzato del gateway self-hosted (nome di dominio).

Transport Layer Security (TLS)

Protocolli supportati

I gateway self-hosted supportano per impostazione predefinita TLS v1.2.

Se si usano domini personalizzati, è possibile abilitare TLS v1.0 e/o v1.1 nel piano di controllo.

Pacchetti di crittografia disponibili

I gateway self-hosted usano i pacchetti di crittografia seguenti per le connessioni client e server:

TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
TLS_DHE_RSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
TLS_DHE_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_GCM_SHA384
TLS_RSA_WITH_AES_128_GCM_SHA256
TLS_RSA_WITH_AES_256_CBC_SHA256
TLS_RSA_WITH_AES_128_CBC_SHA256
TLS_RSA_WITH_AES_256_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA

Gestione di pacchetti di crittografia

Con la versione 2.1.1 e successive, è possibile gestire le crittografie usate tramite la configurazione:

net.server.tls.ciphers.allowed-suites consente di definire un elenco delimitato da virgole di crittografie da usare per la connessione TLS tra il client API e il gateway self-hosted.
net.client.tls.ciphers.allowed-suites consente di definire un elenco delimitato da virgole di crittografie da usare per la connessione TLS tra il gateway self-hosted e il back-end.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-10-30