Panoramica del gateway self-hosted

  • Articolo

SI APPLICA A: Sviluppatore | Premium

Il gateway self-hosted è una versione facoltativa e in contenitori del gateway gestito predefinito incluso in ogni servizio 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à del gateway self-hosted di Azure Gestione API abilita la gestione API ibrida e multicloud, presenta l'architettura di alto livello ed evidenzia le relative funzionalità.

Per una panoramica delle funzionalità nelle varie offerte di gateway, vedere Gateway API in Gestione API.

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 Gestione API negli stessi ambienti in cui ospitano le API. Tutti i gateway self-hosted vengono gestiti dal servizio Gestione API 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.

Flusso del traffico API senza gateway self-hosted

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.

Flusso del traffico API con gateway self-hosted

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 vuole sempre eseguire l'immagine del contenitore di anteprima più recente. v2-preview ✔️ ❌
latest Usare questo tag se si vuole 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 nella portale di Azure usano il v2 tag 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 vuole 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 Gestione API in Kubernetes con Helm.

Rischio di usare tag in sequenza

I tag in sequenza sono tag 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 v2 l'aggiornamento del tag.

Esempio: v2 il tag è stato rilasciato con 2.0.0 l'immagine del contenitore, ma quando 2.1.0 verrà rilasciato, il v2 tag 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

Importante

Il supporto per le immagini del contenitore del gateway self-hosted di Gestione API di Azure versione 0 e versione 1 termina il 1° ottobre 2023, insieme all'API di configurazione corrispondente v1. Consultare la guida alla migrazione per usare il gateway self-hosted v2.0.0 o versione successiva con l'API di configurazione v2. Altre informazioni nella documentazione di deprecazione

Dipendenze FQDN

Per funzionare correttamente, ogni gateway self-hosted richiede la connettività in uscita sulla porta 443 agli endpoint seguenti associati all'istanza di Gestione API basata sul cloud:

Descrizione Obbligatorio per v1 Obbligatorio 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 nomi host personalizzati e possono essere usati invece del nome host predefinito.
Indirizzo IP pubblico dell'istanza di Gestione API ✔️ ✔️ 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 Gestione API.
Nome host dell'account Archiviazione BLOB di Azure ✔️ Facoltativo2 Account associato all'istanza (<blob-storage-account-name>.blob.core.windows.net)
Nome host dell'account Archiviazione tabella 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 app Azure lication Insights Facoltativo5 Facoltativo5 Gli endpoint obbligatori minimi sono:
  • rt.services.visualstudio.com:443
  • dc.services.visualstudio.com:443
  • {region}.livediagnostics.monitor.azure.com:443
Altre informazioni nella documentazione di Monitoraggio di Azure
Endpoint per l'integrazione di Hub eventi Facoltativo5 Facoltativo5 Altre 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, 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.
2È necessario solo nella versione 2 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 nella portale di Azure.
  • Gli indirizzi IP pubblici sottostanti gli account di archiviazione associati sono dinamici e possono cambiare senza preavviso.

Opzioni di autenticazione

Per autenticare la connessione tra il gateway self-hosted e l'endpoint di configurazione dell'istanza di Gestione API 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 al servizio Gestione API 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_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

A partire dalla 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.

Passaggi successivi