Leitfaden für die Migration des selbstgehosteten Gateways

  • Artikel

GILT FÜR: Entwickler | Premium

In diesem Artikel wird erläutert, wie Sie vorhandene Bereitstellungen selbstgehosteter Gateways zu selbstgehosteten v2-Gateways migrieren.

Wichtig

Support für die Version 0 und Version 1 der Containerimages des selbstgehosteten Gateways von Azure API Management endet am 1. Oktober 2023, zusammen mit der zugehörigen Konfigurations-API v1. Weitere Informationen finden Sie in unserer Dokumentation zur Einstellung veralteter Versionen.

Neuigkeiten

Da wir Kunden die Bereitstellung unseres selbstgehosteten Gateways erleichtern möchten, haben wir eine neue Konfigurations-API eingeführt, die die Abhängigkeit von Azure Storage aufhebt, es sei denn, Sie verwenden API-Inspektor oder Kontingente.

Mit der neuen Konfigurations-API können Kunden unser selbstgehostetes Gateway in ihrer vorhandenen Infrastruktur einfacher übernehmen, bereitstellen und betreiben.

Wir haben neue Containerimagetags eingeführt, damit Kunden die beste Möglichkeit auswählen können, unser Gateway zu testen und in der Produktion bereitzustellen.

Um Kunden bei der Ausführung unseres Gateways in der Produktion zu unterstützen, haben wir unseren Produktionsleitfaden erweitert, um zu berücksichtigen, wie das Gateway automatisch skaliert und für hohe Verfügbarkeit in Ihrem Kubernetes-Cluster bereitgestellt wird.

Erfahren Sie in diesem Artikel mehr über die Konnektivität unseres Gateways, unsere neuen Infrastrukturanforderungen und was geschieht, wenn die Konnektivität verloren geht.

Voraussetzungen

Bevor Sie zum selbstgehosteten v2-Gateway migrieren können, müssen Sie sicherstellen, dass Ihre Infrastruktur die Anforderungen erfüllt.

Migrieren zum selbstgehosteten v2-Gateway

Die Migration vom selbstgehostetem v2-Gateway erfordert einige kleine Schritte:

  1. Verwenden des neuen Containerimages
  2. Verwenden der neuen Konfigurations-API
  3. Erfüllen minimaler Sicherheitsanforderungen

Containerimage

Ändern Sie das Imagetag in Ihren Bereitstellungsskripts so, dass 2.0.0 oder höher verwendet wird.

Alternativ können Sie eines unserer anderen Containerimagetags auswählen.

Eine vollständige Liste der verfügbaren Tags finden Sie hier oder auf Docker Hub.

Verwenden der neuen Konfigurations-API

Um zum selbstgehosteten v2-Gateway zu migrieren, müssen Kunden unsere neue Konfigurations-API v2 verwenden.

Derzeit stellt Azure API Management die folgenden Konfigurations-APIs für das selbstgehostete Gateway bereit:

Konfigurationsdienst URL Unterstützt Anforderungen
V2 {name}.configuration.azure-api.net Ja Link
v1 {name}.management.azure-api.net/subscriptions/{sub-id}/resourceGroups/{rg-name}/providers/Microsoft.ApiManagement/service/{name}?api-version=2021-01-01-preview Nein Link

Der Kunde muss die neue Konfigurations-API v2 verwenden, indem seine Bereitstellungsskripts geändert werden, um die neue URL zu verwenden und die Infrastrukturanforderungen zu erfüllen.

Wichtig

  • Der DNS-Hostname muss in IP-Adressen auflösbar sein, und die entsprechenden IP-Adressen müssen erreichbar sein. Dies erfordert möglicherweise eine zusätzliche Konfiguration, wenn Sie ein privates DNS, internes VNET oder andere infrastrukturelle Anforderungen verwenden.

Sicherheit

Verfügbare TLS-Verschlüsselungssammlungen

Beim Start verwendet das selbst gehostete Gateway v2.0 nur eine Teilmenge der Verschlüsselungssuiten, die von v1.x verwendet wurde. Ab v2.0.4 werden wieder alle Verschlüsselungsverfahren angezeigt, die von v1.x unterstützt wurden.

Weitere Informationen über die verwendeten Verschlüsselungssuiten sind in diesem Artikel zu finden oder verwenden Sie v2.1.1, um zu steuern, welche Verschlüsselungssuiten verwendet werden sollen.

Erfüllen minimaler Sicherheitsanforderungen

Während des Starts bereitet das selbstgehostete Gateway die verwendeten Zertifizierungsstellenzertifikate vor. Dies erfordert, dass der Gatewaycontainer mindestens mit der Benutzer-ID 1001 ausgeführt wird. Ein schreibgeschütztes Dateisystem kann nicht verwendet wenden.

Beim Konfigurieren eines Sicherheitskontexts für den Container in Kubernetes ist mindestens Folgendes erforderlich:

securityContext:
  runAsNonRoot: true
  runAsUser: 1001
  readOnlyRootFilesystem: false

Ab 2.0.3 kann das selbstgehostete Gateway jedoch in Kubernetes als Nicht-Root ausgeführt zu werden, sodass Kunden das Gateway sicherer ausführen können.

Nachfolgend sehen Sie ein Beispiel für den Sicherheitskontext für das selbstgehostete Gateway:

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

Warnung

Die Ausführung des selbstgehosteten Gateways mit schreibgeschütztem Dateisystem (readOnlyRootFilesystem: true) wird nicht unterstützt.

Bewerten der Auswirkungen mit Azure Advisor

Um die Migration zu erleichtern, haben wir neue Azure Advisor-Empfehlungen eingeführt:

  • Empfehlung Verwenden Sie ein selbstgehostetes Gateway v2: Identifiziert Azure API Management-Instanzen, bei denen die Nutzung von selbstgehostetem Gateway v0.x oder v1.x identifiziert wurde.
  • Empfehlung Verwenden Sie die Konfigurations-API v2 für selbstgehostete Gateways: Identifiziert Azure API Management-Instanzen, bei denen die Nutzung der Konfigurations-API v1 für selbstgehostete Gateways identifiziert wurde.

Wir empfehlen Kunden dringend, die Übersicht über „Alle Empfehlungen“ in Azure Advisor zu verwenden, um festzustellen, ob eine Migration erforderlich ist. Verwenden Sie die Filteroptionen, um festzustellen, ob eine der oben genannten Empfehlungen vorhanden ist.

Verwenden von Azure Resource Graph zum Identifizieren von Azure API Management-Instanzen

Mit dieser Azure Resource Graph-Abfrage wird eine Liste der betroffenen Azure-API Management-Instanzen bereitgestellt:

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"

Bekannte Einschränkungen

Nachfolgend finden Sie eine Liste bekannter Einschränkungen für das selbstgehostete v2-Gateway:

  • Konfigurations-API v2 unterstützt keine benutzerdefinierten Domänennamen

Nächste Schritte