Migrer une instance de Gestion des API non injectée dans le VNet vers la plateforme de calcul stv2

S’APPLIQUE À : Développeur | Essentiel | Standard | Premium

Cet article décrit les étapes de migration d’une instance Gestion des API hébergée sur la plateforme de calcul stv1 sur place vers la plateforme stv2 lorsque l’instance n’est pas injectée (déployée) dans un VNet externe ou interne. Pour ce scénario, migrez votre instance à l’aide du Portail Microsoft Azure ou de l’API REST Migrer vers stv2. Déterminez si vous avez besoin de le faire.

Si vous devez migrer une gestion des API injectée par un VNet hébergée sur la plateforme stv1, consultez Migrer une instance de Gestion des API injectée par un VNet vers la plateforme stv2.

Que se passe-t-il pendant la migration ?

La migration de la plateforme Gestion des API de stv1 vers stv2 implique la mise à jour du calcul sous-jacent uniquement et n’a aucun impact sur la configuration du service/des API conservés dans la couche de stockage. Pour une instance qui n'est pas déployée dans un VNet :

• Vous pouvez choisir si l’adresse IP virtuelle de l’instance change ou si l’adresse IP virtuelle d’origine est conservée.
• Le processus de mise à niveau implique la création d’un nouveau calcul en parallèle avec l’ancien calcul.
• L’état de Gestion des API dans le portail est Mise à jour.
• Si vous choisissez de conserver l'adresse du VIP, la migration comprend une étape supplémentaire consistant à déplacer le VIP de l'ancien calcul vers le nouveau calcul, au cours de laquelle les API ne répondront pas.
• Azure gère le DNS du point de terminaison de gestion et fait la mise à jour vers le nouveau calcul immédiatement après la migration.
• La passerelle par défaut et le portail DNS pointent immédiatement vers le nouveau calculateur.
• Si vous choisissez de faire en sorte que votre instance de Gestion des API reçoive une nouvelle adresse VIP, vous devrez mettre à jour les dépendances du réseau afin d'utiliser la nouvelle adresse VIP.

Prérequis

• Une instance Gestion des API hébergée sur la plateforme de calcul stv1. Pour vérifier que votre instance est bien hébergée sur la plateforme stv1, consultez Comment faire pour savoir quelle plateforme héberge mon instance Gestion des API ?

• Utilisez l’environnement Bash dans Azure Cloud Shell. Pour plus d’informations, consultez Démarrage rapide pour Bash dans Azure Cloud Shell.

  

• Si vous préférez exécuter les commandes de référence de l’interface de ligne de commande localement, installez l’interface Azure CLI. Si vous exécutez sur Windows ou macOS, envisagez d’exécuter Azure CLI dans un conteneur Docker. Pour plus d’informations, consultez Guide pratique pour exécuter Azure CLI dans un conteneur Docker.

  • Si vous utilisez une installation locale, connectez-vous à Azure CLI à l’aide de la commande az login. Pour finir le processus d’authentification, suivez les étapes affichées dans votre terminal. Pour connaître les autres options de connexion, consultez Se connecter avec Azure CLI.

  • Lorsque vous y êtes invité, installez l’extension Azure CLI lors de la première utilisation. Pour plus d’informations sur les extensions, consultez Utiliser des extensions avec Azure CLI.

  • Exécutez az version pour rechercher la version et les bibliothèques dépendantes installées. Pour effectuer une mise à niveau vers la dernière version, exécutez az upgrade.

Migrer l’instance vers la plateforme stv2

Options de l’adresse IP publique

Vous pouvez choisir si l’adresse IP virtuelle de Gestion des API change ou si l’adresse IP virtuelle d’origine est conservée.

• Nouvelle adresse IP virtuelle : si vous choisissez ce mode, les demandes d’API restent réactives pendant la migration. La configuration de l’infrastructure (par exemple, les domaines personnalisés, les emplacements et les certificats d’autorité de certification) est verrouillée pendant 30 minutes. Après la migration, vous devez mettre à jour toutes les dépendances réseau, notamment DNS, règles de pare-feu et réseaux virtuels pour utiliser la nouvelle adresse IP virtuelle.

