Utiliser la fonctionnalité de migration sur place pour migrer App Service Environment v1 et v2 vers App Service Environment v3

Nous vous recommandons d’utiliser le portail Azure pour l’expérience de migration sur place. Si vous décidez d’utiliser Azure CLI pour effectuer la migration, vous devez suivre les étapes décrites ici dans l’ordre et telles qu’elles sont écrites, car vous effectuez des appels d’API REST Azure. Nous vous recommandons d’utiliser Azure CLI pour effectuer ces appels d’API. Pour obtenir des informations sur les autres méthodes, consultez Informations de référence sur l’API REST Azure.

Pour ce guide, installez Azure CLI ou utilisez Azure Cloud Shell et utilisez un interpréteur de commandes Bash.

1. Obtenir votre ID App Service Environment

Exécutez les commandes suivantes pour obtenir votre ID App Service Environment et le stocker en tant que variable d’environnement. Remplacez les espaces réservés du nom et des groupes de ressources par vos valeurs pour l’environnement App Service que vous voulez migrer. ASE_RG et VNET_RG sont les mêmes si votre réseau virtuel et App Service Environment se trouvent dans le même groupe de ressources.

ASE_NAME=<Your-App-Service-Environment-name>
ASE_RG=<Your-ASE-Resource-Group>
VNET_RG=<Your-VNet-Resource-Group>
ASE_ID=$(az appservice ase show --name $ASE_NAME --resource-group $ASE_RG --query id --output tsv)

2. Confirmer que la migration est prise en charge

La commande suivante vérifie si votre environnement App Service Environment est pris en charge pour la migration. Si vous recevez une erreur ou si votre environnement App Service Environment se trouve dans un état non sain ou suspendu, vous ne pouvez pas migrer à ce stade. Consultez la section Résolution des problèmes pour obtenir les descriptions des messages d’erreur potentiels que vous pouvez obtenir. Si votre environnement n’est pas pris en charge pour la migration en utilisant la fonctionnalité de migration sur place ou si vous voulez migrer vers App Service Environment v3 sans utiliser la fonctionnalité de migration sur place, consultez les options de migration manuelle. Cette commande valide également que votre ASE se trouve sur la version de build prise en charge pour la migration. Si votre environnement App Service n’est pas sur la version de build prise en charge, vous devez démarrer la mise à niveau vous-même, ce qui peut prendre 8 à 12 heures ou plus en fonction de la taille de votre environnement. Pour plus d’informations sur la mise à niveau de la pré-migration, consultez Valider le fait que la migration est prise en charge à l’aide de la fonctionnalité de migration en place pour votre ASE.

az rest --method post --uri "${ASE_ID}/migrate?api-version=2021-02-01&phase=validation"

S’il n’y a pas d’erreurs, votre migration est prise en charge et vous pouvez passer à l’étape suivante.

Si vous devez démarrer une mise à niveau pour mettre à niveau votre ASE vers la version de build prise en charge, exécutez la commande suivante. Exécutez cette commande uniquement si vous ne parvenez pas effectuer l’étape de validation et que vous êtes invité à mettre à niveau votre ASE.

az rest --method post --uri "${ASE_ID}/migrate?api-version=2021-02-01&phase=PreMigrationUpgrade"

3. Générer des adresses IP pour votre nouvel ressource App Service Environment v3

Exécutez la commande suivante pour créer les nouvelles adresses IP. Cette étape prend environ 15 minutes. N’effectuez pas de mise à l’échelle et n’apportez pas de modifications à votre environnement App Service Environment existant pendant cette période.

az rest --method post --uri "${ASE_ID}/migrate?api-version=2021-02-01&phase=premigration"

Exécutez la commande suivante pour vérifier l’état de cette étape :

az rest --method get --uri "${ASE_ID}?api-version=2021-02-01" --query properties.status

Si elle est en cours, vous obtenez l’état Migrating. Après avoir obtenu l’état Ready, exécutez la commande suivante pour voir vos nouvelles IP. Si les nouvelles adresses IP ne s’affichent pas immédiatement, patientez quelques minutes, puis réessayez.

az rest --method get --uri "${ASE_ID}/configurations/networking?api-version=2021-02-01"

