Freigeben über

Migrieren einer in ein VNet eingefügten API Management-Instanz, die auf der stv1-Plattform gehostet wird, zu stv2

  • Artikel

GILT FÜR: Entwickler | Premium

Dieser Artikel enthält Schritte zum direkten Migrieren einer API Management-Instanz, die auf der stv1-Computeplattform gehostet wird, zur stv2-Plattform, wenn die Instanz in ein externes oder internes VNet eingefügt (bzw. in einem solchen bereitgestellt) wird. Ob dies erforderlich ist, erfahren Sie hier.

Hinweis

Neu im August 2024: Um Ihnen bei der Migration Ihrer in vNet eingefügten Instanz zu helfen, haben wir die Migrationsoptionen im Portal verbessert! Sie können ihre Instanz jetzt an Ort und Stelle migrieren und die gleiche Subnetz- und IP-Adresse beibehalten.

Für eine in ein VNet eingefügte Instanz haben Sie die folgenden Migrationsoptionen:

  • Option 1: Dasselbe Subnetz beibehalten: Migrieren Sie die Instanz direkt, und behalten Sie die vorhandene Subnetzkonfiguration der Instanzen bei. Sie können auswählen, ob die ursprüngliche virtuelle IP-Adresse der API Management-Instanz erhalten bleibt (empfohlen) oder ob eine neue VIP-Adresse generiert wird.

  • Option 2: Zu einem neuen Subnetz wechseln: Migrieren Sie Ihre Instanz, indem Sie ein anderes Subnetz in demselben oder einem anderen VNet angeben. Nach der Migration können Sie optional zurück zum ursprünglichen Subnetz der Instanz migrieren. Der Migrationsprozess ändert die virtuellen IP-Adressen der Instanz. Nach der Migration müssen Sie alle Netzwerkabhängigkeiten einschließlich DNS, Firewallregeln und VNets aktualisieren, um die neuen virtuellen IP-Adressen zu verwenden.

Unter bestimmten, selteneren Bedingungen ist die Migration im selben Subnetz möglicherweise nicht möglich oder verhält sich anders. Weitere Informationen finden Sie unter Besondere Bedingungen und Szenarien.

Falls Sie eine nicht in ein VNet eingefügte API Management-Instanz migrieren müssen, die auf der stv1-Plattform gehostet wird, lesen Sie Migrieren einer nicht in ein VNet eingefügten API Management-Instanz zur stv2-Plattform.

Wichtig

Die Unterstützung für API Management-Instanzen, die auf der stv1-Plattform gehostet werden, wird eingestellt. Im globalen Azure ist das Einstellungsdatum der 31. August 2024. In Azure Government und in Azure, betrieben von 21Vianet (Azure in China), ist das Einstellungsdatum der 24. Februar 2025. Wenn Sie Instanzen auf der stv1-Plattform gehostet haben, migrieren Sie sie vor diesem Datum zur stv2-Plattform, um Dienstunterbrechungen zu vermeiden.

Achtung

  • Die Migration Ihrer API Management-Instanz zur stv2-Plattform ist ein zeitintensiver Vorgang.
  • Die Migration zu stv2 ist nicht umkehrbar.

Was geschieht während der Migration?

Die Migration der API Management-Plattform von stv1 zu stv2 umfasst lediglich die Aktualisierung der zugrunde liegenden Computeressource und hat keine Auswirkungen auf die in der Speicherebene gespeicherte Dienst-/API-Konfiguration.

  • Der Upgradeprozess umfasst das Erstellen einer neuen Computeressource parallel zur alten Computeressource. Dies kann bis zu 45 Minuten dauern. Planen Sie einen längeren Zeitraum für Bereitstellungen in mehreren Regionen und in Szenarien, in denen das Subnetz mehrmals geändert werden muss.
  • Der API Management-Status im Azure-Portal lautet Wird aktualisiert.
  • Für bestimmte Migrationsoptionen können Sie die virtuelle IP-Adresse beibehalten oder eine neue öffentliche virtuelle IP-Adresse generieren.
  • Bei Migrationsszenarien, wenn eine neue VIP-Adresse generiert wird:
    • Azure verwaltet die Migration.
    • Bei Verwendung einer benutzerdefinierten Domäne verweist das Gateway-DNS weiterhin auf die alte Computeressource.
    • Wird kein benutzerdefiniertes DNS verwendet, verweisen das Gateway- und das Portal-DNS sofort auf die neue Computeressource.
    • Für eine Instanz im internen VNet-Modus verwaltet der Kunde das DNS, sodass die DNS-Einträge weiterhin auf die alte Computeressource verweisen, bis sie vom Kunden aktualisiert wurden.
    • Das DNS verweist entweder auf die neue oder die alte Computeressource, daher tritt keine Downtime für die APIs auf.
    • Firewallregeln müssen geändert werden (sofern vorhanden), damit das neue Computesubnetz die Back-Ends erreichen kann.
    • Nach erfolgreicher Migration wird die alte Computeressource standardmäßig nach einem kurzen Zeitraum automatisch außer Betrieb genommen. Wenn Sie in ein neues Subnetz wechseln, können Sie im Blatt Plattformmigration im Portal eine Migrationseinstellung aktivieren, um das alte Gateway 48 Stunden lang beizubehalten. Die Option für die 48-stündige Verzögerung ist nur für in das VNet eingefügte Dienste verfügbar.

Voraussetzungen