• conserver l’adresse IP : si vous conservez l’adresse IP virtuelle, les demandes d’API ne répondront pas pendant environ 15 minutes pendant la migration de l’adresse IP vers la nouvelle infrastructure. La configuration de l’infrastructure (par exemple, les domaines personnalisés, les emplacements et les certificats d’autorité de certification) est verrouillée pendant 45 minutes. Aucune configuration supplémentaire n'est nécessaire après la migration.

Adresse IP pré-créée pour une migration

Pour les instances Gestion des API accessibles par un adresse IP publique, Gestion des API crée au préalable une adresse IP publique pour le processus de migration. Recherchez l’adresse IP pré-créée dans la sortie JSON des propriétés de votre instance Gestion des API. Sous customProperties, l’adresse IP pré-créée est la valeur de la propriété Microsoft.WindowsAzure.ApiManagement.Stv2MigrationPreCreatedIps. Pour un déploiement multirégional, la valeur est une liste séparée par des virgules d’adresses IP pré-créées.

Utilisez l’adresse IP pré-créée (ou adresses) pour vous aider à gérer le processus de migration :

• Lorsque vous migrez ou conservez l’adresse IP, l’adresse IP pré-créée est attribuée au nouveau déploiement stv2 temporairement, avant l’attribution de l’adresse IP d’origine au déploiement stv2. Si vous avez des règles de pare-feu limitant l’accès à l’instance Gestion des API, vous pouvez par exemple ajouter l’adresse IP pré-créée à la liste d’autorisation pour préserver la continuité de l’accès client pendant la migration. Après avoir effectué la migration, vous pouvez supprimer l’adresse IP pré-créée de la liste d’autorisation.
• Quand vous migrez et générez une nouvelle adresse IP virtuelle, l’adresse IP pré-créée est attribuée au nouveau déploiement stv2 pendant la migration et persiste après l’achèvement de la migration. Utilisez l’adresse IP pré-créée pour mettre à jour vos dépendances réseau, comme les règles de pare-feu et DNS, à pointer vers la nouvelle adresse IP.

Étapes de la migration

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
az rest --method post --uri "$APIM_RESOURCE_ID/migrateToStv2?api-version=2023-03-01-preview" --body '{"mode": "PreserveIp"}'
# Alternate call to migrate to stv2 and change VIP address
# az rest --method post --uri "$APIM_RESOURCE_ID/migrateToStv2?api-version=2023-03-01-preview" --body '{"mode": "NewIp"}'

Vérifier la migration

Pour vérifier que la migration a réussi, quand l’état devient En ligne, vérifiez la version de plateforme de votre instance Gestion des API. Une fois la migration correctement effectuée, la valeur est stv2 ou stv2.1.

Restaurer automatiquement en cas d’échec de la migration

En cas de défaillance pendant le processus de migration, l’instance restaure automatiquement la plateforme stv1. Si la migration s’effectue correctement (la version de la plateforme de l’instance s’affiche sous la forme stv2 ou stv2.1 et l’état en tant que En ligne), vous ne pouvez pas revenir à la plateforme stv1.

En cas d'échec de la migration, contactez le support Azure.

Si vous avez besoin de la fonctionnalité de restauration manuelle, la suggestion consiste à déployer une nouvelle stv2 instance côte à côte avec votre instance de Gestion des API d’origine.

Mettre à jour les dépendances réseau

Après la migration vers une nouvelle adresse IP virtuelle, mettez à jour toutes les dépendances réseau, notamment le DNS, les règles de pare-feu et les VNets pour qu’ils utilisent la nouvelle adresse IP virtuelle.

Aide et support

Nous vous proposons ici de vous aider à migrer vers la plateforme stv2 avec un minimum d’interruptions pour vos services.

Si vous avez des questions, interrogez les experts de la communauté dans Microsoft Q&A et obtenez des réponses rapides. Si vous disposez d’un plan de support et que vous avez besoin d’une aide technique, créez une demande de support.

