Comment migrer le portail des développeurs d’Azure API Management vers une autre instance APIM avec Azure DevOps

Peter KARDA
Publié par Peter KARDA
Catégorie : API Management / DevOps
18/06/2022

Le portail des développeurs d’Azure API Management (APIM) est livré avec le thème par défaut. De nombreux clients choisissent de le modifier pour refléter l’image de marque de l’entreprise et présenter les API d’une manière personnalisée.

Techniquement, le portail est basé sur le framework Paperbits qui permet de redessiner le portail dans le navigateur. L’ensemble du contenu est stocké dans un fichier JSON et les images sont hébergées sur le stockage interne d’API Management.

Dans le monde réel, nous avons souvent plusieurs environnements APIM (DEV, STG, PROD, …). La migration du portail d’un environnement à un autre est donc une problématique récurrente. Dans cet article, nous allons montrer comment migrer le portail des développeurs APIM d’un environnement à un autre avec Azure DevOps.

Cet article vous montrera comment créer un pipeline Azure DevOps (YAML) et utiliser les outils APIM Developer Portal pour migrer le contenu du portail.

 

Outils de migration

Azure APIM Developer Portal est un projet open-source qui, avec les fichiers du portail, contient également les outils de migration. Il existe actuellement deux versions de ces outils (v2 et v3) mais dans cet article, nous utiliserons la dernière version qui se trouve dans le dossier “scripts.v3“. Ce répertoire contient plusieurs scripts Node.js et des fichiers batch pour la migration.

 

Processus de migration

Notez que dans le dossier vous pouvez trouver les fichiers migrate.js et migrate.bat qui permettent de migrer le portail avec une seule commande. Cela a bien fonctionné lorsque j’ai effectué la migration localement quand mon compte Azure avait suffisamment de permissions pour procéder à la migration. Cependant, dans mon environnement Azure DevOps, je ne disposais que de connexions de service pour les abonnements source et destination (cible), de sorte que la migration a dû être effectuée d’une autre manière. Au lieu d’une commande migrate, nous allons utiliser plusieurs commandes qui nous permettront de procéder à la migration étape par étape.

Les commandes que nous devrons exécuter dans l’ordre sont les suivantes :

  • capture – capture le contenu du portail Developer source
  • cleanup – nettoie le contenu du portail Developer de destination pour éviter les conflits.
  • generate – génère le contenu du portail Developer de destination (remplacement des URLs,…)

Créons un pipeline Azure DevOps avec ces commandes pour procéder à la migration.

 

Créer et configurer le pipeline Azure DevOps

Voyons maintenant comment créer le pipeline YAML. Comme mentionné, nous devons exécuter trois commandes – capture, cleanup et generate. Le pipeline doit capturer les données de l’APIM Developer Portal source, cleanup la destination (portail) et generate du contenu pour l’APIM Developer Portal de destination. Récemment, une nouvelle option (–publish true) a été ajoutée à la commande generate. Avec cette option, nous pouvons publier le portail juste après la génération du contenu.

Comme les outils de migration sont mis en œuvre dans Node.Js, la première tâche dans le pipeline sera l’installation du runtime JavaScript Node.js.

Le code source ci-dessous contient le pipeline Azure DevOps (YAML) qui exécutera toutes les tâches nécessaires à la migration du portail Azure API Management Developer d’une instance APIM à une autre. J’expliquerai toutes les variables du pipeline plus loin dans l’article.

name: APIM_DeveloperPortalMigration	 
trigger: none

variables:
  location: northeurope
  sourceServiceConnection: <source_service_connection>
  destServiceConnection: <destination_service_connection>
  sourceSubscriptionId: <source_subscription_id>
  destSubscriptionId: <destination_subscription_id>
  sourceResourceGroupName: <source_apim_instance_resource_group>
  destResourceGroupName: <destination_apim_instnace_resource_group>
  sourceServiceName: <source_apim_instance_name>
  destServiceName: <destination_apim_instance_name>