Weitere Voraussetzungen sind spezifisch für die Migrationsoptionen in den folgenden Abschnitten.

Option 1: Migrieren und dasselbe Subnetz beibehalten

Sie können Ihre API Management-Instanz zur stv2-Plattform migrieren. Dabei wird die vorhandene Subnetzkonfiguration beibehalten. Dies vereinfacht die Migration. Sie können die Migration über das Blatt Plattformmigration im Azure-Portal oder über die REST-API „Migrieren zu Stv2“ durchführen.

Voraussetzungen

  • Eine Netzwerksicherheitsgruppe muss an jedes Subnetz angefügt werden, und NSG-Regeln für API Management müssen auf der stv2-Plattform konfiguriert werden. Im Anschluss sind die Mindesteinstellungen für die Konnektivität aufgeführt:

    • Ausgehend zu Azure Storage über Port 443
    • Ausgehend zu Azure SQL über Port 1433
    • Ausgehend zu Azure Key Vault über Port 443
    • Eingehend von Azure Load Balancer über Port 6390
    • Eingehend vom ApiManagement-Diensttag über Port 3443
    • Eingehend über Port 80/443 für Clients, die den API Management-Dienst aufrufen
    • Das Subnetz muss über Dienstendpunkte verfügen, die für Azure Storage, Azure SQL und Azure Key Vault aktiviert sind.

  • Der Adressraum jedes vorhandenen Subnetzes muss groß genug sein, um eine Kopie Ihres vorhandenen Diensts parallel zum vorhandenen Dienst während der Migration zu hosten.

  • Weitere Überlegungen zum Netzwerk:

    • Deaktivieren Sie alle Autoskalierungsregeln, die für im Subnetz bereitgestellte API Management-Instanzen konfiguriert sind. Autoskalierungsregeln können den Migrationsprozess beeinträchtigen.
    • Wenn Sie über mehrere API Management-Instanzen im selben Subnetz verfügen, migrieren Sie die einzelnen Instanzen nacheinander. Es wird empfohlen, alle Instanzen im Subnetz umgehend zu migrieren, um potenzielle Probleme mit Instanzen zu vermeiden, die auf verschiedenen Plattformen im selben Subnetz gehostet werden.

  • Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Schnellstart für Bash in Azure Cloud Shell.

  • Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.

    • Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.

    • Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.

    • Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.

Optionen für öffentliche IP-Adressen – Migration desselben Subnetzes

Sie können auswählen, ob die ursprüngliche virtuelle IP-Adresse der API Management-Instanz erhalten bleibt (empfohlen) oder ob eine neue VIP-Adresse generiert wird.

  • Virtuelle IP-Adresse beibehalten: Wenn Sie die virtuelle IP-Adresse in einem VNet im externen Modus beibehalten, können API-Anforderungen während der Migration reaktionsfähig bleiben (siehe Erwartete Downtime). Bei einem VNet im internen Modus wird eine vorübergehende Downtime erwartet. Die Infrastrukturkonfiguration (z. B. benutzerdefinierte Domänen, Standorte und Zertifizierungsstellenzertifikate) wird 45 Minuten lang gesperrt. Nach der Migration ist keine weitere Konfiguration erforderlich.

    Bei dieser Option wird die Computeressource stv1 nach Abschluss der Migration endgültig gelöscht. Es gibt keine Möglichkeit, sie vorübergehend beizubehalten.

    Die folgende Abbildung zeigt eine allgemeine Übersicht darüber, was passiert, wenn die IP-Adresse beibehalten wird.

    Diagramm der Migration in dasselbe Subnetz unter Beibehaltung der IP-Adresse.

  • Neue virtuelle IP-Adresse: Wenn Sie diese Option auswählen, generiert API Management eine neue virtuelle IP-Adresse für Ihre Instanz. API-Anforderungen bleiben während der Migration reaktionsfähig. Die Infrastrukturkonfiguration (z. B. benutzerdefinierte Domänen, Standorte und Zertifizierungsstellenzertifikate) wird 30 Minuten lang gesperrt. Nach der Migration müssen Sie alle Netzwerkabhängigkeiten einschließlich DNS, Firewallregeln und VNets aktualisieren, um die neue VIP-Adresse zu verwenden.

    Mit dieser Option wird die Computeressource stv1 standardmäßig nach Abschluss der Migration für eine kurze Zeit aufbewahrt, sodass Sie die migrierte Instanz überprüfen und die Netzwerk- und DNS-Konfiguration bestätigen können.

    Die folgende Abbildung zeigt eine allgemeine Übersicht darüber, was passiert, wenn eine neue IP-Adresse generiert wird.

    Diagramm der Migration in dasselbe Subnetz bei Generierung einer neuen IP-Adresse.

Vorkonfigurierte IP-Adresse für die Migration

Für API Management-Instanzen, die über eine öffentliche IP-Adresse erreichbar sind, erstellt API Management vorab eine öffentliche IP-Adresse für den Migrationsprozess. Suchen Sie die vorab erstellte IP-Adresse in der JSON-Ausgabe der Eigenschaften Ihrer API Management-Instanz. Unter customProperties ist die vorab erstellte IP-Adresse der Wert der Eigenschaft Microsoft.WindowsAzure.ApiManagement.Stv2MigrationPreCreatedIps. Bei einer Bereitstellung mit mehreren Regionen ist der Wert eine durch Trennzeichen getrennte Liste der vorab erstellten IP-Adressen.

