Automatiser la configuration gestion des API à l’aide de l’interface CLI APIOps

Gestion des API Azure

Azure DevOps

Azure Pipelines

GitHub

APIOps est une méthodologie qui applique les concepts de GitOps et DevOps au déploiement d’API. Cette architecture montre comment utiliser l’interface CLI APIOps pour extraire, examiner et promouvoir Gestion des API Azure configuration via un flux de travail Basé sur Git. Utilisez cette approche pour gérer le cycle de vie des API, améliorer la qualité des API et gérer un enregistrement auditable des modifications approuvées.

Architecture

Le diagramme suivant illustre le flux de travail de promotion de la configuration CLI APIOps de haut niveau. Les équipes examinent les artefacts de gestion des API dans Git, puis les pipelines d’intégration continue et de livraison continue (CI/CD) déploient la configuration approuvée vers les environnements cibles de gestion des API.

Le diagramme comporte trois sections de gauche à droite. À gauche, l’entrée A alternative utilise un flux de travail d’extraction qui exécute « apiops extract » sur une configuration de gestion des API source existante. L’entrée alternative B utilise une création orientée code d’artefacts de gestion d’API compatibles avec l’interface CLI : fichiers d’information JSON, fichiers XML de stratégie et spécifications d’API. Les deux entrées pointent vers le référentiel Git au centre, où l’étape 1 crée une modification de configuration dans une branche, l’étape 2 examine et valide la pull request, et l’étape 3 approuve l’entrée de déploiement immuable en tant que commit approuvé. Une flèche mène de l’étape 3 au flux de travail CI/CD dans la section Déploiement contrôlé à droite. Le flux de travail CI/CD affiche un aperçu de l’entrée approuvée à l’étape 4 en exécutant « apiops publish --dry-run », publie et le promeut à l’étape 5 en exécutant « apiops publish », et valide et rapproche les environnements de gestion des API cibles à l’étape 6.

Téléchargez un fichier Visio de cette architecture.

Flux de travail

La configuration gestion des API démarre en extrayant une configuration gestion des API existante ou en créant des artefacts de gestion des API compatibles avec l’interface CLI. Le flux de travail opérationnel commence par l’une de ces entrées d’artefact. Les deux chemins mènent au même processus de pull request, de validation, d’approbation et de déploiement :

• (A) Extraire en premier : un opérateur d’API s’exécute apiops extract sur une instance API Management existante pour créer des fichiers d’artefact API Management dans leur extraction Git locale. L’opérateur utilise ces artefacts pour proposer une ligne de base ou capturer une modification de configuration approuvée.

• (B) Code-first : un développeur d’API rédige ou met à jour des spécifications d’API compatibles avec l’outil CLI APIOps, des fichiers d’information, des stratégies et les artefacts associés d’API Management dans la branche locale de son dépôt Git.

Utilisez le cycle de vie suivant pour les entrées :

1. Créez une modification de configuration. Après l’extraction initiale ou le premier archivage de l’artefact créé selon l’approche code-first, le référentiel de configuration d’API devient la source de référence pour les artefacts de configuration d’API Management. Le référentiel conserve l’historique des versions et l’enregistrement d’audit pour chaque déploiement. Pour apporter une modification, un opérateur d’API ou un développeur crée une branche à partir de la branche protégée dans le référentiel de configuration d’API et apporte une modification logique liée à l’API.

2. Passez en revue et validez la modification. L’opérateur ou le développeur ouvre une demande de tirage pour fusionner sa branche avec une branche protégée. Les propriétaires et les réviseurs requis du contrat d’API, des stratégies et de la configuration d’API Management examinent la pull request. Le système CI/CD exécute les vérifications et tests suivants :

   • Linting de spécification d’API
   • Détection des changements cassants par rapport au contrat approuvé
   • Analyse de la sécurité des spécifications et du contenu du référentiel
   • Tests d’API qui vérifient le comportement attendu, l’authentification, les effets de stratégie et les dépendances principales

   Ces vérifications ne nécessitent pas d'outils Microsoft. L’équipe utilise les outils appropriés qui répondent aux exigences de support, de sécurité et de licence de son organisation.

3. Approuver le paramètre d’entrée du déploiement immuable. Les propriétaires ou réviseurs requis approuvent la pull request, et un responsable autorisé du dépôt fusionne les modifications examinées une fois que toutes les vérifications et tous les examens requis ont été effectués. Le commit fusionné, immuable, ainsi que les artefacts de sa branche protégée, deviennent la source de référence du dépôt, pouvant faire l’objet d’un audit.

   L’équipe protège les branches de dépôt protégées contre les transmissions directes, nécessite des approbations d’environnement ou de connexion de service pour les cibles sensibles et utilise des identités à privilèges minimum distincts pour l’extraction et la publication. Ils enregistrent le commit approuvé avec sa pull request, ses revues et ses résultats de validation à des fins d’audit.

4. Affichez un aperçu du déploiement. Le pipeline CI/CD exécute apiops publish --dry-run pour le commit approuvé en utilisant la même cible et le fichier de substitution sans publication. L’approbateur de mise en production examine les ressources que l’exécution sèche crée, met à jour, supprime ou ignore. L’équipe traite une exécution sèche réussie comme une porte de déploiement, pas un substitut aux tests d’API automatisés.