1. Pour Résumé, tapez une description de votre problème, par exemple « mise hors service stv1 ».
2. Sous Type de problème, sélectionnez Technique.
3. Sous Abonnement, sélectionnez votre abonnement.
4. Sous Service, sélectionnez Mes services, puis Service de gestion des API.
5. Sous Ressource, sélectionnez la ressource Azure pour laquelle vous créez une demande de support.
6. Pour le Type de problème, sélectionnez Administration et gestion.
7. Pour le Sous-type de problème, sélectionnez Mettre à niveau, Mettre à l’échelle ou Modifier la référence SKU.

Forum aux questions

• De quelles informations avons-nous besoin pour choisir un chemin de migration ?

  • Quel est le mode de réseau de l’instance Gestion des API ?
  • Des domaines personnalisés sont-ils configurés ?
  • Un pare-feu est-il impliqué ?
  • Des dépendances connues prises en amont/en aval sur les IP sont-elles impliquées ?
  • Est-ce un déploiement dans plusieurs régions ?
  • Pouvons-nous modifier l’instance existante ou une configuration parallèle est-elle nécessaire ?
  • Peut-il y avoir un temps d’arrêt ?
  • La migration peut-elle être effectuée en dehors des heures de travail ?

• Quels sont les prérequis de la migration ?

  Pour les instances non injectées dans un VNet, aucun prérequis. Si vous migrez en conservant votre adresse IP publique, votre instance Gestion des API ne répond plus pendant environ 15 minutes. Il se peut qu’il n’y ait pas de temps d’arrêt si vous choisissez l’option Nouvelle adresse IP virtuelle qui rend la Gestion des API disponible sur une nouvelle adresse IP. Les instances configurées avec un domaine personnalisé utilisant un enregistrement A et/ou ayant des dépendances réseau sur l'adresse IP virtuelle publique auront un temps d'arrêt lorsqu'une nouvelle adresse IP virtuelle est demandée.

• La migration entraîne-t-elle un temps d’arrêt ?

  Pour les instances non injectées dans un VNet, il y a un temps d’arrêt d’environ 15 minutes uniquement si vous choisissez de conserver l’adresse IP d’origine. Cependant, il n'y a pas de temps d'arrêt si vous migrez avec une nouvelle adresse IP et que vous n'avez pas de dépendances de réseau sur la nouvelle IP. Les dépendances du réseau comprennent un nom de domaine personnalisé sans CNAME, une liste d'autorisations IP, des règles de pare-feu et des réseaux virtuels.

• Les données ou les pertes de configuration peuvent-elles se produire par ou pendant la migration ?

  La migration de stv1 vers stv2 implique la mise à jour de la plateforme de calcul uniquement, la couche de stockage interne n’est pas changée. Par conséquent, toute la configuration est protégée pendant le processus de migration. Cela inclut l'identité managée affectée par le système, qui est préservée si elle est activée.

• Comment vérifier que la migration est terminée et réussie ?

  La migration est considérée terminée et réussie quand l’état dans la page de présentation indique En ligne ainsi que la version de plateforme stv2 ou stv2.1. Vérifiez également que l’état du réseau dans le panneau Réseau affiche en vert toutes les connectivités nécessaires.

• Puis-je effectuer la migration à partir du portail ?

  Oui, le panneau Migration de plateforme dans le Portail Microsoft Azure vous décrit les migrations des instances non injectées dans un VNet.

• Puis-je conserver l’adresse IP de l’instance ?

  Oui, l’adresse IP peut être conservée, mais il y a un temps d’arrêt d’environ 15 minutes.

• Existe-t-il un chemin de migration qui ne modifie pas l’instance existante ?

  Oui, vous avez besoin d’une migration côte à côte. Cela signifie que vous créez une instance Gestion des API en parallèle de votre instance actuelle et copiez la configuration sur la nouvelle instance.

• Que se passe-t-il si la migration échoue ?

  Si votre instance Gestion des API n’affiche pas la version de plateforme stv2 ou stv2.1 et l’état En ligne une fois la migration lancée, c’est qu’elle a probablement échoué. Votre service est automatiquement restauré sur l’ancienne instance et aucun changement n’est effectué. Si vous rencontrez des problèmes (par exemple, si l’état est Mise à jour pendant plus de 2 heures), contactez le support Azure.