Verwenden Sie die vorab erstellte IP-Adresse (bzw. die Adressen), um den Migrationsprozess zu verwalten:

  • Wenn Sie die virtuelle IP-Adresse migrieren und beibehalten, wird die vorab erstellte IP-Adresse vorübergehend der neuen stv2-Bereitstellung zugewiesen, bevor die ursprüngliche IP-Adresse der stv2-Bereitstellung zugewiesen wird. Wenn Sie Firewallregeln haben, die den Zugriff auf die API Management-Instanz einschränken, können Sie beispielsweise die vorab erstellte IP-Adresse zur Positivliste hinzufügen, um die Kontinuität des Clientzugriffs während der Migration zu gewährleisten. Nach Abschluss der Migration können Sie die vorab erstellte IP-Adresse von Ihrer Positivliste entfernen.
  • Wenn Sie migrieren und eine neue virtuelle IP-Adresse generieren, wird die vorab erstellte IP-Adresse während der Migration der neuen stv2-Bereitstellung zugewiesen und nach Abschluss der Migration beibehalten. Verwenden Sie die vorab erstellte IP-Adresse, um Ihre Netzwerkabhängigkeiten wie DNS- und Firewallregeln zu aktualisieren, um auf die neue IP-Adresse zu verweisen.

Erwartete Downtime und Computeaufbewahrung

Wenn Sie eine in ein VNet eingefügte Instanz migrieren und dieselbe Subnetzkonfiguration beibehalten, wird nur minimale oder keine Downtime für das API-Gateway erwartet. In der folgenden Tabelle sind die erwarteten Downtime und die stv1-Computeaufbewahrung für jedes Migrationsszenario zusammengefasst, wenn dasselbe Subnetz beibehalten wird:

VNet-Modus Option mit öffentlicher IP-Adresse Erwartete Downtime stv1-Computeaufbewahrung
Extern Virtuelle IP beibehalten Keine Downtime. Datenverkehr wird für eine temporäre IP-Adresse bis zu 20 Minuten lang während der Migration zur neuen stv2-Bereitstellung verarbeitet. Keine Beibehaltung
Extern Neue virtuelle IP Keine Ausfallzeit Wird standardmäßig 15 Minuten lang aufbewahrt, damit Sie Netzwerkabhängigkeiten aktualisieren können
Intern Virtuelle IP beibehalten Downtime von ca. 20 Minuten während der Migration, während die vorhandene IP-Adresse der neuen stv2-Bereitstellung zugewiesen wird. Keine Beibehaltung
Intern Neue virtuelle IP Keine Ausfallzeit Wird standardmäßig 15 Minuten lang aufbewahrt, damit Sie Netzwerkabhängigkeiten aktualisieren können; kann bei Verwendung des Portals auf bis zu 48 Stunden erweitert werden

Migrationsschritte – Subnetz beibehalten

  1. Navigieren Sie im Azure-Portal zu Ihrer API Management-Instanz.
  2. Wählen Sie im linken Menü unter Einstellungen die Option Plattformmigration aus.
  3. Wählen Sie unter Migrationsoption auswählen Subnetz beibehalten aus.
  4. Wählen Sie unter IP-Adressoptionen auswählen eine der beiden IP-Adressoptionen aus.

    Hinweis

    Wenn sich Ihr VNet im externen Modus befindet, notieren Sie sich die vordefinierte öffentliche IP-Adresse für den Migrationsprozess. Verwenden Sie diese Adresse, um die Netzwerkkonnektivität für Ihre migrierte Instanz zu konfigurieren.

  5. (Für Instanzen, die im internen Modus eingefügt wurden und auf ein neues VIP migriert werden) Wählen Sie unter Wählen Sie das Szenario, das Ihren Anforderungen entspricht eine der beiden Optionen aus, je nachdem, ob Sie die ursprüngliche stv1-Berechnung für eine gewisse Zeit nach der Migration beibehalten möchten.
  6. Wählen Sie Überprüfen aus, um automatisierte Prüfungen im Subnetz auszuführen. Wenn Probleme erkannt werden, passen Sie Ihre Subnetzkonfiguration an, und führen Sie erneut Prüfungen aus. Führen Sie bei anderen Netzwerkabhängigkeiten, z. B. DNS- und Firewallregeln, manuelle Überprüfungen durch.
  7. Bestätigen Sie, dass Sie migrieren möchten, und wählen Sie Migration beginnen aus. Der Status Ihrer API-Verwaltungsinstanz ändert sich in Aktualisieren. Der Migrationsprozess dauert ca. 45 Minuten. Wenn sich der Status in Online ändert, ist die Migration abgeschlossen.

Option 2: Migrieren und zu einem neuen Subnetz wechseln

Sie können mithilfe des Azure-Portals Ihre Instanz migrieren, indem Sie ein anderes Subnetz in demselben oder einem anderen VNet angeben. Nach der Migration können Sie optional zurück zum ursprünglichen Subnetz der Instanz migrieren.

Die folgende Abbildung zeigt eine allgemeine Übersicht über die Abläufe bei der Migration zu einem neuen Subnetz:

Diagramm: Direkte Migration zu einem neuen Subnetz