5. Publier et promouvoir. Une fois que l’essai à blanc a réussi la validation, le pipeline CI/CD utilise apiops publish pour publier le même commit révisé. Pour plusieurs environnements, l’équipe plateforme maintient la stabilité des artefacts partagés et utilise des fichiers de configuration de substitution revus pour des valeurs telles que les URL de back-end, les ID de ressource et les références aux secrets. L’équipe promeut le commit via l’environnement hors production avant la production, et empêche plus d’un pipeline d’écrire sur la même cible en même temps.

   Note

   La configuration accepte les surcharges des éléments enfants de l'espace de travail, mais ne les applique pas lors de la publication. La publication applique des surcharges uniquement au conteneur de l’espace de travail lui-même. Ne vous appuyez pas sur les substitutions des ressources enfants de l’espace de travail pour déployer les API d’un espace de travail propres à un environnement, des back-ends, des valeurs nommées ou d’autres ressources enfants. Validez une autre approche de promotion pour ces ressources, ou reportez la promotion jusqu’à ce que le problème connu Propriétés de substitution à portée de l’espace de travail non appliquées soit résolu.

6. Validez et effectuez le rapprochement après le déploiement. Après la publication, l’équipe des opérations exécute des tests automatisés de fumée et de régression, surveille la gestion des API et l’intégrité du back-end et compare le résultat déployé avec la validation approuvée. L’équipe examine et résout les changements inattendus via des pull requests plutôt qu’en modifiant directement en production.

   Si un opérateur d’API effectue une modification d’urgence approuvée directement dans API Management, l’opérateur doit exécuter une extraction dans un extraction Git, vérifier et valider la modification de l’artefact sur leur branche, envoyer (push) la branche et ouvrir une demande de tirage (pull request). Les propriétaires ou réviseurs requis doivent examiner et approuver la pull request, et un mainteneur autorisé du dépôt doit la fusionner afin que le dépôt reste la source de référence.

Composants

• Gestion des API est un service managé qui crée des passerelles API cohérentes pour les services principaux. Dans cette architecture, elle fournit les configurations sources extraites par l’interface CLI APIOps et les environnements cibles dans lesquels l’interface CLI publie des définitions d’API approuvées, des stratégies, des produits, des diagnostics, des valeurs nommées et d’autres configurations prises en charge.

• APIOps CLI est un projet open source qui fournit des outils pour une approche APIOps avisée. Dans cette architecture, elle extrait la configuration gestion des API dans les fichiers d’artefacts, publie des artefacts dans Gestion des API et peut générer des flux de travail CI/CD.

• Un référentiel Git stocke les artefacts gestion des API et, le cas échéant, les contrats d’API. Il fournit l’historique des révisions et la source de référence approuvée pour les déploiements du pipeline.

• Un système CI/CD exécute la validation, l’extraction et la publication à l’aide d’une identité de charge de travail ou d’autres informations d’identification non interactives prises en charge. Dans cette architecture, GitHub Actions ou Azure Pipelines définir les flux de travail CI/CD.

Autres solutions

Vous pouvez remplacer ou augmenter cette architecture avec d'autres services ou approches Azure, en fonction des exigences fonctionnelles et non fonctionnelles de votre charge de travail. Tenez compte des alternatives et compromis suivants.

Bicep ou Terraform et APIOps peuvent servir différentes parties de la même solution. Une équipe propriétaire de la configuration et de l’infrastructure gestion des API peut utiliser l’infrastructure en tant que code (IaC) pour approvisionner le service Gestion des API et son infrastructure de prise en charge, et utiliser le même pipeline IaC pour gérer la configuration gestion des API. Choisissez cette approche lorsque l’infrastructure et la configuration changent et déploient ensemble, et quand les paramètres peuvent exprimer les différences entre les environnements.

Utilisez le modèle APIOps lorsque les définitions d’API, les stratégies et la configuration associée ont des propriétaires distincts ou un cycle de vie de mise en production indépendant de l’infrastructure de service. APIOps est également approprié lorsque vous devez extraire la configuration existante, passer en revue les artefacts axés sur l’API ou promouvoir la même configuration approuvée dans plusieurs environnements ou instances gestion des API. Les modifications d’API et de stratégie plus fréquentes ou plus d’environnements augmentent la valeur de ce flux de travail dédié.

Ces facteurs n’ont pas de seuils fixes. Basez la décision principalement sur les limites de propriété, de révision et de déploiement. Pour un patrimoine d’API plus petit avec un faible taux de modification, commencez par un flux de travail de demande de tirage manuel et ajoutez des planifications d’extraction ou une automatisation du déploiement uniquement après l’établissement de la base de référence et du processus d’approbation du référentiel.

Détails du scénario

APIOps utilise le contrôle de version pour gérer les API et créer une piste d’audit des modifications apportées aux définitions d’API, aux stratégies, aux produits, aux diagnostics et à d’autres configurations gestion des API. L’examen des modifications antérieures et plus souvent aide les équipes à identifier les écarts par rapport aux normes d’API avant le déploiement. À mesure que d’autres API utilisent le même processus, les équipes peuvent améliorer la cohérence dans leur patrimoine d’API.

Ce flux de travail déploie la configuration gestion des API sur une instance Gestion des API. Il ne déploie pas de back-ends d’API, de calcul d’application ou de ressources de données, de mise en réseau ou de l’infrastructure de service Gestion des API. Utilisez des pipelines IaC et d’application régis distincts pour déployer ces couches.

Cette solution aide les équipes :

• Gérez une vue d’ensemble des environnements et des instances gestion des API.
• Suivez les modifications critiques apportées aux API et aux stratégies.
• Créez une piste d’audit pour les déploiements approuvés.
• Rapprocher les modifications approuvées qui proviennent de l’extérieur du référentiel.

Choisir les sources d’artefact et la propriété

Choisissez parmi les méthodes suivantes que les artefacts entrent dans le référentiel et qui les possède avant d’automatiser le déploiement :

