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 servizio API Management. È 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 in che modo la funzionalità gateway self-hosted di API Management di Azure abilita la API Management ibrida e multicloud, presenta l'architettura di alto livello ed evidenzia le sue funzionalità.
Per una panoramica delle funzionalità nelle varie offerte di gateway, vedere Gateway API in API Management.
Gestione API ibrida e multicloud
La funzionalità gateway self-hosted espande il supporto di Gestione API agli ambienti ibridi e multicloud e consente alle organizzazioni di gestire in modo efficiente e sicuro le API ospitate in locale e nei cloud da un singolo servizio di Gestione API in Azure.
Con il gateway self-hosted, i clienti hanno la flessibilità di distribuire una versione in contenitori del componente gateway di API Management negli stessi ambienti in cui ospitano le API. Tutti i gateway self-hosted vengono gestiti dal servizio API Management con cui sono federati, offrendo così ai clienti la visibilità e l'esperienza di gestione unificata in tutte le API interne ed esterne.
Ogni servizio di Gestione API è composto dai componenti chiave seguenti:
- Piano di gestione, esposto come API, usato per configurare il servizio tramite il portale di Microsoft Azure, PowerShell e altri meccanismi supportati.
- Gateway (o piano dati), responsabile del proxy delle richieste API, dell'applicazione dei criteri e della raccolta dei dati di telemetria
- Portale per sviluppatori usato dagli sviluppatori per individuare, apprendere ed eseguire l'onboarding per usare le API
Per impostazione predefinita, tutti questi componenti vengono distribuiti in Azure, causando il flusso di tutto il traffico dell'API (come frecce nere continue 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 sono ospitate le implementazioni API back-end 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à, pur mantenendo i vantaggi di avere un singolo punto di gestione, osservabilità e individuabilità di tutte le API all'interno dell'organizzazione, indipendentemente da dove sono ospitate le loro implementazioni.
Packaging
Il gateway self-hosted è disponibile come immagine del contenitore Docker basata su Linux dal Registro artefatti Microsoft. Può essere distribuito su Docker, Kubernetes o qualsiasi altra soluzione di orchestrazione del contenitore in esecuzione su un cluster server locale, su un'infrastruttura cloud o, a scopo di valutazione e sviluppo, su 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 per soddisfare le proprie esigenze:
| Convenzione tag | Elemento consigliato | 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 |
✔️ | ❌ |
beta1 |
Usare questo tag per valutare le versioni di anteprima del gateway self-hosted. | beta |
✔️ | ❌ |
Qui è disponibile un elenco completo dei tag disponibili.
1Le 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 tag v2 che consente ai clienti di usare la versione più recente dell'immagine del contenitore del gateway self-hosted v2 con tutti gli aggiornamenti e le patch delle funzionalità.
Nota
È possibile fornire come riferimento i frammenti di comando e YAML, se si desidera usare un tag più specifico.
Quando si esegue l'installazione con il grafico Helm, l'assegnazione di tag alle immagini è ottimizzata per l'utente. La versione dell'applicazione del grafico Helm aggiunge il gateway a una determinata versione e non si basa su latest.
Altre informazioni su come installare un gateway self-hosted di API Management in 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. Ciò consente agli utenti del contenitore di ricevere aggiornamenti all'immagine del contenitore senza dover aggiornare le distribuzioni.
Ciò significa che è possibile eseguire versioni diverse in parallelo senza notarlo, ad esempio quando si eseguono azioni di ridimensionamento dopo l'aggiornamento del tag v2.
Esempio: il tag v2 è stato rilasciato con l'immagine del contenitore 2.0.0, ma quando 2.1.0 verrà rilasciato, il tag v2 verrà collegato all'immagine 2.1.0.
Importante
È consigliabile usare un tag di versione specifico nell'ambiente di produzione per evitare l'aggiornamento involontario 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 un singolo servizio di Gestione API e viene 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
- La verifica regola re(ogni 10 secondi) e l’applicazione di aggiornamenti della configurazione quando sono disponibili
- L’invio di metriche a Monitoraggio di Azure, se configurato in tal senso
- L’invio di eventi ad Application Insights, se impostato 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:
| Descrizione | Necessario per v1 | Necessario per v2 | Note |
|---|---|---|---|
| Nome host dell'endpoint di configurazione | <apim-service-name>.management.azure-api.net |
<apim-service-name>.configuration.azure-api.net1 |
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 del tag del servizio Archiviazione di Azure | ✔️ | Facoltativo2 | Gli indirizzi IP devono corrispondere alla posizione primaria dell'istanza di API Management. |
| Nome host dell'account di archiviazione BLOB di Azure | ✔️ | Facoltativo2 | Account associato all'istanza (<blob-storage-account-name>.blob.core.windows.net) |
| Nome host dell'account di archiviazione tabelle di Azure | ✔️ | Facoltativo2 | Account associato all'istanza (<table-storage-account-name>.table.core.windows.net) |
| Endpoint per Azure Resource Manager | ✔️ | Facoltativo3 | Gli endpoint obbligatori sono management.azure.com. |
| Endpoint per l'integrazione di Microsoft Entra | ✔️ | Facoltativo4 | Gli endpoint obbligatori sono <region>.login.microsoft.com e login.microsoftonline.com. |
| Endpoint per l'integrazione di Azure Application Insights | Facoltativo5 | Facoltativo5 | Gli endpoint obbligatori minimi sono:
|
| Endpoint per l'integrazione di Hub eventi | Facoltativo5 | Facoltativo5 | Ulteriori informazioni sono disponibili nella documentazione di Hub eventi di Azure |
| Endpoint per l'integrazione della cache esterna | Facoltativo5 | Facoltativo5 | Questo requisito dipende dalla cache esterna usata |
1Per un'istanza di Gestione API in una rete virtuale interna, vedere Connettività in una rete virtuale interna.
2È necessario solo in v2 quando il controllo API o le quote vengono usate nei criteri.
3È necessario solo quando si usa l'autenticazione Microsoft Entra per verificare le autorizzazioni di controllo degli accessi in base al ruolo.
4Solo quando si utilizza l'autenticazione Microsoft Entra o i criteri correlati a Microsoft Entra.
5È necessario 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 dal percorso del gateway self-hosted, ad esempio usando un DNS privato in una rete con peering.
Accesso a Internet: se il gateway self-hosted deve connettersi a un endpoint di configurazione v2 tramite Internet, configurare un nome host personalizzato per l'endpoint di configurazione ed esporre l'endpoint usando gateway applicazione.
Opzioni di autenticazione
Per autenticare la connessione tra il gateway self-hosted e l'endpoint di configurazione dell'istanza di API Management basata sul cloud, sono disponibili le opzioni seguenti nelle impostazioni di configurazione del contenitore del gateway.
| 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 all'app e per ruotare i segreti |
| Token di accesso del gateway (detto anche chiave di autenticazione) | Il token scade ogni 30 giorni al massimo 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 |
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:
- L'esecuzione di gateway self-hosted continuerà a funzionare usando 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 arrestati potranno iniziare a usare una copia di backup della configurazione
Quando viene ripristinata la connettività, ogni gateway self-hosted interessato dall'interruzione si riconnette automaticamente con il servizio API Management associato e scarica tutti gli aggiornamenti di configurazione che si sono verificati mentre il gateway era "offline".
Sicurezza
Limiti
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)
Importante
Questa panoramica è applicabile solo al gateway self-hosted v1 & v2.
Protocolli supportati
Il gateway self-hosted fornisce il supporto per TLS v1.2 per impostazione predefinita.
I clienti che usano domini personalizzati possono abilitare TLS v1.0 e/o v1.1 nel piano di controllo.
Pacchetti di crittografia disponibili
Importante
Questa panoramica è applicabile solo al gateway self-hosted v2.
Il gateway self-hosted usa le suite di crittografia seguenti per le connessioni client e server:
TLS_AES_256_GCM_SHA384TLS_CHACHA20_POLY1305_SHA256TLS_AES_128_GCM_SHA256TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384TLS_DHE_RSA_WITH_AES_256_GCM_SHA384TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256TLS_DHE_RSA_WITH_AES_128_GCM_SHA256TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384TLS_DHE_RSA_WITH_AES_256_CBC_SHA256TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256TLS_DHE_RSA_WITH_AES_128_CBC_SHA256TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHATLS_ECDHE_RSA_WITH_AES_256_CBC_SHATLS_DHE_RSA_WITH_AES_256_CBC_SHATLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHATLS_ECDHE_RSA_WITH_AES_128_CBC_SHATLS_DHE_RSA_WITH_AES_128_CBC_SHATLS_RSA_WITH_AES_256_GCM_SHA384TLS_RSA_WITH_AES_128_GCM_SHA256TLS_RSA_WITH_AES_256_CBC_SHA256TLS_RSA_WITH_AES_128_CBC_SHA256TLS_RSA_WITH_AES_256_CBC_SHATLS_RSA_WITH_AES_128_CBC_SHA
Gestione di pacchetti di crittografia
A partire dalla versione 2.1.1 e successive, è possibile gestire le crittografie usate tramite la configurazione:
net.server.tls.ciphers.allowed-suitesconsente 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-suitesconsente di definire un elenco delimitato da virgole di crittografie da usare per la connessione TLS tra il gateway self-hosted e il back-end.
Passaggi successivi
- Altre informazioni sui vari gateway sono disponibili nella panoramica del gateway API
- Altre informazioni sui criteri di supporto per il gateway self-hosted
- Altre informazioni su API Management in un ambiente ibrido e multicloud
- Altre informazioni sulle linee guida per l'esecuzione del gateway self-hosted in Kubernetes nell'ambiente di produzione
- Distribuire un gateway self-hosted in Docker
- Distribuire un gateway self-hosted in Kubernetes
- Distribuire un gateway self-hosted nel cluster Kubernetes abilitato per Azure Arc
- Distribuire un gateway self-hosted nell'App contenitore di Azure
- Impostazioni di configurazione del gateway self-hosted
- Informazioni sulle funzionalità di osservabilità in API Management
- Informazioni sull'integrazione di Dapr con il gateway self-hosted