Voraussetzungen

  • Ein neues Subnetz im aktuellen virtuellen Netzwerk in jeder Region, in der die API Management-Instanz bereitgestellt wird. (Richten Sie alternativ ein Subnetz in einem anderen virtuellen Netzwerk in der gleichen Region und im gleichen Abonnement wie Ihre API Management-Instanz ein.) Eine Netzwerksicherheitsgruppe muss an jedes Subnetz angefügt werden, und NSG-Regeln für API Management müssen auf der stv2-Plattform konfiguriert werden.

  • (Optional) Eine neue Standard-SKU-Ressource mit öffentlicher IPv4-Adresse in der gleichen Region (bzw. in den gleichen Regionen) und im gleichen Abonnement wie Ihre API Management-Instanz. Details finden Sie unter Voraussetzungen für Netzwerkverbindungen.

Wichtig

  • Ab Mai 2024 wird keine öffentliche IP-Adressressource mehr benötigt, wenn eine API Management-Instanz in einem VNet im internen Modus bereitgestellt (injiziert) oder die interne VNet-Konfiguration zu einem neuen Subnetz migriert wird. Im externen VNet-Modus ist die Angabe einer öffentlichen IP-Adresse optional. Wenn Sie keine angeben, wird automatisch eine von Azure verwaltete öffentliche IP-Adresse konfiguriert und für Runtime-API-Datenverkehr verwendet. Geben Sie die öffentliche IP-Adresse nur an, wenn Sie die öffentliche IP-Adresse, die für eingehende oder ausgehende Kommunikation mit dem Internet verwendet wird, besitzen und steuern möchten.

Migrationsschritte – Wechsel zu einem neuen Subnetz

  1. Navigieren Sie im Azure-Portal zu Ihrer API Management-Instanz.

  2. Wählen Sie im linken Menü unter Einstellungen die Option Plattformmigration aus.

  3. Wählen Sie unter Migrationsoption auswählen Zu neuem Subnetz wechseln aus.

  4. Wählen Sie unter Wählen Sie das Szenario, das Ihren Anforderungen entspricht eine der beiden Optionen aus, je nachdem, ob Sie die ursprüngliche stv1-Berechnung für eine gewisse Zeit nach der Migration beibehalten möchten.

    Screenshot der Optionen zum Aufbewahren der stv1-Berechnung im Portal.

  5. Unter Migrationseinstellungen für jeden Speicherort definieren:

    1. Wählen Sie einen zu migrierenden Speicherort aus.
    2. Wählen Sie das virtuelle Netzwerk, Subnetz und optional die Öffentliche IP-Adresse aus, zu der Sie migrieren möchten.

    Screenshot der Auswahl der Netzwerkmigrationseinstellungen im Portal.

  6. Wählen Sie unter Überprüfen, ob Ihr Subnetz die Migrationsanforderungen erfüllt Bestätigen aus, um automatisierte Prüfungen im Subnetz auszuführen. Wenn Probleme erkannt werden, passen Sie Ihre Subnetzkonfiguration an, und führen Sie erneut Prüfungen aus. Führen Sie bei anderen Netzwerkabhängigkeiten, z. B. DNS- und Firewallregeln, manuelle Überprüfungen durch.

  7. Bestätigen Sie, dass Sie migrieren möchten, und wählen Sie Migrieren aus. Der Status Ihrer API-Verwaltungsinstanz ändert sich in Aktualisieren. Der Migrationsprozess dauert ca. 45 Minuten. Wenn sich der Status in Online ändert, ist die Migration abgeschlossen.

Wenn Ihre API-Verwaltungsinstanz in mehreren Regionen bereitgestellt wird, wiederholen Sie die vorherigen Schritte, um die Migration der VNet-Einstellungen für die verbleibenden Speicherorte Ihrer Instanz fortzusetzen.

(Optional) Migrieren zum ursprünglichen Subnetz

Wenn Sie die Migration durchgeführt und zu einem neuen Subnetz gewechselt haben, können Sie optional wieder zum ursprünglichen Subnetz migrieren, das Sie in den einzelnen Regionen verwendet haben. Aktualisieren Sie hierzu erneut die VNet-Konfiguration, und geben Sie dieses Mal in jeder Region das ursprüngliche VNet und Subnetz an. Wie bei der vorherigen Migration sollten Sie sich auf einen Vorgang mit langer Ausführungsdauer einstellen und damit rechnen, dass sich die VIP-Adresse ändert.

Die folgende Abbildung zeigt eine allgemeine Übersicht über die Abläufe bei der Migration zum ursprünglichen Subnetz:

Diagramm: Direkte Migration zum ursprünglichen Subnetz

Wichtig

Falls das VNet und das Subnetz gesperrt sind (weil dort andere, auf der stv1-Plattform basierende API Management-Instanzen bereitgestellt werden) oder die Ressourcengruppe, in der das ursprüngliche VNet bereitgestellt wird, über eine Ressourcensperre verfügt, muss die Sperre vor der Migration zum ursprünglichen Subnetz entfernt werden. Warten Sie, bis das Entfernen der Sperre abgeschlossen ist, bevor Sie versuchen, die Migration zum ursprünglichen Subnetz durchzuführen. Weitere Informationen