• Extraire d’abord : Extrayez une instance API Management dont le bon fonctionnement est avéré afin d’établir la référence initiale des artefacts. Passez en revue les artefacts générés enregistrés dans le dépôt avant de considérer le référentiel comme la source de référence.
• Code-first : Conservez le contrat d’API, tel qu’une description OpenAPI, avec la source de l’application ou le référentiel APIOps. Définissez qui transforme ce contrat en artefacts d’API Management que le pipeline publie. Validez le flux de travail d’importation et d’artefact prévu avec une instance gestion des API hors production. Ne supposez pas qu’une disposition source arbitraire est directement consommable par l’interface CLI.
• Responsabilité partagée : Déterminez si les développeurs d’API, les exploitants de la plateforme ou les deux sont responsables des modifications apportées aux stratégies, aux produits, aux diagnostics, aux valeurs nommées et aux définitions d’API. Une fois la ligne de base acceptée, routez chaque modification via le même dépôt et le même processus de révision.

Cas d’usage potentiels

• Organisations qui développent et gèrent des API, y compris les organisations avec une SEULE API exposée via Gestion des API.

• Des secteurs hautement réglementés tels que l’assurance, les banques, les finances et le gouvernement qui ont besoin d’un examen et d’un dossier de déploiement pouvant être suivis.

Considérations

Ces considérations implémentent les piliers de l’infrastructure Azure Well-Architected, qui est un ensemble de tenets guidants que vous pouvez utiliser pour améliorer la qualité d’une charge de travail. Pour plus d’informations, consultez Well-Architected Framework.

Reliability

La fiabilité permet de s’assurer que votre application peut respecter les engagements que vous prenez à vos clients. Pour plus d'informations, veuillez consulter la liste de vérification de la conception pour la fiabilité.

Pour les modifications non destructives de l’API, utilisez les révisions d’API Management pour déployer et tester une révision qui n’est pas active avant d’en faire la version active. Si la validation échoue après le déploiement, rétablissez la révision précédente comme version actuelle. Utilisez des versions d’API pour rompre les modifications de contrat afin que les consommateurs existants puissent continuer à utiliser la version antérieure.

Coordonner les modifications de configuration de gestion des API avec la stratégie de déploiement pour chaque serveur principal d’API. La restauration d’une validation APIOps restaure uniquement la configuration représentée par cette validation. Il ne restaure pas un serveur principal incompatible ou indisponible. Enregistrez le commit APIOps, la révision d’API Management et la version du back-end correspondant à chaque déploiement validé. Testez la procédure complète de retour arrière dans un environnement hors production, notamment les stratégies, les valeurs nommées, les références de secrets, les dépendances et la compatibilité avec le back-end.

Sécurité

La sécurité offre des garanties contre les attaques délibérées et l’utilisation abusive de données et de systèmes précieux. Pour plus d’informations, consultez la liste de vérification de la révision de conception pour la sécurité.

Utilisez le référentiel et le pipeline comme chemin normal d’application des modifications de gestion des API. Les développeurs et les opérateurs n’ont pas besoin d’un accès en écriture persistant aux instances gestion des API de production. Accordez un accès avec élévation de privilèges uniquement si nécessaire, et seulement pendant une durée limitée. Répercutez toute modification qui en résulte dans le dépôt.

Utilisez les mécanismes suivants pour protéger le référentiel Git qui stocke les artefacts gestion des API :

• Révision des demandes de tirage : Protégez les branches qui déploient la configuration et nécessitent une révision par les réviseurs appropriés.
• Isolation des informations d’identification : Privilégiez l’identité de charge de travail fédérée si elle est disponible. Stockez des secrets spécifiques à l’environnement dans un environnement de magasin de secrets ou de référentiel approuvé, et non dans des artefacts ou des fichiers de pipeline.
• Intégrité de la validation : Exiger des validations signées pour vérifier la provenance de la validation. Configurez les protections de branche afin d’empêcher les push forcés et la suppression de branches, exigez l’authentification multifacteur pour que les utilisateurs puissent approuver ou fusionner les modifications, et préservez l’historique des commits et des pull requests pour les déploiements.
• Examen des artefacts : Vérifiez la sortie d’extraction et les entrées de publication afin d’y repérer des secrets, des marqueurs de masquage et des valeurs spécifiques à l’environnement non intentionnelles. Vérifiez qu’une modification n’étend pas l’accès aux API ni affaiblit une stratégie.

Gérez l’interface CLI APIOps en tant que dépendance de référentiel. Fixez @azure-tools/apiops-cli dans package.json à une version éprouvée, validez le fichier de verrouillage et utilisez npm ci. Passez en revue les paramètres d’identité générés, les variables, les déclencheurs et les règles de protection avant d’activer un pipeline de production.

Optimisation des coûts

L’optimisation des coûts se concentre sur les moyens de réduire les dépenses inutiles et d’améliorer l’efficacité opérationnelle. Pour plus d’informations, consultez la liste de contrôle de révision de conception pour l’optimisation des coûts.

L’interface CLI APIOps est un logiciel open source, mais ce scénario entraîne des coûts pour les instances gestion des API et la plateforme CI/CD sélectionnée. Une estimation fixe unique n’est pas fournie, car les prix de gestion des API varient selon la région, le niveau, le nombre d’unités, le modèle de capacité, la zone de disponibilité ou la configuration multirégion et l’utilisation. Les frais CI/CD dépendent également du type d’exécuteur, des minutes incluses, de la concurrence, du stockage et de la rétention.

Créez une estimation spécifique au scénario dans la calculatrice de prix Azure et enregistrez les hypothèses suivantes avec la décision d’architecture :