4. Mettre à jour les ressources dépendantes avec les nouvelles adresses IP

En utilisant les nouvelles IP, mettez à jour les ressources et les composants réseau pour que votre nouvel environnement fonctionne comme prévu après la migration. Il vous incombe d’effectuer toutes les mises à jour nécessaires.

Cette étape est également un bon moment pour passer en revue les modifications des dépendances des réseaux entrantes et sortantes lors du passage à App Service Environment v3. Ces modifications incluent le changement de port pour Azure Load Balancer qui utilise désormais le port 80. Ne lancez pas la migration tant que cette étape n’est pas terminée.

5. Déléguer votre sous-réseau App Service Environment

L’environnement App Service Environment v3 exige que le sous-réseau où il se trouve dispose d’une seule délégation de Microsoft.Web/hostingEnvironments. Les versions précédentes n’exigeaient pas cette délégation. Vous devez vérifier que votre sous-réseau est délégué correctement et mettre à jour la délégation (si nécessaire) avant de procéder à la migration. Vous pouvez mettre à jour la délégation en exécutant la commande suivante ou en accédant au sous-réseau dans le portail Azure.

az network vnet subnet update --resource-group $VNET_RG --name <subnet-name> --vnet-name <vnet-name> --delegations Microsoft.Web/hostingEnvironments

6. Vérifiez qu’il n’y a pas de verrous sur le réseau virtuel

Les verrous de réseau virtuel bloquent les opérations de plateforme pendant la migration. Si votre réseau virtuel a des verrous, vous devez les supprimer avant la migration. Si nécessaire, vous pouvez rajouter les verrous une fois la migration terminée.

Les verrous peuvent exister dans trois étendues : abonnement, groupe de ressources et ressource. Lorsque vous appliquez un verrou à une étendue parente, toutes les ressources de cette étendue héritent du même verrou. Si vous avez des verrous appliqués à l’étendue de l’abonnement, de la ressource ou du groupe de ressources, vous devez les supprimer avant la migration. Pour plus d’informations sur les verrous et l’héritage des verrous, consultez Verrouiller vos ressources pour protéger votre infrastructure.

Utilisez la commande suivante pour vérifier si votre réseau virtuel dispose de verrous :

az lock list --resource-group $VNET_RG --resource <vnet-name> --resource-type Microsoft.Network/virtualNetworks

Supprimez les verrous existants à l’aide de la commande suivante :

az lock delete --resource-group $VNET_RG --name <lock-name> --resource <vnet-name> --resource-type Microsoft.Network/virtualNetworks

Pour connaître les commandes associées pour vérifier si votre abonnement ou groupe de ressources dispose de verrous, consultez la référence Azure CLI pour les verrous.

7. Préparer vos configurations

Vous pouvez rendre votre nouvelle ressource App Service Environment v3 redondante interzone si votre environnement existant se trouve dans une région qui prend en charge la redondance interzone. Vous pouvez configurer la redondance de zone en définissant la propriété zoneRedundant sur true.

La redondance interzone est une configuration facultative. Vous pouvez uniquement la définir lors de la création de votre nouvelle ressource App Service Environment v3. Vous ne pouvez pas la supprimer ultérieurement. Pour plus d’informations, consultez Choisir vos configurations App Service Environment v3. Si vous ne voulez pas configurer la redondance interzone, n’ajoutez pas le paramètre zoneRedundant.

Si votre environnement App Service Environment existant utilise un suffixe de domaine personnalisé, vous devez en configurer un pour votre nouvelle ressource App Service Environment v3 pendant le processus de migration. La migration échoue si vous ne configurez pas de suffixe de domaine personnalisé alors que vous en utilisez un actuellement. La migration échoue également si vous tentez d’ajouter un suffixe de domaine personnalisé pendant la migration vers un environnement qui n’en a pas. Pour plus d’informations sur les suffixes de domaine personnalisé App Service Environment v3, notamment les exigences, les instructions pas à pas et les bonnes pratiques, consultez Suffixe de domaine personnalisé pour les environnements App Service Environment.

Si votre migration n’a pas de suffixe de domaine personnalisé et que vous n’activez pas la redondance interzone, vous pouvez passer à la migration.