Zusätzliche Voraussetzungen

  • Das entsperrte ursprüngliche Subnetz in jeder Region, in der die API Management-Instanz bereitgestellt wird. Eine Netzwerksicherheitsgruppe muss an das Subnetz angefügt werden, und NSG-Regeln für API Management müssen konfiguriert werden.

  • (Optional) Eine neue Standard-SKU-Ressource mit öffentlicher IPv4-Adresse in der gleichen Region (bzw. in den gleichen Regionen) und im gleichen Abonnement wie Ihre API Management-Instanz.

    Wichtig

    • Ab Mai 2024 wird keine öffentliche IP-Adressressource mehr benötigt, wenn eine API Management-Instanz in einem VNet im internen Modus bereitgestellt (injiziert) oder die interne VNet-Konfiguration zu einem neuen Subnetz migriert wird. Im externen VNet-Modus ist die Angabe einer öffentlichen IP-Adresse optional. Wenn Sie keine angeben, wird automatisch eine von Azure verwaltete öffentliche IP-Adresse konfiguriert und für Runtime-API-Datenverkehr verwendet. Geben Sie die öffentliche IP-Adresse nur an, wenn Sie die öffentliche IP-Adresse, die für eingehende oder ausgehende Kommunikation mit dem Internet verwendet wird, besitzen und steuern möchten.

Aktualisieren von VNet-Konfigurationen

  1. Navigieren Sie im Portal zu Ihrem ursprünglichen VNet.
  2. Wählen Sie im Menü auf der linken Seite Subnetze und dann das ursprüngliche Subnetz aus.
  3. Überprüfen Sie, ob die ursprünglichen IP-Adressen von API Management freigegeben wurden. Notieren Sie sich unter Verfügbare IP-Adressen die Anzahl der im Subnetz verfügbaren IP-Adressen. Alle Adressen (mit Ausnahme von reservierten Azure-Adressen) sollten verfügbar sein. Warten Sie bei Bedarf, bis IP-Adressen freigegeben werden.
  4. Navigieren Sie zu Ihrer API Management-Instanz.
  5. Wählen Sie im linken Menü unter Netzwerk virtuelles Netzwerk aus.
  6. Wählen Sie die Netzwerkverbindung an dem Standort aus, den Sie aktualisieren möchten.
  7. Wählen Sie das ursprüngliche VNet-Netzwerk und das Subnetz aus. Wählen Sie optional eine neue öffentliche IP aus. Wählen Sie Übernehmen.
  8. Wenn Ihre API-Verwaltungsinstanz in mehreren Regionen bereitgestellt wird, konfigurieren Sie weiterhin die VNet-Einstellungen für die verbleibenden Speicherorte Ihrer Instanz.
  9. Wählen Sie auf der oberen Navigationsleiste die Option Speichern aus.

Nachdem Sie die VNet-Konfiguration aktualisiert haben, ändert sich der Status Ihrer API Management-Instanz in Wird aktualisiert. Der Migrationsprozess dauert ca. 45 Minuten. Wenn sich der Status in Online ändert, ist die Migration abgeschlossen.

Überprüfen der Migration

Überprüfen Sie die Plattformversion Ihrer API Management-Instanz, wenn sich der Status in Online ändert, um sich zu vergewissern, dass die Migration erfolgreich war. Nach erfolgreicher Migration lautet der Wert stv2 oder stv2.1.

Bestätigen der Einstellungen vor dem endgültigen Löschen des alten Gateways

Bei Szenarien, in denen das alte Gateway nach der Migration vorübergehend beibehalten wird, sind die alte und die während der Migration erstellte neue Computeressource etwa 15 Minuten lang parallel vorhanden. In diesem Zeitfenster können Sie die Bereitstellung überprüfen und sich vergewissern, dass Ihre Anwendungen erwartungsgemäß funktionieren. Für bestimmte Szenarien können Sie optional den Aufbewahrungszeitraum über eine Portaleinstellung auf 48 Stunden verlängern.

  • Während dieses Zeitfensters ist sowohl das alte als auch das neue Gateway online und verarbeitet Datenverkehr. Diese Zeit wird Ihnen nicht in Rechnung gestellt.
  • Nutzen Sie dieses Zeitfenster, um etwaige Netzwerkabhängigkeiten einschließlich DNS, Firewallregeln und VNets für die Verwendung der neuen VIP-Adresse und des neuen Subnetzadressraums zu aktualisieren.
  • Überprüfen Sie außerdem den Netzwerkstatus der aktualisierten Instanz, um die Konnektivität der Instanz mit ihren Abhängigkeiten sicherzustellen. Wählen Sie im Portal im linken Menü unter Bereitstellung und Infrastruktur die Option Netzwerk>Netzwerkstatus aus. Aktualisieren Sie bei Bedarf Einstellungen wie UDRs und NSG-Regeln.
  • Am Ende des Zeitfensters wird das alte Gateway außer Betrieb gesetzt, und Datenverkehr wird nur noch vom neuen Gateway verarbeitet.

Automatisches Zurücksetzen, wenn die Migration fehlschlägt

Wenn während des Migrationsprozesses ein Fehler auftritt, wird die Instanz automatisch auf die stv1-Plattform zurückgesetzt. Nach erfolgreichem Abschluss der Migration (für die Plattformversion der Instanz wird stv2 oder stv2.1 und für den Status wird Online angezeigt) ist kein Rollback zur stv1-Plattform mehr möglich.

Im Falle einer nicht erfolgreichen Migration erhalten Sie Hilfe vom Azure-Support.

Wenn Sie die Möglichkeit benötigen, ein manuelles Rollback auszuführen, empfiehlt es sich, eine neue stv2-Instanz parallel zu Ihrer ursprünglichen API Management-Instanz bereitzustellen.

Besondere Bedingungen und Szenarien