Estimer l’entrée	Hypothèse à enregistrer
Région Gestion des API	Région de déploiement pour chaque instance de développement, de test, de préproduction et de production.
Niveau et capacité	Niveau ou niveau v2, nombre d’unités ou de passerelles et heures d’exploitation pour chaque environnement.
Resiliency	Tout déploiement de zone de disponibilité ou de région supplémentaire, y compris les unités de chaque emplacement.
Frais basés sur l’utilisation	Demandes ou opérations attendues et tout espace de travail applicable, passerelle auto-hébergée, mise en réseau, surveillance ou frais de transfert de données.
Plateforme CI/CD	agents hébergés par GitHub, auto-hébergés ou Azure Pipelines. Exécutions de pipeline attendues, durée, concurrence, stockage et rétention des journaux ou des artefacts.
Contrôle de code source et licences	Nombre d’utilisateurs et toutes les fonctionnalités de plan de GitHub ou de Azure DevOps payantes.

Utilisez les détails actuels de la tarification gestion des API pour sélectionner le modèle de facturation applicable. Pour connaître les hypothèses ci/CD et contrôle de code source, consultez Azure DevOps tarification et GitHub tarification. Exportez ou capturez l’estimation de la calculatrice, sa devise, la date de tarification et toutes les hypothèses afin que les réviseurs puissent le reproduire et le mettre à jour. Recalculez avant le déploiement et lorsque les régions, niveaux, nombres d’unités, environnements ou modifications d’utilisation du pipeline changent.

Excellence opérationnelle

L’excellence opérationnelle couvre les processus opérationnels qui déploient une application et la maintiennent en production. Pour plus d’informations, consultez la liste de vérification de la révision de conception pour l’excellence opérationnelle.

APIOps rend les déploiements reproductibles et crée un historique de validation pour l’analyse post-modification. Balisez ou enregistrez la validation que chaque environnement reçoit, conservez les journaux de pipeline et surveillez l’instance gestion des API et les API dépendantes après le déploiement.

Dans plusieurs environnements, faites progresser le même commit d’artefact validé à travers le développement, la préproduction et la production. Utilisez les surcharges d’environnement uniquement pour les valeurs qui doivent différer d’un environnement à l’autre, et examinez ces fichiers avec la même attention que les artefacts. Les remplacements enfants de l’espace de travail ne sont pas appliqués au moment de la publication. Par conséquent, ne les utilisez pas pour la promotion de l’environnement. Testez les procédures de retour arrière avant qu’un incident ne se produise. Un rétablissement Git nécessite toujours une validation et une publication contrôlée pour restaurer la gestion des API.

La CLI propose les commandes init, extract et publish et peut générer le squelette de pipelines GitHub Actions ou Azure DevOps. Passez en revue les détails de la commande dans la documentation DE l’interface CLI APIOps.

Migrer en toute sécurité à partir du kit de ressources APIOps hérité

Si votre processus APIOps utilise le kit de ressources APIOps hérité, envisagez de procéder à la mise à niveau. Cette approche utilise des exécutables distincts pour Extractor et Publisher, ainsi que des modèles de pipeline. L’interface CLI APIOps utilise une seule interface CLI Node.js, mais son format d’artefact est conçu pour être compatible avec les artefacts de kit de ressources existants. Traitez la migration comme un basculement contrôlé, et non comme une mise à niveau de production sur place.

1. Marquez les artefacts et le pipeline de la boîte à outils validés, et conservez l’éditeur existant comme option de restauration. Ne modifiez pas l’éditeur hérité et introduisez le nouvel éditeur dans le même déploiement.

2. Dans une branche de migration, utilisez la dernière version de l’interface CLI APIOps et exécutez apiops init sans utiliser --force. La commande détecte les fichiers en conflit et les quitte plutôt que de les remplacer. Comparez et intégrez délibérément les pipelines générés, les directives relatives à l’identité, les filtres et les fichiers de substitution.

3. Utilisez les artefacts avec apiops publish --dry-run et les remplacements de l’environnement cible par rapport à une instance API Management hors production. Passez en revue les ressources que l’interface CLI créerait, mettre à jour ou supprimer. Testez une publication contrôlée et validez les API, stratégies, valeurs nommées et dépendances déployées.

4. N’utilisez pas les remplacements enfants de l’espace de travail, qui ne sont pas appliqués au moment de la publication, dans la conception de la migration ou de la promotion. Validez une approche alternative de promotion pour les ressources enfant concernées, ou reportez leur migration jusqu’à la résolution du problème connu Les propriétés de remplacement limitées à l’espace de travail ne sont pas appliquées.

5. Lors du basculement, autorisez un seul éditeur à écrire dans une instance d’API Management. Désactivez le déclencheur d’éditeur hérité avant d’activer l’éditeur CLI. Déployez un commit validé et surveillez le résultat. Conservez le pipeline de kit de ressources étiqueté et la ligne de base des artefacts jusqu’à ce que le nouveau workflow termine un cycle de mise en production réussi.

Pour plus d’informations sur la compatibilité et des exemples de migration de commande par commande, consultez Migration à partir d’APIOps Toolkit.

Déployer ce scénario

Suivez la documentation de l’outil de ligne de commande APIOps dans le dépôt GitHub d’APIOps CLI. Commencez par une instance gestion des API hors production et utilisez les instructions de publication actuelles de l’interface CLI APIOps. Pour commencer à utiliser un environnement hors production, consultez Comment gérer la configuration gestion des API avec l’interface CLI APIOps.

Contributeurs

Microsoft conserve cet article. Les contributeurs suivants ont écrit cet article.

Auteurs principaux :

• Pat Altimore | Développeur de contenu senior
• Wael Kdouh | Architecte de solution principal senior
• Rishabh Saha | Architecte de solution principal senior

Pour afficher les profils LinkedIn non publics, connectez-vous à LinkedIn.

Étapes suivantes

• APIOps CLI
• Comment gérer la configuration gestion des API avec l’interface CLI APIOps
• Vue d’ensemble de GitOps

Ressources associées

• GitOps pour Azure Kubernetes Service (AKS)
• Migrer une application web à l’aide de Gestion des API
• Protéger les API à l’aide d’Azure Application Gateway et gestion des API

