Guida alla migrazione del gateway autogestito

SI APPLICA A: Sviluppatore | Versione Premium

Questo articolo illustra come eseguire la migrazione delle distribuzioni di gateway self-hosted esistenti al gateway self-hosted v2.

Importante

Il supporto per le immagini del contenitore self-hosted di Gestione API di Azure versione 0 e versione 1 termina il 1° ottobre 2023, insieme all'API di configurazione v1 corrispondente. Per altre informazioni, vedere la documentazione relativa alla deprecazione

Novità

Con l'obiettivo di semplificare la distribuzione del gateway self-hosted da parte dei clienti, è stata introdotta una nuova API di configurazione che rimuove la dipendenza da Azure Storage, a meno che non si usi API inspector o quote.

La nuova API di configurazione consente ai clienti di adottare, distribuire e gestire più facilmente il gateway self-hosted nella propria infrastruttura esistente.

Sono stati introdotti nuovi tag di immagine del contenitore per consentire ai clienti di scegliere il modo migliore per provare il gateway e distribuirlo nell'ambiente di produzione.

Per aiutare i clienti a eseguire il gateway nell'ambiente di produzione, abbiamo esteso la nostra guida alla produzione per includere come scalare automaticamente il gateway e distribuirlo per un'alta disponibilità nel tuo cluster Kubernetes.

Altre informazioni sulla connettività del gateway, sui nuovi requisiti dell'infrastruttura e su cosa accade se la connettività viene persa in questo articolo.

Prerequisiti

Prima di poter eseguire la migrazione al gateway self-hosted v2, è necessario assicurarsi che l'infrastruttura soddisfi i requisiti.

Migrazione al gateway auto-ospitato v2

Per eseguire la migrazione dal gateway self-hosted v2 è necessario eseguire alcuni piccoli passaggi:

  1. Usare la nuova immagine del contenitore
  2. Usare la nuova API di configurazione
  3. Soddisfare i requisiti minimi di sicurezza

Immagine del contenitore

Modificare il tag immagine negli script di distribuzione per usare 2.0.0 o versione successiva.

In alternativa, scegliere uno degli altri tag dell'immagine del contenitore.

È possibile trovare un elenco completo dei tag disponibili qui o trovarci nell'hub Docker.

Usare la nuova API di configurazione

Per eseguire la migrazione al gateway self-hosted v2, i clienti devono usare la nuova API di configurazione v2.

Attualmente, Gestione API di Azure offre le API di configurazione seguenti per il gateway self-hosted:

Servizio di configurazione URL Supportato Requisiti
v2 {name}.configuration.azure-api.net Sì Collegamento
v1 {name}.management.azure-api.net/subscriptions/{sub-id}/resourceGroups/{rg-name}/providers/Microsoft.ApiManagement/service/{name}?api-version=2021-01-01-preview NO Collegamento

Il cliente deve usare la nuova API di configurazione v2 modificando gli script di distribuzione per usare il nuovo URL e soddisfare i requisiti dell'infrastruttura.

Importante

  • Il nome host DNS deve essere risolvibile negli indirizzi IP e gli indirizzi IP corrispondenti devono essere raggiungibili. Ciò potrebbe richiedere una configurazione aggiuntiva nel caso in cui si usi un DNS privato, una rete virtuale interna o altri requisiti infrastrutturali.

Sicurezza

Pacchetti di crittografia TLS disponibili

Al momento dell'avvio, il gateway self-hosted v2.0 usava solo un subset delle suite di crittografia usate dalla versione 1.x. A partire dalla versione 2.0.4, sono stati riportati tutti i pacchetti di crittografia supportati dalla versione 1.x.

Per altre informazioni sulle suite di crittografia usate, vedere questo articolo o usare la versione 2.1.1 per controllare quali pacchetti di crittografia usare.

Soddisfare i requisiti minimi di sicurezza

Durante l'avvio, il gateway self-hosted preparerà i certificati della CA che verranno usati. Ciò richiede che il contenitore del gateway sia eseguito con almeno l'ID utente 1001 e non possa usare il file system di sola lettura.

Quando si configura un contesto di sicurezza per il contenitore in Kubernetes, sono necessari almeno gli elementi seguenti:

securityContext:
  runAsNonRoot: true
  runAsUser: 1001
  readOnlyRootFilesystem: false

Tuttavia, a partire da 2.0.3, il gateway self-hosted è in grado di essere eseguito senza privilegi di root in Kubernetes, consentendo ai clienti di gestire il gateway in modo più sicuro.

Ecco un esempio del contesto di sicurezza per il gateway self-hosted:

securityContext:
  allowPrivilegeEscalation: false
  runAsNonRoot: true
  runAsUser: 1001       # This is a built-in user, but you can use any user ie 1000 as well
  runAsGroup: 2000      # This is just an example
  privileged: false
  capabilities:
    drop:
    - all

Avviso

L'esecuzione del gateway self-hosted con file system di sola lettura (readOnlyRootFilesystem: true) non è supportata.

Valutazione dell'impatto con Azure Advisor

Per semplificare la migrazione, sono state introdotte nuove raccomandazioni di Azure Advisor:

  • Usare la raccomandazione gateway self-hosted v2: identifica le istanze di Gestione API di Azure in cui è stato identificato l'uso del gateway self-hosted v0.x o v1.x.
  • Usare l'API di configurazione v2 per i gateway self-hosted : identifica le istanze di Gestione API di Azure in cui è stato identificato l'uso dell'API di configurazione v1 per il gateway self-hosted.

È consigliabile che i clienti usino la panoramica "Tutte le raccomandazioni" in Azure Advisor per determinare se è necessaria una migrazione. Usare le opzioni di filtro per verificare se è presente una delle raccomandazioni precedenti.

Usare Azure Resource Graph per identificare le istanze di Gestione API di Azure

Questa query di Azure Resource Graph fornisce un elenco delle istanze di Gestione delle API di Azure che sono state impattate.

AdvisorResources
| where type == 'microsoft.advisor/recommendations'
| where properties.impactedField == 'Microsoft.ApiManagement/service' and properties.category == 'OperationalExcellence'
| extend
    recommendationTitle = properties.shortDescription.solution
| where recommendationTitle == 'Use self-hosted gateway v2' or recommendationTitle == 'Use Configuration API v2 for self-hosted gateways'
| extend
    instanceName = properties.impactedValue,
    recommendationImpact = properties.impact,
    recommendationMetadata = properties.extendedProperties,
    lastUpdated = properties.lastUpdated
| project tenantId, subscriptionId, resourceGroup, instanceName, recommendationTitle, recommendationImpact, recommendationMetadata, lastUpdated

az graph query -q "AdvisorResources | where type == 'microsoft.advisor/recommendations' | where properties.impactedField == 'Microsoft.ApiManagement/service' and properties.category == 'OperationalExcellence' | extend recommendationTitle = properties.shortDescription.solution | where recommendationTitle == 'Use self-hosted gateway v2' or recommendationTitle == 'Use Configuration API v2 for self-hosted gateways' | extend instanceName = properties.impactedValue, recommendationImpact = properties.impact, recommendationMetadata = properties.extendedProperties, lastUpdated = properties.lastUpdated | project tenantId, subscriptionId, resourceGroup, instanceName, recommendationTitle, recommendationImpact, lastUpdated"

Limitazioni note

Ecco un elenco delle limitazioni note per il gateway auto-ospitato v2:

  • L'API di configurazione v2 non supporta i nomi di dominio personalizzati

Passaggi successivi

  • Last updated on