Unter bestimmten Bedingungen ist Option 1: Migrieren und gleiches Subnetz beibehalten möglicherweise nicht verfügbar oder verhält sich anders. Das Portal erkennt diese Bedingungen und empfiehlt die Migrationsoption(en). Wenn Sie Option 1 nicht verwenden können oder mehrere Bedingungen vorliegen, verwenden Sie Option 2: Zu einem neuen Subnetz wechseln.

  • VNet mit besonderen internen Bedingungen – Wenn Ihre API Management-Instanz derzeit in einem VNet mit besonderen internen Bedingungen (unabhängig von der Kundenkonfiguration) bereitgestellt wird, werden Sie im Portal benachrichtigt, dass Option 1 für die Migration in dasselbe Subnetz im Portal zusätzliche Ausfallzeiten (ca. 1 Stunde) beinhaltet. Die Verwendung des Portals für die Migration wird empfohlen. Sie können auch das folgende modifizierte Azure CLI-Skript für die Migration innerhalb desselben Subnetzes mit einer Ausfallzeit von ca. 1 Stunde verwenden:

    APIM_NAME={name of your API Management instance}
# In PowerShell, use the following syntax: $APIM_NAME={name of your API Management instance}
RG_NAME={name of your resource group} 
# Get resource ID of API Management instance
APIM_RESOURCE_ID=$(az apim show --name $APIM_NAME --resource-group $RG_NAME --query id --output tsv)
# Call REST API to migrate to stv2 and preserve VIP address for special condition
az rest --method post --uri "$APIM_RESOURCE_ID/migrateToStv2?api-version=2024-06-01-preview&migrateWithDowntime=true" --body '{"mode": "PreserveIP"}'

  • Mehrere stv1-Instanzen im Subnetz – Wenn Sie versuchen, die Instanzen gleichzeitig zu migrieren, stehen möglicherweise nicht genügend freie IP-Adressen für eine Migration innerhalb desselben Subnetzes zur Verfügung. Möglicherweise können Sie Instanzen nacheinander mithilfe von Option 1 migrieren.

  • Subnetzdelegierung – Wenn das Subnetz, in dem API Management bereitgestellt wird, derzeit an andere Azure-Dienste delegiert ist, müssen Sie die Migration mit Option 2 durchführen.

  • Azure Key Vault blockiert – Wenn der Zugriff auf Azure Key Vault derzeit blockiert ist, müssen Sie die Migration mit Option 2 durchführen, einschließlich der Einrichtung von NSG-Regeln im neuen Subnetz für den Zugriff auf Azure Key Vault.

Hilfe und Support

Wir helfen Ihnen bei der Migration zur stv2-Plattform mit minimalen Unterbrechungen für Ihre Dienste.

Bei Fragen können Sie schnelle Antworten von Communityexperten auf Microsoft Q&A erhalten. Wenn Sie über einen Supportplan verfügen und technische Hilfe benötigen, erstellen Sie eine Supportanfrage.

  1. Geben Sie als Zusammenfassung eine Beschreibung Ihres Problems ein, z. B. „stv1 Einstellung“.
  2. Wählen Sie unter Problemtyp die Option Technisch aus.
  3. Wählen Sie unter Abonnement Ihr Abonnement aus.
  4. Wählen Sie unter Dienst die Option Meine Dienste und dann API Management-Dienst aus.
  5. Wählen Sie unter Ressource die Azure-Ressource aus, für die Sie eine Supportanfrage erstellen.
  6. Wählen Sie als Problemtyp die Option Administration und Verwaltung aus.
  7. Wählen Sie als Problemuntertyp die Option Upgrade, Skalierung oder SKU-Änderungen aus.