APIOps est une méthodologie qui applique les concepts de GitOps et DevOps au déploiement d’API. Cette architecture montre comment utiliser l’interface CLI APIOps pour extraire, examiner et promouvoir Gestion des API Azure configuration via un flux de travail Basé sur Git. Utilisez cette approche pour gérer le cycle de vie des API, améliorer la qualité des API et gérer un enregistrement auditable des modifications approuvées.

Architecture

Le diagramme suivant illustre le flux de travail de promotion de la configuration CLI APIOps de haut niveau. Les équipes examinent les artefacts de gestion des API dans Git, puis les pipelines d’intégration continue et de livraison continue (CI/CD) déploient la configuration approuvée vers les environnements cibles de gestion des API.

Le diagramme comporte trois sections de gauche à droite. À gauche, l’entrée A alternative utilise un flux de travail d’extraction qui exécute « apiops extract » sur une configuration de gestion des API source existante. L’entrée alternative B utilise une création orientée code d’artefacts de gestion d’API compatibles avec l’interface CLI : fichiers d’information JSON, fichiers XML de stratégie et spécifications d’API. Les deux entrées pointent vers le référentiel Git au centre, où l’étape 1 crée une modification de configuration dans une branche, l’étape 2 examine et valide la pull request, et l’étape 3 approuve l’entrée de déploiement immuable en tant que commit approuvé. Une flèche mène de l’étape 3 au flux de travail CI/CD dans la section Déploiement contrôlé à droite. Le flux de travail CI/CD affiche un aperçu de l’entrée approuvée à l’étape 4 en exécutant « apiops publish --dry-run », publie et le promeut à l’étape 5 en exécutant « apiops publish », et valide et rapproche les environnements de gestion des API cibles à l’étape 6.

Téléchargez un fichier Visio de cette architecture.

Flux de travail

La configuration gestion des API démarre en extrayant une configuration gestion des API existante ou en créant des artefacts de gestion des API compatibles avec l’interface CLI. Le flux de travail opérationnel commence par l’une de ces entrées d’artefact. Les deux chemins mènent au même processus de pull request, de validation, d’approbation et de déploiement :

• (A) Extraire en premier : un opérateur d’API s’exécute apiops extract sur une instance API Management existante pour créer des fichiers d’artefact API Management dans leur extraction Git locale. L’opérateur utilise ces artefacts pour proposer une ligne de base ou capturer une modification de configuration approuvée.

• (B) Code-first : un développeur d’API rédige ou met à jour des spécifications d’API compatibles avec l’outil CLI APIOps, des fichiers d’information, des stratégies et les artefacts associés d’API Management dans la branche locale de son dépôt Git.

Utilisez le cycle de vie suivant pour les entrées :

1. Créez une modification de configuration. Après l’extraction initiale ou le premier archivage de l’artefact créé selon l’approche code-first, le référentiel de configuration d’API devient la source de référence pour les artefacts de configuration d’API Management. Le référentiel conserve l’historique des versions et l’enregistrement d’audit pour chaque déploiement. Pour apporter une modification, un opérateur d’API ou un développeur crée une branche à partir de la branche protégée dans le référentiel de configuration d’API et apporte une modification logique liée à l’API.

2. Passez en revue et validez la modification. L’opérateur ou le développeur ouvre une demande de tirage pour fusionner sa branche avec une branche protégée. Les propriétaires et les réviseurs requis du contrat d’API, des stratégies et de la configuration d’API Management examinent la pull request. Le système CI/CD exécute les vérifications et tests suivants :

   • Linting de spécification d’API
   • Détection des changements cassants par rapport au contrat approuvé
   • Analyse de la sécurité des spécifications et du contenu du référentiel
   • Tests d’API qui vérifient le comportement attendu, l’authentification, les effets de stratégie et les dépendances principales

   Ces vérifications ne nécessitent pas d'outils Microsoft. L’équipe utilise les outils appropriés qui répondent aux exigences de support, de sécurité et de licence de son organisation.

3. Approuver le paramètre d’entrée du déploiement immuable. Les propriétaires ou réviseurs requis approuvent la pull request, et un responsable autorisé du dépôt fusionne les modifications examinées une fois que toutes les vérifications et tous les examens requis ont été effectués. Le commit fusionné, immuable, ainsi que les artefacts de sa branche protégée, deviennent la source de référence du dépôt, pouvant faire l’objet d’un audit.

   L’équipe protège les branches de dépôt protégées contre les transmissions directes, nécessite des approbations d’environnement ou de connexion de service pour les cibles sensibles et utilise des identités à privilèges minimum distincts pour l’extraction et la publication. Ils enregistrent le commit approuvé avec sa pull request, ses revues et ses résultats de validation à des fins d’audit.

4. Affichez un aperçu du déploiement. Le pipeline CI/CD exécute apiops publish --dry-run pour le commit approuvé en utilisant la même cible et le fichier de substitution sans publication. L’approbateur de mise en production examine les ressources que l’exécution sèche crée, met à jour, supprime ou ignore. L’équipe traite une exécution sèche réussie comme une porte de déploiement, pas un substitut aux tests d’API automatisés.