• Quelle fonctionnalité n’est pas disponible pendant la migration ?

  Pour les instances non injectées par un VNet :

  • Si vous choisissez de conserver l’adresse IP d’origine : les demandes d’API ne répondent pas pendant environ 15 minutes pendant la migration de l’adresse IP vers la nouvelle infrastructure. La configuration de l’infrastructure (par exemple, les domaines personnalisés, les localisations et les certificats d’autorité de certification) est verrouillée pendant 45 minutes.
  • Si vous avez choisi de migrer vers une nouvelle adresse IP : les demandes d’API restent réactives pendant la migration. La configuration de l’infrastructure (par exemple, les domaines personnalisés, les localisations et les certificats d’autorité de certification) est verrouillée pendant 30 minutes. Après la migration, vous devez mettre à jour toutes les dépendances réseau, notamment DNS, règles de pare-feu et réseaux virtuels pour utiliser la nouvelle adresse IP virtuelle.

• Combien de temps prend la migration ?

  La durée attendue pour l’ensemble de la migration est d’environ 45 minutes. Pour voir si la migration a déjà été effectuée, vérifiez si l’état de votre instance est En ligne de nouveau et pas Mise à jour. S’il indique Mise à jour pendant plus de 2 heures, contactez le support Azure.

• Puis-je restaurer la migration si nécessaire ?

  En cas de défaillance pendant le processus de migration, l’instance restaure automatiquement la plateforme stv1. Toutefois, une fois le service migré avec succès, vous ne pouvez pas revenir à la plateforme stv1.

• Des changements sont-il nécessaires dans les domaines personnalisés ou les zones DNS privées ?

  Pour les instances non injectées dans un VNet, aucun changement n’est nécessaire si l’adresse IP est conservée. Si vous avez choisi une nouvelle IP, les domaines personnalisés référençant l’IP doivent être mis à jour.

• Mon instance stv1 est déployée sur plusieurs régions Azure (multi-région). Comment effectuer la mise à niveau vers stv2 ?

  Pour une Gestion des API qui n’est pas injectée dans un VNet, suivez les étapes de migration à l’aide du portail ou d'Azure CLI. Toutes les régions seront migrées vers stv2.

• Quels sont les points à prendre en compte pour les passerelles auto-hébergées ?

  Vous n’avez pas besoin de faire quoi que ce soit dans vos passerelles auto-hébergées. Vous devez simplement migrer les instances Gestion des API qui s’exécutent dans Azure et sont impactées par la mise hors service de la plateforme stv1. Notez qu’il peut y avoir une nouvelle IP pour le point de terminaison de configuration de l’instance Gestion des API, et toutes les restrictions réseau épinglées à l’IP doivent être mises à jour.

• Comment le portail des développeurs est-il impacté par la migration ?

  Il n’y a aucun impact sur le portail des développeurs. Si des domaines personnalisés sont utilisés, l’enregistrement DNS doit être mis à jour avec l’IP effective, après la migration. Toutefois, si les domaines par défaut sont utilisés, ils sont automatiquement mis à jour quand la migration est réussie. Il n’y a aucun temps d’arrêt pour le portail des développeurs pendant la migration.

• Y a-t-il un impact sur le coût après la migration vers stv2 ?

  Le modèle de facturation reste le même pour stv2 et aucun coût supplémentaire n’est facturé pendant et après la migration.

• Quelles sont les autorisations RBAC requises pour la migration stv1 vers stv2 ?

  L’utilisateur ou le processus qui effectue la migration a besoin d’un accès en écriture à l’instance Gestion des API.

Contenu connexe

• Comment savoir quelle plateforme héberge mon instance de Gestion des API ?

• Les avantages de la plateforme de calcul stv2 pour Gestion des API

• Mise hors service de la plateforme de calcul stv1 – Azure global (août 2024)

• Mise hors service de la plateforme stv1 – Azure Government et Azure géré par 21Vianet (février 2025)