Comment gérer la configuration de gestion d’API avec APIOps CLI

CONCERNE : Tous les niveaux de gestion des API

APIOps CLI est un outil configuration-as-code pour Gestion des API Azure. Dans cet article, vous l’utilisez pour extraire la configuration de gestion d’API en artefacts locaux, examiner les artefacts dans Git, prévisualiser les modifications et publier les artefacts approuvés dans une instance de gestion d’API. La CLI peut également échaffacer des fichiers GitHub Actions ou Azure Pipelines pour un flux de travail APIOps.

Les étapes fournissent un flux de travail minimal que vous pouvez valider avec une instance de gestion d’API non en production. Pour des conseils d’architecture et de conception, voir Déploiements automatisés d’API avec APIOps.

Utilisez ce flux de travail pour :

  • Examinez les définitions d’API, les politiques et d’autres configurations de gestion d’API via les pull requests.
  • Conservez un historique auditable des modifications de configuration approuvées.
  • Promouvoir les artefacts examinés entre environnements de gestion d’API.
  • Commencez par une configuration extraite d’une instance existante ou créez des artefacts compatibles CLI dans le code.

La ligne de commande APIOps complète les approches DevOps d’API décrites dans Use DevOps and CI/CD to publish APIs. Évaluez la CLI et votre flux de travail d’artefacts prévu dans un environnement non en production avant de l’utiliser pour des déploiements en production.

Prerequisites

  • Node.js version 22 ou ultérieure.
  • Azure CLI, pour les étapes d’authentification locale dans cet article.
  • Un abonnement Azure et une instance existante d’API Management hors production.
  • Un dépôt Git pour vos artefacts de gestion d’API.
  • Une identité avec accès à l’instance de gestion d’API. Le guide de prise en main de l’interface CLI APIOps répertorie les rôles API Management Service Contributor et Reader au niveau de la ressource API Management pour son workflow d’extraction et de publication.

Pour l’automatisation de la production, utilisez des identités séparées et à privilèges minimes lorsque cela est possible. Une identité d’extraction nécessite un accès en lecture à l’instance source. Une identité de publication n’a besoin que des autorisations nécessaires pour mettre à jour l’instance cible.

Installer APIOps CLI

Installez le package NPM @azure-tools/apiops-cli :

npm install -g @azure-tools/apiops-cli

Vérifiez la version installée :

apiops --version

Enregistrez et fixez la version que vous avez approuvée pour vos pipelines CI/CD. Consultez le journal des modifications de la ligne de commande APIOps avant de faire une mise à niveau.

S’authentifier auprès de Azure

Pour un usage local, connectez-vous avec Azure CLI et sélectionnez l’abonnement contenant votre instance de gestion d’API non-production :

az login
az account set --subscription <subscription-id>

APIOps CLI utilise DefaultAzureCredential. En plus des identifiants Azure CLI, il prend en compte les identifiants d’environnement, l’identité de la charge de travail, l’identité gérée, Azure PowerShell et les identifiants Azure Developer CLI.

Pour le CI/CD, privilégiez la fédération d’identités de charge de travail ou l’identité gérée plutôt qu’un secret de client. Ne placez jamais d’informations d’identification, de jetons d’accès, de clés d’abonnement ou de valeurs nommées secrètes dans la gestion de versions. Pour les options d’authentification prises en charge, consultez le guide d’authentification de la CLI APIOps.

Préparer un dépôt d’artefacts

Exécutez les commandes API CLI depuis la racine du dépôt Git qui contient vos artefacts de gestion d’API.

Pour échafauder les pipelines et les modèles de configuration de GitHub Actions, exécutez :

apiops init --ci github-actions --environments dev,prod --non-interactive

Pour Azure Pipelines, utilisez :

apiops init --ci azure-devops --environments dev,prod --non-interactive