5. Publier et promouvoir. Une fois que l’essai à blanc a réussi la validation, le pipeline CI/CD utilise apiops publish pour publier le même commit révisé. Pour plusieurs environnements, l’équipe plateforme maintient la stabilité des artefacts partagés et utilise des fichiers de configuration de substitution revus pour des valeurs telles que les URL de back-end, les ID de ressource et les références aux secrets. L’équipe promeut le commit via l’environnement hors production avant la production, et empêche plus d’un pipeline d’écrire sur la même cible en même temps.

   Note

   La configuration accepte les surcharges des éléments enfants de l'espace de travail, mais ne les applique pas lors de la publication. La publication applique des surcharges uniquement au conteneur de l’espace de travail lui-même. Ne vous appuyez pas sur les substitutions des ressources enfants de l’espace de travail pour déployer les API d’un espace de travail propres à un environnement, des back-ends, des valeurs nommées ou d’autres ressources enfants. Validez une autre approche de promotion pour ces ressources, ou reportez la promotion jusqu’à ce que le problème connu Propriétés de substitution à portée de l’espace de travail non appliquées soit résolu.

6. Validez et effectuez le rapprochement après le déploiement. Après la publication, l’équipe des opérations exécute des tests automatisés de fumée et de régression, surveille la gestion des API et l’intégrité du back-end et compare le résultat déployé avec la validation approuvée. L’équipe examine et résout les changements inattendus via des pull requests plutôt qu’en modifiant directement en production.

   Si un opérateur d’API effectue une modification d’urgence approuvée directement dans API Management, l’opérateur doit exécuter une extraction dans un extraction Git, vérifier et valider la modification de l’artefact sur leur branche, envoyer (push) la branche et ouvrir une demande de tirage (pull request). Les propriétaires ou réviseurs requis doivent examiner et approuver la pull request, et un mainteneur autorisé du dépôt doit la fusionner afin que le dépôt reste la source de référence.

Composants

• Gestion des API est un service managé qui crée des passerelles API cohérentes pour les services principaux. Dans cette architecture, elle fournit les configurations sources extraites par l’interface CLI APIOps et les environnements cibles dans lesquels l’interface CLI publie des définitions d’API approuvées, des stratégies, des produits, des diagnostics, des valeurs nommées et d’autres configurations prises en charge.

• APIOps CLI est un projet open source qui fournit des outils pour une approche APIOps avisée. Dans cette architecture, elle extrait la configuration gestion des API dans les fichiers d’artefacts, publie des artefacts dans Gestion des API et peut générer des flux de travail CI/CD.

• Un référentiel Git stocke les artefacts gestion des API et, le cas échéant, les contrats d’API. Il fournit l’historique des révisions et la source de référence approuvée pour les déploiements du pipeline.

• Un système CI/CD exécute la validation, l’extraction et la publication à l’aide d’une identité de charge de travail ou d’autres informations d’identification non interactives prises en charge. Dans cette architecture, GitHub Actions ou Azure Pipelines définir les flux de travail CI/CD.

Autres solutions

Vous pouvez remplacer ou augmenter cette architecture avec d'autres services ou approches Azure, en fonction des exigences fonctionnelles et non fonctionnelles de votre charge de travail. Tenez compte des alternatives et compromis suivants.

Bicep ou Terraform et APIOps peuvent servir différentes parties de la même solution. Une équipe propriétaire de la configuration et de l’infrastructure gestion des API peut utiliser l’infrastructure en tant que code (IaC) pour approvisionner le service Gestion des API et son infrastructure de prise en charge, et utiliser le même pipeline IaC pour gérer la configuration gestion des API. Choisissez cette approche lorsque l’infrastructure et la configuration changent et déploient ensemble, et quand les paramètres peuvent exprimer les différences entre les environnements.

Utilisez le modèle APIOps lorsque les définitions d’API, les stratégies et la configuration associée ont des propriétaires distincts ou un cycle de vie de mise en production indépendant de l’infrastructure de service. APIOps est également approprié lorsque vous devez extraire la configuration existante, passer en revue les artefacts axés sur l’API ou promouvoir la même configuration approuvée dans plusieurs environnements ou instances gestion des API. Les modifications d’API et de stratégie plus fréquentes ou plus d’environnements augmentent la valeur de ce flux de travail dédié.

Ces facteurs n’ont pas de seuils fixes. Basez la décision principalement sur les limites de propriété, de révision et de déploiement. Pour un patrimoine d’API plus petit avec un faible taux de modification, commencez par un flux de travail de demande de tirage manuel et ajoutez des planifications d’extraction ou une automatisation du déploiement uniquement après l’établissement de la base de référence et du processus d’approbation du référentiel.

Détails du scénario

APIOps utilise le contrôle de version pour gérer les API et créer une piste d’audit des modifications apportées aux définitions d’API, aux stratégies, aux produits, aux diagnostics et à d’autres configurations gestion des API. L’examen des modifications antérieures et plus souvent aide les équipes à identifier les écarts par rapport aux normes d’API avant le déploiement. À mesure que d’autres API utilisent le même processus, les équipes peuvent améliorer la cohérence dans leur patrimoine d’API.

Ce flux de travail déploie la configuration gestion des API sur une instance Gestion des API. Il ne déploie pas de back-ends d’API, de calcul d’application ou de ressources de données, de mise en réseau ou de l’infrastructure de service Gestion des API. Utilisez des pipelines IaC et d’application régis distincts pour déployer ces couches.

Cette solution aide les équipes :

• Gérez une vue d’ensemble des environnements et des instances gestion des API.
• Suivez les modifications critiques apportées aux API et aux stratégies.
• Créez une piste d’audit pour les déploiements approuvés.
• Rapprocher les modifications approuvées qui proviennent de l’extérieur du référentiel.

Choisir les sources d’artefact et la propriété

Choisissez parmi les méthodes suivantes que les artefacts entrent dans le référentiel et qui les possède avant d’automatiser le déploiement :