Pour définir ces configurations, créez un fichier appelé parameters.json avec les détails suivants en fonction de votre scénario. N’ajoutez pas les propriétés de suffixe de domaine personnalisé si cette fonctionnalité ne s’applique pas à votre migration. Faites attention à la valeur de la propriété zoneRedundant, car cette configuration est irréversible après la migration. Définissez la valeur de la propriété kind est définie en fonction de la version existante de votre environnement App Service. Les valeurs possibles pour la propriété kind sont ASEV1 et ASEV2.

Si vous migrez sans suffixe de domaine personnalisé et que vous activez la redondance de zone, utilisez ce code :

{
    "type": "Microsoft.Web/hostingEnvironments",
    "name": "sample-ase-migration",
    "kind": "ASEV2",
    "location": "westcentralus",
    "properties": {
        "zoneRedundant": true
    }
}

Si vous utilisez une identité managée affectée par l’utilisateur pour votre configuration de suffixe de domaine personnalisé et que vous activez la redondance de zone, utilisez ce code :

{
    "type": "Microsoft.Web/hostingEnvironments",
    "name": "sample-ase-migration",
    "kind": "ASEV2",
    "location": "westcentralus",
    "properties": {
        "zoneRedundant": true,
        "customDnsSuffixConfiguration": {
            "dnsSuffix": "internal.contoso.com",
            "certificateUrl": "https://contoso.vault.azure.net/secrets/myCertificate",
            "keyVaultReferenceIdentity": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/asev3-migration/providers/Microsoft.ManagedIdentity/userAssignedIdentities/ase-managed-identity"
        }
    }
}

Si vous utilisez une identité managée affectée par le système pour votre configuration de suffixe de domaine personnalisé et que vous n’activez pas la redondance de zone, utilisez ce code :

{
    "type": "Microsoft.Web/hostingEnvironments",
    "name": "sample-ase-migration",
    "kind": "ASEV2",
    "location": "westcentralus",
    "properties": {
        "customDnsSuffixConfiguration": {
            "dnsSuffix": "internal.contoso.com",
            "certificateUrl": "https://contoso.vault.azure.net/secrets/myCertificate",
            "keyVaultReferenceIdentity": "SystemAssigned"
        }
    }
}

8. Migrer vers App Service Environment v3 et vérifier l’état

Une fois toutes les étapes précédentes effectuées, vous pouvez démarrer la migration. Assurez-vous de bien comprendre les implications de la migration.

Cette étape prend de trois à six heures pour les migrations v2 vers v3 et jusqu’à six heures pour les migrations v1 vers v3, en fonction de la taille de l’environnement. Pendant ce temps, comptez environ une heure de temps d’arrêt de l’application. La mise à l’échelle, les déploiements et les modifications apportées à votre environnement App Service Environment existant sont bloqués pendant cette étape.

Ajoutez le paramètre body dans la commande suivante si vous activez la redondance de zone et/ou configurez un suffixe de domaine personnalisé. Si aucune de ces configurations ne s’applique à votre migration, vous pouvez supprimer le paramètre de la commande.

az rest --method post --uri "${ASE_ID}/migrate?api-version=2021-02-01&phase=fullmigration" --body @parameters.json

Exécutez les commandes suivantes pour vérifier l’état détaillé de votre migration. Pour obtenir des informations sur les états, consultez les descriptions des états de la migration.

La première commande obtient l’ID d’opération pour la migration. Copiez la valeur de la propriété ID.

az rest --method get --uri "${ASE_ID}/operations?api-version=2022-03-01"

Remplacez l’espace réservé de l’ID d’opération dans la commande suivante par la valeur copiée. Cette commande renvoie l’état détaillé de votre migration. Vous pouvez exécuter cette commande aussi souvent que nécessaire pour obtenir le dernier état.

az rest --method get --uri "${ASE_ID}/operations/<operation-id>/details/default?api-version=2022-09-01"

Une fois que vous obtenez l’état Ready, la migration est effectuée et vous avez une ressource App Service Environment v3. Vos applications s’exécutent désormais dans votre nouvel environnement.

Obtenez des informations détaillées sur votre nouvel environnement en exécutant la commande suivante ou en accédant au portail Azure.

az appservice ase show --name $ASE_NAME --resource-group $ASE_RG

1. Confirmer que la migration est prise en charge