Häufig gestellte Fragen

  • Welche Informationen benötigen wir für die Auswahl eines Migrationspfads?

    • Wie lautet der Netzwerkmodus der API Management-Instanz?
    • Sind benutzerdefinierte Domänen konfiguriert?
    • Ist eine Firewall beteiligt?
    • Gibt es bekannte Upstream- oder Downstreamabhängigkeiten für die beteiligten IP-Adressen?
    • Handelt es sich um eine Bereitstellung in mehreren Regionen?
    • Können wir die vorhandene Instanz ändern, oder ist ein paralleles Setup erforderlich?
    • Darf es Downtime geben?
    • Kann die Migration außerhalb der Geschäftszeiten durchgeführt werden?

  • Wie lauten die Voraussetzungen für die Migration?

    Informationen zu in ein VNet eingefügten Instanzen finden Sie in den Voraussetzungen für die Optionen Migrieren und dasselbe Subnetz beibehalten oder Migrieren und zu einem neuen Subnetz wechseln.

  • Verursacht die Migration Downtime?

    Wenn Sie eine in ein VNet eingefügte Instanz migrieren und dieselbe Subnetzkonfiguration beibehalten, wird nur minimale oder keine Downtime für das API-Gateway erwartet. Weitere Informationen finden Sie in der Zusammenfassungstabelle unter Erwartete Downtime.

    Wenn Sie zu migrieren und zu einer neuen virtuellen IP-Adresse wechseln, sollte es keine Downtime geben, wenn Standardhostnamen verwendet werden. Es ist wichtig, dass alle Netzwerkabhängigkeiten vorab behandelt werden, damit die betroffenen APIs funktionsfähig sind. Wenn jedoch benutzerdefinierte Domänen verwendet werden, verweisen sie auf die gelöschte Berechnung, bis sie aktualisiert werden, was zu einer Ausfallzeit führen kann. Alternativ können Sie bei bestimmten Migrationsoptionen eine Migrationseinstellung aktivieren, um das alte Gateway 48 Stunden lang beizubehalten. Wenn die alte und die neue Compute koexistieren, wird die Überprüfung erleichtert, und Sie können dann die benutzerdefinierten DNS-Einträge bei Bedarf aktualisieren.

  • Für meinen Datenverkehr wird Tunneling durch eine Firewall erzwungen. Welche Änderungen sind erforderlich?

    • Stellen Sie zunächst sicher, dass die Subnetze, die Sie für die Migration verwenden, die folgende Konfiguration behalten (sie sollten bereits konfiguriert sein, wenn Sie migrieren und das aktuelle Subnetz beibehalten):
      • Aktivieren Sie Dienstendpunkte wie hier beschrieben.
      • Für die benutzerdefinierte Route (User-Defined Route, UDR) ist der Hop des ApiManagement-Diensttags auf „Internet“ und nicht nur auf Ihre Firewalladresse festgelegt.
    • Die Anforderungen für die NSG-Konfiguration für stv2 bleiben unverändert, unabhängig davon, ob Sie über eine Firewall verfügen oder nicht. Stellen Sie jedoch sicher, dass das neue Subnetz darüber verfügt.
    • Firewallregeln, die sich auf den aktuellen IP-Adressbereich der API Management-Instanz beziehen, müssen aktualisiert werden, damit sie den IP-Adressbereich Ihres neuen Subnetzes verwenden.

  • Kann es durch die bzw. während der Migration zu Daten- oder Konfigurationsverlusten kommen?

    Bei der Migration von stv1 zu stv2 wird nur die Computeplattform aktualisiert. Die interne Speicherebene wird nicht geändert. Daher ist die gesamte Konfiguration während des Migrationsprozesses sicher. Somit bleibt auch die systemseitig zugewiesene verwaltete Identität erhalten (sofern aktiviert).

  • Bestätigen, dass die Migration abgeschlossen ist und erfolgreich war

    Die Migration gilt als abgeschlossen und erfolgreich, wenn der Status auf der Seite Übersicht Online zusammen mit der Plattformversion gelesen wird, die entweder stv2 oder stv2.1 ist. Überprüfen Sie außerdem, ob der Netzwerkstatus auf dem Blatt Netzwerk für alle erforderlichen Verbindungen grün angezeigt wird.

  • Kann ich die Migration über das Portal durchführen?

    Ja. In ein VNet eingefügte Instanzen können über das Blatt Plattformmigration migriert werden.

  • Kann ich die IP-Adresse der Instanz beibehalten?

    Ja, das Blatt Plattformmigration im Portal und die REST-API verfügt über Optionen, um die IP-Adresse beizubehalten.

  • Gibt es einen Migrationspfad, ohne dass die vorhandene Instanz geändert werden muss?

    Ja. Hierzu ist eine parallele Migration erforderlich. Das bedeutet, dass Sie parallel zu Ihrer aktuellen Instanz eine neue API Management-Instanz erstellen und die Konfiguration in die neue Instanz kopieren.

  • Was passiert, wenn die Migration nicht erfolgreich abgeschlossen werden kann?

    Wenn für Ihre API Management-Instanz nicht die Plattformversion stv2 oder stv2.1 und nicht der Status Online anzeigt werden, nachdem Sie die Migration initiiert haben, war sie wahrscheinlich nicht erfolgreich. Ihr Dienst wird automatisch auf die alte Instanz zurückgesetzt, und es werden keine Änderungen vorgenommen.

  • Welche Funktionalität ist während der Migration nicht verfügbar?

    API-Anforderungen bleiben während der Migration reaktionsfähig. Die Infrastrukturkonfiguration (z. B. benutzerdefinierte Domänen, Standorte und Zertifizierungsstellenzertifikate) wird 30 Minuten lang gesperrt.

  • Wie lange dauert die Migration?

    Eine Migration zu einer neuen VNet-Konfiguration dauert voraussichtlich etwa 45 Minuten. Überprüfen Sie, ob der Status Ihrer Instanz wieder Online und nicht mehr Wird aktualisiert lautet, um zu ermitteln, ob die Migration bereits ausgeführt wurde. Planen Sie einen längeren Zeitraum für Bereitstellungen in mehreren Regionen und in Szenarien, in denen das Subnetz mehrmals geändert werden muss.

  • Gibt es eine Möglichkeit, die VNet-Konfiguration vor einer Migration zu überprüfen?

    Wenn Sie das Subnetz während der Migration ändern möchten, können Sie eine neue API Management-Instanz mit dem VNet, dem Subnetz und (optional) der IP-Adressressourcen bereitstellen, die Sie für die tatsächliche Migration verwenden. Navigieren Sie nach Abschluss der Bereitstellung zur Seite Netzwerkstatus, und überprüfen Sie, ob der Status für alle Endpunktverbindungen grün ist. Falls ja, können Sie diese neue API Management-Instanz entfernen und mit der tatsächlichen Migration mit Ihrem ursprünglichen, auf stv1 gehosteten Dienst fortfahren.

  • Kann ich bei Bedarf ein Rollback für die Migration ausführen?

    Wenn während des Migrationsprozesses ein Fehler auftritt, wird automatisch ein Rollback der Instanz auf die stv1-Plattform ausgeführt. Nach erfolgreicher Migration des Diensts können Sie jedoch kein Rollback mehr auf die stv1-Plattform ausführen.

  • Sind Änderungen an benutzerdefinierten Domänen/privaten DNS-Zonen erforderlich?

    Bei in ein VNet eingefügten Instanzen im internen Modus müssen Sie beim Wechseln zu einer neuen virtuellen IP die privaten DNS-Zonen auf die neue VNet-IP-Adresse aktualisieren, die nach der Migration bezogen wurde. Achten Sie darauf, auch DNS-Zonen zu aktualisieren, die keine Azure DNS-Zonen sind (z. B. Ihre lokalen DNS-Server, die auf die private IP-Adresse von API Management verweisen). Im externen Modus aktualisiert der Migrationsprozess jedoch automatisch die Standarddomänen, sofern sie verwendet werden.

  • Meine stv1-Instanz wird in mehreren Azure-Regionen bereitgestellt. Wie führe ich ein Upgrade auf stv2 aus?

    Bereitstellungen in mehreren Regionen umfassen mehr verwaltete Gateways, die an anderen Standorten bereitgestellt werden. Wenn Sie zum Migrieren das Blatt Plattformmigration im Portal nutzen, migrieren Sie jeden Standort separat. Die REST-API zum Migrieren zu Stv2 migriert alle Standorte in einem Aufruf. Die Instanz wird nur dann als zur neuen Plattform migriert betrachtet, wenn alle Standorte migriert wurden. Alle regionalen Gateways werden während des gesamten Migrationsprozesses weiterhin normal ausgeführt.

  • Kann ich meine stv1-Instanz auf dasselbe Subnetz aktualisieren?

    Ja, verwenden Sie das Blatt Plattformmigration im Azure-Portal oder die REST-API „Migrieren zu stv2“.

  • Kann ich das neue Gateway in einem neuen Subnetz vor der Umstellung des Livedatenverkehrs testen?

    • Wenn Sie in ein neues Subnetz migrieren, koexistieren die alten und neuen verwalteten Gateways standardmäßig für 15 Minuten. Das ist ein kleines Zeitfenster, um die Bereitstellung zu überprüfen. Sie können eine Migrationseinstellung aktivieren, um das alte Gateway 48 Stunden lang beizubehalten. Diese Änderung behält die alten und die neuen verwalteten Gateways aktiv bei, um den Datenverkehr zu empfangen und die Validierung zu erleichtern.
    • Der Migrationsprozess aktualisiert automatisch die Standarddomänennamen und leitet den Datenverkehr, sofern er verwendet wird, sofort an die neuen Gateways weiter.
    • Wenn benutzerdefinierte Domänennamen verwendet werden, müssen die entsprechenden DNS-Einträge möglicherweise mit der neuen IP-Adresse aktualisiert werden, wenn kein CNAME-Eintrag verwendet wird. Kunden können ihre Hostdatei auf die neue API Management-IP-Adresse aktualisieren und die Instanz überprüfen, bevor sie die Umstellung vornehmen. Während dieses Überprüfungsprozesses verarbeitet das alte Gateway weiterhin den Livedatenverkehr.

  • Gibt es Überlegungen bei der Verwendung des Standarddomänennamens in einem neuen Subnetz?

    Bei Instanzen, die den standardmäßigen DNS-Namen im externen Modus verwenden, wird das DNS beim Migrationsprozess automatisch aktualisiert. Darüber hinaus wird der Verwaltungsendpunkt (der immer den Standarddomänennamen verwendet) automatisch durch den Migrationsprozess aktualisiert. Da die Umstellung bei einer erfolgreichen Migration sofort erfolgt, empfängt die neue Instanz sofort Datenverkehr. Es ist wichtig, dass alle Netzwerkeinschränkungen/-abhängigkeiten vorab behandelt werden, um zu verhindern, dass betroffene APIs nicht verfügbar sind.

  • Was sollten wir bei selbstgehosteten Gateways berücksichtigen?

    Sie müssen für Ihre selbstgehosteten Gateways keine Schritte unternehmen. Sie müssen nur in Azure ausgeführte API Management-Instanzen migrieren, die von der Einstellung der stv1-Plattform betroffen sind. Beachten Sie, dass es u. U. eine neue IP-Adresse für den Konfigurationsendpunkt der API Management-Instanz gibt. Daher müssen alle an die IP-Adresse angehefteten Netzwerkeinschränkungen aktualisiert werden.

  • Wie wirkt sich die Migration auf das Entwicklerportal aus?

    Es gibt keine Auswirkungen auf das Entwicklerportal. Wenn benutzerdefinierte Domänen verwendet werden, sollte der DNS-Eintrag nach der Migration mit der effektiven IP-Adresse aktualisiert werden. Wenn jedoch die Standarddomänen verwendet werden, werden sie bei erfolgreicher Migration automatisch aktualisiert. Während der Migration gibt es keine Downtime für das Entwicklerportal.

  • Gibt es nach der Migration zu stv2 Auswirkungen auf die Kosten?

    Das Abrechnungsmodell bleibt für stv2 gleich, und während sowie nach der Migration entstehen keine weiteren Kosten.

  • Welche RBAC-Berechtigungen sind für die Migration von stv1 zu stv2 erforderlich?

    Der Benutzer/Prozess, der die Migration durchführt, benötigt Schreibzugriff auf die API Management-Instanz. Außerdem werden die beiden folgenden Berechtigungen benötigt:

    • Microsoft.Network/virtualNetworks/subnets/join/action
    • Microsoft.Network/publicIPAddresses/join/action

Zugehöriger Inhalt