• Extraire d’abord : Extrayez une instance API Management dont le bon fonctionnement est avéré afin d’établir la référence initiale des artefacts. Passez en revue les artefacts générés enregistrés dans le dépôt avant de considérer le référentiel comme la source de référence.
• Code-first : Conservez le contrat d’API, tel qu’une description OpenAPI, avec la source de l’application ou le référentiel APIOps. Définissez qui transforme ce contrat en artefacts d’API Management que le pipeline publie. Validez le flux de travail d’importation et d’artefact prévu avec une instance gestion des API hors production. Ne supposez pas qu’une disposition source arbitraire est directement consommable par l’interface CLI.
• Responsabilité partagée : Déterminez si les développeurs d’API, les exploitants de la plateforme ou les deux sont responsables des modifications apportées aux stratégies, aux produits, aux diagnostics, aux valeurs nommées et aux définitions d’API. Une fois la ligne de base acceptée, routez chaque modification via le même dépôt et le même processus de révision.

Cas d’usage potentiels

• Organisations qui développent et gèrent des API, y compris les organisations avec une SEULE API exposée via Gestion des API.

• Des secteurs hautement réglementés tels que l’assurance, les banques, les finances et le gouvernement qui ont besoin d’un examen et d’un dossier de déploiement pouvant être suivis.

Considérations

Ces considérations implémentent les piliers de l’infrastructure Azure Well-Architected, qui est un ensemble de tenets guidants que vous pouvez utiliser pour améliorer la qualité d’une charge de travail. Pour plus d’informations, consultez Well-Architected Framework.

Reliability

La fiabilité permet de s’assurer que votre application peut respecter les engagements que vous prenez à vos clients. Pour plus d'informations, veuillez consulter la liste de vérification de la conception pour la fiabilité.

Pour les modifications non destructives de l’API, utilisez les révisions d’API Management pour déployer et tester une révision qui n’est pas active avant d’en faire la version active. Si la validation échoue après le déploiement, rétablissez la révision précédente comme version actuelle. Utilisez des versions d’API pour rompre les modifications de contrat afin que les consommateurs existants puissent continuer à utiliser la version antérieure.

Coordonner les modifications de configuration de gestion des API avec la stratégie de déploiement pour chaque serveur principal d’API. La restauration d’une validation APIOps restaure uniquement la configuration représentée par cette validation. Il ne restaure pas un serveur principal incompatible ou indisponible. Enregistrez le commit APIOps, la révision d’API Management et la version du back-end correspondant à chaque déploiement validé. Testez la procédure complète de retour arrière dans un environnement hors production, notamment les stratégies, les valeurs nommées, les références de secrets, les dépendances et la compatibilité avec le back-end.

Sécurité

La sécurité offre des garanties contre les attaques délibérées et l’utilisation abusive de données et de systèmes précieux. Pour plus d’informations, consultez la liste de vérification de la révision de conception pour la sécurité.

Utilisez le référentiel et le pipeline comme chemin normal d’application des modifications de gestion des API. Les développeurs et les opérateurs n’ont pas besoin d’un accès en écriture persistant aux instances gestion des API de production. Accordez un accès avec élévation de privilèges uniquement si nécessaire, et seulement pendant une durée limitée. Répercutez toute modification qui en résulte dans le dépôt.

Utilisez les mécanismes suivants pour protéger le référentiel Git qui stocke les artefacts gestion des API :

• Révision des demandes de tirage : Protégez les branches qui déploient la configuration et nécessitent une révision par les réviseurs appropriés.
• Isolation des informations d’identification : Privilégiez l’identité de charge de travail fédérée si elle est disponible. Stockez des secrets spécifiques à l’environnement dans un environnement de magasin de secrets ou de référentiel approuvé, et non dans des artefacts ou des fichiers de pipeline.
• Intégrité de la validation : Exiger des validations signées pour vérifier la provenance de la validation. Configurez les protections de branche afin d’empêcher les push forcés et la suppression de branches, exigez l’authentification multifacteur pour que les utilisateurs puissent approuver ou fusionner les modifications, et préservez l’historique des commits et des pull requests pour les déploiements.
• Examen des artefacts : Vérifiez la sortie d’extraction et les entrées de publication afin d’y repérer des secrets, des marqueurs de masquage et des valeurs spécifiques à l’environnement non intentionnelles. Vérifiez qu’une modification n’étend pas l’accès aux API ni affaiblit une stratégie.

Gérez l’interface CLI APIOps en tant que dépendance de référentiel. Fixez @azure-tools/apiops-cli dans package.json à une version éprouvée, validez le fichier de verrouillage et utilisez npm ci. Passez en revue les paramètres d’identité générés, les variables, les déclencheurs et les règles de protection avant d’activer un pipeline de production.

Optimisation des coûts

L’optimisation des coûts se concentre sur les moyens de réduire les dépenses inutiles et d’améliorer l’efficacité opérationnelle. Pour plus d’informations, consultez la liste de contrôle de révision de conception pour l’optimisation des coûts.

L’interface CLI APIOps est un logiciel open source, mais ce scénario entraîne des coûts pour les instances gestion des API et la plateforme CI/CD sélectionnée. Une estimation fixe unique n’est pas fournie, car les prix de gestion des API varient selon la région, le niveau, le nombre d’unités, le modèle de capacité, la zone de disponibilité ou la configuration multirégion et l’utilisation. Les frais CI/CD dépendent également du type d’exécuteur, des minutes incluses, de la concurrence, du stockage et de la rétention.

Créez une estimation spécifique au scénario dans la calculatrice de prix Azure et enregistrez les hypothèses suivantes avec la décision d’architecture :