Dans le portail Azure, accédez à la page Migration de l’environnement App Service Environment que vous migrez. Pour accéder à la page de Migration, sélectionnez la bannière en haut de la page Vue d’ensemble de votre environnement App Service Environment ou sélectionnez l’élément Migration sur le menu gauche.

Sur la page Migration, la plateforme vérifie si la migration est prise en charge pour votre environnement App Service Environment. Sélectionnez Valider, puis confirmez que vous souhaitez poursuivre la validation. Le processus de validation prend généralement quelques secondes.

Si votre environnement n’est pas pris en charge pour la migration, une bannière s’affiche en haut de la page et inclut un message d’erreur avec un motif. Pour obtenir des descriptions des messages d’erreur que vous pouvez voir si vous n’êtes pas éligible à la migration, consultez la section Résolution des problèmes.

Vous ne pouvez pas utiliser la fonctionnalité de migration si votre environnement App Service Environment n’est pas pris en charge pour la migration pour le moment ou si votre environnement affiche un état non sain ou suspendu. Si votre environnement n’est pas pris en charge pour la migration avec la fonctionnalité de migration sur place ou si vous voulez migrer vers App Service Environment v3 sans utiliser la fonctionnalité de migration sur place, consultez les options de migration manuelle.

Si vous devez démarrer une mise à niveau pour mettre à niveau votre environnement App Service vers la version de build prise en charge, vous êtes invité à démarrer la mise à niveau, ce qui peut prendre 8 à 12 heures ou plus en fonction de la taille de votre environnement. Sélectionnez Mettre à niveau pour commencer la mise à niveau. Une fois la mise à niveau terminée, vous passez la validation et vous pouvez utiliser la fonctionnalité de migration pour démarrer votre migration.

Si la migration est prise en charge pour votre App Service Environment, passez à l’étape suivante du processus. La page Migration vous guide tout au long des étapes à suivre pour réaliser la migration.

2. Générer des adresses IP pour votre nouvel ressource App Service Environment v3

Sous Obtenir de nouvelles adresses IP, confirmez que vous comprenez les implications et sélectionnez le bouton Démarrer. Cette étape prend environ 15 minutes. Vous ne pouvez pas effectuer de mise à l’échelle ou apporter des modifications à votre environnement App Service Environment existant pendant cette période.

3. Mettre à jour les ressources dépendantes avec les nouvelles adresses IP

À l’issue de l’étape précédente, les adresses IP de votre nouvel environnement App Service Environment v3 s’affichent. Avec ces nouvelles adresses IP, mettez à jour les ressources et les composants réseau pour vous assurer que votre nouvel environnement fonctionne comme prévu une fois que la migration est réalisée. Il vous incombe d’effectuer toutes les mises à jour nécessaires.

Cette étape est également un bon moment pour passer en revue les modifications des dépendances des réseaux entrantes et sortantes lors du passage à App Service Environment v3. Ces modifications incluent le changement de port pour Azure Load Balancer qui utilise désormais le port 80. Ne passez pas à l’étape suivante tant que vous n’avez pas confirmé que vous avez effectué ces mises à jour.

4. Déléguer votre sous-réseau App Service Environment

L’environnement App Service Environment v3 exige que le sous-réseau où il se trouve dispose d’une seule délégation de Microsoft.Web/hostingEnvironments. Les versions précédentes n’exigeaient pas cette délégation. Vous devez vérifier que votre sous-réseau est délégué correctement et mettre à jour la délégation (si nécessaire) avant de procéder à la migration. Le portail affiche un lien vers votre sous-réseau, afin que vous puissiez le confirmer et le mettre à jour le cas échéant.

5. Confirmez les changements de taille d’instance

Vos plans App Service sont convertis d’Isolated vers la référence niveau Isolated v2 correspondante. Par exemple, I2 est converti en I2v2. Vos applications peuvent être surprovisionnées après la migration, car le niveau Isolated v2 dispose de plus de mémoire et d’UC par taille d’instance correspondante. Vous avez la possibilité de faire évoluer votre environnement selon vos besoins après que la migration est terminée. Pour plus d’informations, consultez les détails des prix.

6. Vérifiez que le réseau virtuel n’a pas de verrous