jobs:
  # All tasks on APIM Developer portal pipeline
  - job: Deploy_APIM_Developer_Portal
    displayName: Deploy APIM Developer portal from one APIM instance to another APIM instance Migration
    pool:
      vmImage: ubuntu-latest
    timeoutInMinutes: 90
    steps:
      - task: Npm@1
        displayName: Npm Install command
        inputs:
          command: "install"
          workingDir: 'portal/scripts.v3'
      - task: AzureCLI@2
        displayName: Capturing source portal
        inputs:
          azureSubscription: $(sourceServiceConnection)
          scriptType: 'pscore'
          workingDirectory: 'portal/scripts.v3'
          scriptLocation: 'inlineScript'
          inlineScript: 'node ./capture --subscriptionId $(sourceSubscriptionId) --resourceGroupName $(sourceResourceGroupName) --serviceName $(sourceServiceName)'
      - task: AzureCLI@2
        displayName: Cleaning up destination portal
        inputs:
          azureSubscription: $(destServiceConnection)
          scriptType: 'pscore'
          workingDirectory: 'portal/scripts.v3'
          scriptLocation: 'inlineScript'
          inlineScript: 'node ./cleanup --subscriptionId $(destSubscriptionId) --resourceGroupName $(destResourceGroupName) --serviceName $(destServiceName)'
      - task: AzureCLI@2
        displayName: Generating destination portal
        inputs:
          azureSubscription: $(destServiceConnection)
          scriptType: 'pscore'
          workingDirectory: 'portal/scripts.v3'
          scriptLocation: 'inlineScript'
        inlineScript: 'node ./generate --publish true --subscriptionId $(destSubscriptionId) --resourceGroupName $(destResourceGroupName) --serviceName $(destServiceName)'

 

Variables du pipeline

Pour migrer le portail des développeurs APIM de l’instance APIM source à l’instance APIM de destination, les paramètres suivants (entre crochets) doivent être spécifiés :

< source_service_connection> – connexion de service dans Azure DevOps permet d’accéder aux ressources de la souscription source.

< destination_service_connection> – connexion de service dans Azure DevOps permettant d’accéder aux ressources de la souscription de destination.

< source_subscription_id> – id d’abonnement de l’instance APIM source

< destination_subscription_id> – id d’abonnement de l’instance APIM de destination

< source_apim_instance_resource_group> – nom du groupe de ressources de l’instance APIM source.

< destination_apim_instnace_resource_group> – nom du groupe de ressources de l’instance APIM de destination.

< source_apim_instance_name> – nom de l’instance APIM source

< destination_apim_instance_name> – nom de l’instance APIM de destination

 

Préparation du répertoire DevOps

Préparons un espace de travail dans le répertoire Azure DevOps. Tout d’abord, j’ai créé un répertoire “portal” où nous mettrons tous les fichiers liés au portail et les outils de migration. J’ai cloné le dépôt GitHub du portail APIM Developer sur mon disque local, puis j’ai copié le dossier “scripts.v3“. Après j’ai créé mon pipeline YAML Azure DevOps et je l’ai poussé dans le répertoire du portail. À la fin, nous allons commiter et pousser les fichiers vers le dépôt Azure DevOps, de sorte que la structure sur le dépôt Azure DevOps ressemble à quelque chose comme ceci :

Repertoire Azure DevOps

Une fois que les fichiers sont dans le dépôt Azure DevOps, il suffit de trouver le fichier YAML pipeline dans Azure DevOps et de l’exécuter. Si tout est configuré correctement et que les connexions de service ont des autorisations suffisantes, le contenu du portail sera migré entre les instances Azure APIM.

 

Un pas de plus

Il pourrait arriver que que le portail de destination doive utiliser les différentes URL qui sont attribuées par défaut à l’instance APIM. Dans ce cas, nous pouvons ajouter une tâche supplémentaire à notre pipeline et appeler la commande updatecontenturl :

- task: AzureCLI@2 
  displayName: Updating destination urls 
  inputs: 
    azureSubscription: $(destServiceConnection) 
    scriptType: 'pscore' 
    workingDirectory: 'portal/scripts.v3' 
    scriptLocation: 'inlineScript' 
    inlineScript: 'node ./updatecontenturl --subscriptionId $(destSubscriptionId) --resourceGroupName $(destResourceGroupName) --serviceName $(destServiceName) --existingEnvUrls $(existingEnvUrls) --destEnvUrls $(destEnvUrls)'

 

Vous devrez ajouter deux nouvelles variables à la liste des variables :

existingEnvUrls – une ou plusieurs URL existantes séparées par des virgules

destEnvUrls – une ou plusieurs URL de destination séparées par des virgules

 

Si plusieurs URL sont spécifiées, le nombre et l’ordre des URL doivent correspondre à la liste des URL existantes et de destination.

 

Conclusion

La dernière version des outils a rendu la migration plus facile. Les commandes de migration sont bien documentées dans leurs fichiers sources, n’hésitez pas à les consulter.