Estimer l’entrée	Hypothèse à enregistrer
Région Gestion des API	Région de déploiement pour chaque instance de développement, de test, de préproduction et de production.
Niveau et capacité	Niveau ou niveau v2, nombre d’unités ou de passerelles et heures d’exploitation pour chaque environnement.
Resiliency	Tout déploiement de zone de disponibilité ou de région supplémentaire, y compris les unités de chaque emplacement.
Frais basés sur l’utilisation	Demandes ou opérations attendues et tout espace de travail applicable, passerelle auto-hébergée, mise en réseau, surveillance ou frais de transfert de données.
Plateforme CI/CD	agents hébergés par GitHub, auto-hébergés ou Azure Pipelines. Exécutions de pipeline attendues, durée, concurrence, stockage et rétention des journaux ou des artefacts.
Contrôle de code source et licences	Nombre d’utilisateurs et toutes les fonctionnalités de plan de GitHub ou de Azure DevOps payantes.

Utilisez les détails actuels de la tarification gestion des API pour sélectionner le modèle de facturation applicable. Pour connaître les hypothèses ci/CD et contrôle de code source, consultez Azure DevOps tarification et GitHub tarification. Exportez ou capturez l’estimation de la calculatrice, sa devise, la date de tarification et toutes les hypothèses afin que les réviseurs puissent le reproduire et le mettre à jour. Recalculez avant le déploiement et lorsque les régions, niveaux, nombres d’unités, environnements ou modifications d’utilisation du pipeline changent.

Excellence opérationnelle

L’excellence opérationnelle couvre les processus opérationnels qui déploient une application et la maintiennent en production. Pour plus d’informations, consultez la liste de vérification de la révision de conception pour l’excellence opérationnelle.

APIOps rend les déploiements reproductibles et crée un historique de validation pour l’analyse post-modification. Balisez ou enregistrez la validation que chaque environnement reçoit, conservez les journaux de pipeline et surveillez l’instance gestion des API et les API dépendantes après le déploiement.

Dans plusieurs environnements, faites progresser le même commit d’artefact validé à travers le développement, la préproduction et la production. Utilisez les surcharges d’environnement uniquement pour les valeurs qui doivent différer d’un environnement à l’autre, et examinez ces fichiers avec la même attention que les artefacts. Les remplacements enfants de l’espace de travail ne sont pas appliqués au moment de la publication. Par conséquent, ne les utilisez pas pour la promotion de l’environnement. Testez les procédures de retour arrière avant qu’un incident ne se produise. Un rétablissement Git nécessite toujours une validation et une publication contrôlée pour restaurer la gestion des API.

La CLI propose les commandes init, extract et publish et peut générer le squelette de pipelines GitHub Actions ou Azure DevOps. Passez en revue les détails de la commande dans la documentation DE l’interface CLI APIOps.

Migrer en toute sécurité à partir du kit de ressources APIOps hérité

Si votre processus APIOps utilise le kit de ressources APIOps hérité, envisagez de procéder à la mise à niveau. Cette approche utilise des exécutables distincts pour Extractor et Publisher, ainsi que des modèles de pipeline. L’interface CLI APIOps utilise une seule interface CLI Node.js, mais son format d’artefact est conçu pour être compatible avec les artefacts de kit de ressources existants. Traitez la migration comme un basculement contrôlé, et non comme une mise à niveau de production sur place.

1. Marquez les artefacts et le pipeline de la boîte à outils validés, et conservez l’éditeur existant comme option de restauration. Ne modifiez pas l’éditeur hérité et introduisez le nouvel éditeur dans le même déploiement.

2. Dans une branche de migration, utilisez la dernière version de l’interface CLI APIOps et exécutez apiops init sans utiliser --force. La commande détecte les fichiers en conflit et les quitte plutôt que de les remplacer. Comparez et intégrez délibérément les pipelines générés, les directives relatives à l’identité, les filtres et les fichiers de substitution.

3. Utilisez les artefacts avec apiops publish --dry-run et les remplacements de l’environnement cible par rapport à une instance API Management hors production. Passez en revue les ressources que l’interface CLI créerait, mettre à jour ou supprimer. Testez une publication contrôlée et validez les API, stratégies, valeurs nommées et dépendances déployées.

4. N’utilisez pas les remplacements enfants de l’espace de travail, qui ne sont pas appliqués au moment de la publication, dans la conception de la migration ou de la promotion. Validez une approche alternative de promotion pour les ressources enfant concernées, ou reportez leur migration jusqu’à la résolution du problème connu Les propriétés de remplacement limitées à l’espace de travail ne sont pas appliquées.

5. Lors du basculement, autorisez un seul éditeur à écrire dans une instance d’API Management. Désactivez le déclencheur d’éditeur hérité avant d’activer l’éditeur CLI. Déployez un commit validé et surveillez le résultat. Conservez le pipeline de kit de ressources étiqueté et la ligne de base des artefacts jusqu’à ce que le nouveau workflow termine un cycle de mise en production réussi.

Pour plus d’informations sur la compatibilité et des exemples de migration de commande par commande, consultez Migration à partir d’APIOps Toolkit.

Déployer ce scénario

Suivez la documentation de l’outil de ligne de commande APIOps dans le dépôt GitHub d’APIOps CLI. Commencez par une instance gestion des API hors production et utilisez les instructions de publication actuelles de l’interface CLI APIOps. Pour commencer à utiliser un environnement hors production, consultez Comment gérer la configuration gestion des API avec l’interface CLI APIOps.

Contributeurs

Microsoft conserve cet article. Les contributeurs suivants ont écrit cet article.

Auteurs principaux :

• Pat Altimore | Développeur de contenu senior
• Wael Kdouh | Architecte de solution principal senior
• Rishabh Saha | Architecte de solution principal senior

Pour afficher les profils LinkedIn non publics, connectez-vous à LinkedIn.

Étapes suivantes

• APIOps CLI
• Comment gérer la configuration gestion des API avec l’interface CLI APIOps
• Vue d’ensemble de GitOps

Ressources associées

• GitOps pour Azure Kubernetes Service (AKS)
• Migrer une application web à l’aide de Gestion des API
• Protéger les API à l’aide d’Azure Application Gateway et gestion des API