Les verrous de réseau virtuel bloquent les opérations de plateforme pendant la migration. Si votre réseau virtuel a des verrous, vous devez les supprimer avant la migration. Si nécessaire, vous pouvez rajouter les verrous une fois la migration terminée.

Les verrous peuvent exister dans trois étendues : abonnement, groupe de ressources et ressource. Lorsque vous appliquez un verrou à une étendue parente, toutes les ressources de cette étendue héritent du même verrou. Si vous avez des verrous appliqués à l’étendue de l’abonnement, de la ressource ou du groupe de ressources, vous devez les supprimer avant la migration. Pour plus d’informations sur les verrous et l’héritage des verrous, consultez Verrouiller vos ressources pour protéger votre infrastructure.

Pour plus d’informations sur la façon de vérifier si votre abonnement ou groupe de ressources a des verrous, consultez Configurer les verrous.

7. Choisissez vos configurations

Vous pouvez rendre votre nouvelle ressource App Service Environment v3 redondante interzone si votre environnement existant se trouve dans une région qui prend en charge la redondance interzone. La redondance interzone est une configuration facultative. Vous pouvez uniquement la définir lors de la création de votre nouvelle ressource App Service Environment v3. Vous ne pouvez pas la supprimer ultérieurement. Pour plus d’informations, consultez Choisir vos configurations App Service Environment v3.

Cochez la case Activé si vous souhaitez configurer la redondance de zone.

Si votre environnement est dans une région qui ne prend pas en charge la redondance de zone, la case est décochée. Si vous avez besoin d’une ressource App Service Environment v3 redondant interzone, utilisez l’une des options de migration manuelles et créez la ressource dans l’une des régions prenant en charge la redondance de zone.

Si votre environnement App Service Environment existant utilise un suffixe de domaine personnalisé, vous devez en configurer un pour votre nouvel environnement App Service v3. Les options de configuration du suffixe de domaine personnalisé s’affichent si cette situation s’applique à votre cas. Vous ne pouvez pas lancer la migration tant que vous ne fournissez pas les informations nécessaires.

Si vous voulez utiliser un suffixe de domaine personnalisé, mais que vous n’en avez pas un actuellement configuré, vous pouvez le configurer une fois la migration terminée. Pour plus d’informations sur les suffixes de domaine personnalisé App Service Environment v3, notamment les exigences, les instructions pas à pas et les bonnes pratiques, consultez Suffixe de domaine personnalisé pour les environnements App Service Environment.

Une fois que vous avez ajouté les détails pour le suffixe de domaine personnalisé, le bouton Migrer est disponible.

8. Migrer vers App Service Environment v3

Une fois toutes les étapes précédentes effectuées, vous pouvez démarrer la migration. Veillez à bien comprendre les implications de la migration, notamment ce qui se passe pendant cette période.

Cette étape prend de trois à six heures pour les migrations v2 vers v3 et jusqu’à six heures pour les migrations v1 vers v3, en fonction de la taille de l’environnement. La mise à l’échelle et les modifications apportées à votre environnement App Service Environment existant sont bloquées au cours de cette étape.

À ce moment, les états détaillés de migration sont uniquement disponibles lors de l’utilisation de l’interface de ligne de commande Azure. Pour obtenir plus d’informations, consultez la section Azure CLI pour migrer vers App Service Environment v3. Vous pouvez vérifier l’état de la migration à l’aide de la CLI même si vous utilisez le Portail pour effectuer la migration.

Une fois la migration terminée, vous avez une ressource App Service Environment v3 et toutes vos applications s’exécutent dans votre nouvel environnement. Vous pouvez vérifier la version de l’environnement en consultant la page Configuration de votre environnement App Service Environment.

Si votre migration comprend un suffixe de domaine personnalisé, le domaine ne s’affiche plus dans App Service Environment v3, contrairement à App Service Environment v1/v2 où il s’affichait dans la section Éléments principaux de la page Vue d’ensemble du portail. Au lieu de cela, pour App Service Environment v3, accédez à la page Suffixe de domaine personnalisé pour confirmer que votre suffixe de domaine personnalisé est configuré correctement. Vous pouvez également supprimer la configuration si vous n’en avez plus besoin ou en configurer un si vous n’en avez pas.