La commande crée des définitions de pipeline, un modèle de filtre d’extraction, des modèles de dérogation d’environnement, des guides pour la configuration de l’identité et un apim-artifacts répertoire. Examinez chaque fichier généré avant de valider ou d’activer un pipeline. N’utilisez --force pas dans un dépôt avec des fichiers existants à moins de revoir les fichiers que la commande écrase.

Si vous avez déjà un dépôt et une conception de pipeline, vous pouvez plutôt créer ou sélectionner un répertoire d’artefacts et utiliser directement les commandes extract et publie.

Créer les artefacts initiaux

Choisissez l’une des approches suivantes pour établir les artefacts que votre dépôt possède.

Extraire la configuration existante

Pour créer une base de référence à partir d’une instance existante de gestion d’API, extrayez sa configuration :

apiops extract \
  --subscription-id <source-subscription-id> \
  --resource-group <source-resource-group> \
  --service-name <source-apim-name> \
  --output ./apim-artifacts

La commande crée des fichiers d’information JSON, des fichiers de politique XML et des fichiers de spécifications API dans une hiérarchie sous apim-artifacts. Pour une grande instance, configurez un filtre d’extraction afin que le dépôt ne gère que les ressources prévues.

Commencez par des artefacts codés d’abord

Pour un flux de travail axé sur le code, ajoutez une spécification OpenAPI ainsi que les informations et fichiers de politique de gestion d’API requis en utilisant le format d’artefact de la CLI APIOps. Ne supposez pas qu’une disposition existante de dépôt d’applications ou un fichier OpenAPI à lui seul est prêt pour apiops publish.

Si vous débutez dans le format d’artefact, extrayez d’abord une petite API de référence à partir d’une instance non-production. Utilisez les fichiers obtenus comme modèles et relisez les directives de workflow axées sur le code.

Examinez les artefacts

Avant de publier :

  1. Inspectez les fichiers générés ou créés et confirmez que le dépôt ne contient que les ressources que vous souhaitez gérer.
  2. Examinez les spécifications API, les politiques, les back-ends, les valeurs nommées, les produits et leurs dépendances.
  3. Supprimez les valeurs spécifiques à l’environnement qui ne devraient pas être transférées dans un autre environnement. Utilisez des fichiers de substitution d’environnement validés ou des références à Azure Key Vault, le cas échéant.
  4. Cherchez des références et des valeurs secrètes. L’extraction masque les champs secrets pris en charge et les modèles de stratégie reconnus, mais il se peut qu’elle ne détecte pas tous les secrets intégrés. Ne validez pas de secrets ni de valeurs *** REDACTED *** non résolues.
  5. Validez les artefacts sur une branche et utilisez une requête de tirage (pull) pour la validation et l’approbation.

Aperçu d’une publication

Effectuez une simulation sur l’instance cible de non-production. Une simulation indique les créations, mises à jour et suppressions prévues sans les appliquer :

apiops publish \
  --subscription-id <target-subscription-id> \
  --resource-group <target-resource-group> \
  --service-name <target-apim-name> \
  --source ./apim-artifacts \
  --dry-run

Examinez la sortie et résolvez les changements inattendus ou les dépendances manquantes. Un test réussi ne remplace pas les tests du comportement de l’API, des politiques, des permissions ou de la connectivité backend.

Caution

N’ajoutez --delete-unmatched pas à votre premier flux de travail. Cette option supprime les ressources dans l’instance cible qui ne sont pas représentées dans les artefacts sources.

Publiez les artefacts examinés

Après l’approbation de la pull request et le succès de l’essai à blanc, publiez les mêmes artefacts examinés dans la cible non produite :

apiops publish \
  --subscription-id <target-subscription-id> \
  --resource-group <target-resource-group> \
  --service-name <target-apim-name> \
  --source ./apim-artifacts

Validez les API et les politiques dans l’instance cible après publication. Lorsque vous automatisez ce flux de travail, configurez le pipeline pour publier un commit approuvé et protégez les environnements de déploiement avec les vérifications et approbations requises de votre organisation.

Étapes suivantes

  • Last updated on