Guida alla migrazione del gateway self-hosted

  • Articolo

SI APPLICA A: Sviluppatore | 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 corrispondente v1. Altre informazioni nella documentazione di 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 Archiviazione di Azure, a meno che non si usi controllo API 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 le linee guida per la produzione per comprendere come ridimensionare automaticamente il gateway e distribuirlo per la disponibilità elevata nel cluster Kubernetes.

Per ulteriori informazioni sulla connettività del gateway, sui nuovi requisiti dell'infrastruttura e su cosa accade se la connettività viene persa, consultare 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 self-hosted 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 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 in Docker Hub.

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 Supportata 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 come non radice in Kubernetes consentendo ai clienti di eseguire 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:

  • Raccomandazione su Usare il 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.
  • Raccomandazione su 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 panoramica di "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 offre un elenco delle istanze interessate di Gestione API di Azure:

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 self-hosted v2:

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

Passaggi successivi