API Management-configuratie automatiseren met behulp van APIOps CLI

APIOps is een methodologie die de concepten van GitOps en DevOps toepast op API-implementatie. Deze architectuur laat zien hoe u APIOps CLI gebruikt om Azure API Management configuratie te extraheren, beoordelen en promoten via een git-werkstroom. Gebruik deze benadering voor het beheren van de API-levenscyclus, het verbeteren van de API-kwaliteit en het onderhouden van een controlebare record van goedgekeurde wijzigingen.

Architectuur

In het volgende diagram ziet u de werkstroom voor de promotie van APIOps CLI-configuratie op hoog niveau. Teams beoordelen API Management-artefacten in Git en vervolgens zorgen ervoor dat ci/CD-pijplijnen (continue integratie en continue levering) de goedgekeurde configuratie promoveren naar API Management-omgevingen.

Download een Visio-bestand van deze architectuur.

Werkproces

API Management-configuratie begint door een bestaande API Management-configuratie te extraheren of door CLI-compatibele API Management-artefacten te ontwerpen. De operationele werkstroom begint met een van deze artefactinvoeren. Beide paden leiden tot hetzelfde pull-aanvraag-, validatie-, goedkeurings- en implementatieproces:

• (A) Eerst extraheren: Een API-operator voert apiops extract uit op een bestaand API Management-exemplaar om artefactbestanden van API Management te maken in de lokaal uitgecheckte Git-branch. De operator gebruikt deze artefacten om een basislijn voor te stellen of een goedgekeurde configuratiewijziging vast te leggen.

• (B) Code-first: Een API-ontwikkelaar schrijft of werkt APIOps CLI-compatibele API-specificaties, ინფორმati ebestanden, beleidsregels en gerelateerde API Management-artefacten bij in zijn lokale Git-checkoutbranch.

Gebruik de volgende levenscyclus voor beide invoer:

1. Maak een configuratiewijziging. Na de eerste extractie- of code-first controle voor het maken van artefacten, wordt de API-configuratieopslagplaats de gezaghebbende bron van waarheid voor API Management-configuratieartefacten. De opslagplaats onderhoudt de versiegeschiedenis en controlerecord voor elke implementatie. Als u een wijziging wilt aanbrengen, maakt een API-operator of ontwikkelaar een vertakking van de beveiligde vertakking in de API-configuratieopslagplaats en brengt één logische wijziging aan die betrekking heeft op de API.

2. Controleer en valideer de wijziging. De operator of de ontwikkelaar opent een pull request om hun branch samen te voegen met een beveiligde branch. De vereiste eigenaren en revisoren van het API-contract, -beleid en de API Management-configuratie controleren de pull-aanvraag. Het CI/CD-systeem voert de volgende controles en tests uit:

   • Linting van API-specificatie
   • Detectie van incompatibele wijzigingen ten opzichte van het goedgekeurde contract
   • Beveiligingsscans van specificaties en inhoud van opslagplaats
   • API-tests die het verwachte gedrag, verificatie, beleidseffecten en back-endafhankelijkheden controleren

   Voor deze controles zijn geen Microsoft hulpprogramma's vereist. Het team gebruikt alle geschikte hulpprogramma's die voldoen aan de ondersteunings-, beveiligings- en licentievereisten van de organisatie.

3. Keur de onveranderbare implementatie-invoer goed. Vereiste eigenaren of reviewers keuren de pull request goed en een geautoriseerde repositorybeheerder mergeert de beoordeelde wijzigingen nadat alle vereiste controles en reviews zijn geslaagd. De samengevoegde, onveranderbare commit en de artefacten van de beveiligde branch worden de controleerbare, gezaghebbende bron van de repository.

   Het team beveiligt de beveiligde opslagplaatsvertakkingen tegen directe pushes, vereist goedkeuringen voor omgevings- of serviceverbindingen voor gevoelige doelen en maakt gebruik van afzonderlijke identiteiten met minimale bevoegdheden voor extractie en publicatie. Ze registreren de goedgekeurde commit met de bijbehorende pullrequest, reviews en validatieresultaten ten behoeve van auditbaarheid.

4. Bekijk een voorbeeld van de implementatie. De CI/CD-pijplijn wordt uitgevoerd apiops publish --dry-run voor de goedgekeurde doorvoer met hetzelfde doel en overschrijft het bestand zonder publicatie. Degene die de release goedkeurt, controleert de resources die tijdens het proefdraaien worden gemaakt, bijgewerkt, verwijderd of overgeslagen. Het team behandelt een geslaagde drooguitvoering als een implementatiepoort, niet als vervanging voor geautomatiseerde API-tests.

5. Publiceren en promoten. Nadat de proefuitvoering de validatie succesvol heeft doorstaan, gebruikt de CI/CD-pijplijn apiops publish om dezelfde gereviewde commit te publiceren. Voor meerdere omgevingen houdt het platformteam gedeelde artefacten stabiel en gebruikt het beoordeelde override-configuratiebestanden voor waarden zoals back-end-URL's, resource-id's en verwijzingen naar geheimen. Het team bevordert de doorvoer via niet-productie vóór de productie en voorkomt dat meerdere pijplijnen tegelijkertijd naar hetzelfde doel schrijven.

   Note

   De configuratie ondersteunt onderliggende overschrijvingen van de werkruimte, maar past deze niet toe bij het publiceren. Bij het publiceren worden overschrijvingen alleen op de werkruimtecontainer zelf toegepast. Vertrouw niet op onderliggende overschrijvingen van werkruimten om omgevingsspecifieke werkruimte-API's, back-ends, benoemde waarden of andere onderliggende resources te bevorderen. Controleer een alternatieve promotieaanpak voor die resources, of stel de promotie uit totdat het bekende probleem Werkruimtegebonden overschrijvingseigenschappen niet toegepast is opgelost.

6. Valideren en afstemmen na de implementatie. Na publicatie voert het operationsteam geautomatiseerde smoketests en regressietests uit, monitort het de gezondheid van API Management en de back-end, en vergelijkt het de uitgerolde versie met de goedgekeurde commit. Het team onderzoekt en lost onverwachte wijzigingen op via pull-aanvragen in plaats van rechtstreeks productie te bewerken.

   Als een API-operator rechtstreeks in API Management een goedgekeurde spoedwijziging aanbrengt, moet de operator in een Git-checkout een extractie uitvoeren, de artefactwijziging op zijn of haar branch beoordelen en committen, de branch pushen en een pull request openen. De vereiste eigenaren of revisoren moeten de pull-aanvraag controleren en goedkeuren en een geautoriseerde opslagplaatsonderhouder moet deze samenvoegen, zodat de opslagplaats gezaghebbend blijft.

Onderdelen

• API Management is een beheerde service waarmee consistente API-gateways voor back-endservices worden gemaakt. In deze architectuur biedt het de bronconfiguraties die de APIOps CLI extraheert en de doelomgevingen waar de CLI goedgekeurde API-definities, beleid, producten, diagnostische gegevens, benoemde waarden en andere ondersteunde configuratie publiceert.

• APIOps CLI is een opensource-project dat hulpprogramma's biedt voor een aanbevolen APIOps-benadering. In deze architectuur worden API Management-configuraties geëxtraheerd in artefactbestanden, worden artefacten gepubliceerd naar API Management en kunnen CI/CD-werkstromen worden gegenereerd.

• In een Git-opslagplaats worden API Management-artefacten en, indien van toepassing, API-contracten opgeslagen. Het biedt de beoordelingsgeschiedenis en de goedgekeurde bron van waarheid voor pijplijnimplementaties.

• Een CI/CD-systeem voert validatie, extractie en publicatie uit met een workloadidentiteit of een ander ondersteund niet-interactief verificatiemiddel. In deze architectuur GitHub Actions of Azure-pipelines de CI/CD-werkstromen definiëren.

Alternatieven

U kunt deze architectuur vervangen of uitbreiden met andere Azure services of benaderingen, afhankelijk van de functionele en niet-functionele vereisten van uw workload. Houd rekening met de volgende alternatieven en compromissen.

Bicep of Terraform en APIOps kunnen verschillende onderdelen van dezelfde oplossing leveren. Een team dat zowel eigenaar is van de API Management-configuratie als infrastructuur kan infrastructuur als code (IaC) gebruiken om de API Management-service en de ondersteunende infrastructuur in te richten, en dezelfde IaC-pijplijn gebruiken om DE API Management-configuratie te beheren. Kies deze benadering wanneer de infrastructuur en configuratie samen worden gewijzigd en geïmplementeerd, en wanneer parameters de verschillen tussen omgevingen kunnen uitdrukken.

Gebruik het APIOps-patroon wanneer API-definities, beleidsregels en gerelateerde configuratie afzonderlijke eigenaren of een releaselevenscyclus hebben die onafhankelijk is van de service-infrastructuur. APIOps is ook geschikt wanneer u bestaande configuratie moet extraheren, API-gerichte artefacten wilt controleren of dezelfde goedgekeurde configuratie wilt promoten in meerdere omgevingen of API Management-exemplaren. Frequentere API- en beleidswijzigingen of meer omgevingen verhogen de waarde van deze toegewezen werkstroom.

Deze factoren hebben geen vaste drempelwaarden. Baseer de beslissing voornamelijk op eigendom, beoordelingsvereisten en implementatiegrenzen. Voor een kleinere API-omgeving met een lage wijzigingssnelheid begint u met een handmatige werkstroom voor pull-aanvragen en voegt u pas extractieschema's of implementatieautomatisering toe nadat de basislijn en het goedkeuringsproces van de opslagplaats tot stand zijn gebracht.

Details van het scenario

APIOps maakt gebruik van versiebeheer voor het beheren van API's en het maken van een audittrail met wijzigingen in API-definities, beleidsregels, producten, diagnostische gegevens en andere API Management-configuraties. Door wijzigingen eerder en vaker te bekijken, kunnen teams afwijkingen van API-standaarden identificeren vóór de implementatie. Naarmate meer API's hetzelfde proces gebruiken, kunnen teams de consistentie in hun API-omgeving verbeteren.

Met deze werkstroom wordt API Management-configuratie geïmplementeerd in een API Management-exemplaar. Er worden geen API-back-ends, reken- of gegevensresources voor toepassingen, netwerken of de API Management-service-infrastructuur geïmplementeerd. Gebruik afzonderlijke beheerde IaC- en toepassingspijplijnen om deze lagen te implementeren.

Deze oplossing helpt teams:

• Behoud een overzicht van omgevingen en API Management-instanties.
• Houd kritieke wijzigingen in API's en beleidsregels bij.
• Maak een audittrail voor goedgekeurde implementaties.
• Goedgekeurde wijzigingen afstemmen die afkomstig zijn van buiten de opslagplaats.

Artefactbronnen en eigendom kiezen

Kies uit de volgende manieren waarop artefacten de opslagplaats invoeren en wie eigenaar is van de opslagplaats voordat u de implementatie automatiseert:

• Extract-first: Extraheer een verifiëerbaar goed werkende API Management-instantie om de eerste basislijn van artefacten op te bouwen. Controleer de ingecheckte gegenereerde artefacten voordat u de repository als de gezaghebbende bron beschouwt.
• Code-first: Behoud het API-contract, zoals een OpenAPI-beschrijving, met de toepassingsbron of de APIOps-opslagplaats. Definieer wie dat contract transformeert in de API Management-artefacten die door de pijplijn worden gepubliceerd. Valideer de beoogde import- en artefactwerkstroom met een niet-productie-API Management-exemplaar. Stel niet dat een willekeurige bronindeling rechtstreeks kan worden gebruikt door de CLI.
• Gedeelde verantwoordelijkheid: Bepaal of API-ontwikkelaars, platformoperators of beide eigen wijzigingen in beleid, producten, diagnostische gegevens, benoemde waarden en API-definities hebben. Nadat de basislijn is geaccepteerd, routeert u elke wijziging via dezelfde opslagplaats en controleert u het proces.

Potentiële gebruikscases

• Organisaties die API's ontwikkelen en beheren, inclusief organisaties met één API die beschikbaar wordt gesteld via API Management.

• Sterk gereglementeerde sectoren zoals verzekeringen, banken, financiën en overheid die traceerbare controle- en implementatierecords nodig hebben.

Overwegingen

Met deze overwegingen worden de pijlers van het Azure Well-Architected Framework geïmplementeerd. Dit is een set richtlijnen die u kunt gebruiken om de kwaliteit van een workload te verbeteren. Zie Well-Architected Framework voor meer informatie.

Reliability

Betrouwbaarheid zorgt ervoor dat uw toepassing kan voldoen aan de toezeggingen die u aan uw klanten hebt gedaan. Zie Ontwerp controlelijst voor betrouwbaarheid voor meer informatie.

Voor niet-brekende API-wijzigingen gebruikt u API Management-revisies om een niet-huidige revisie te implementeren en te testen voordat u deze actueel maakt. Als de validatie mislukt na de release, herstelt u de vorige revisie als actueel. Gebruik API-versies voor belangrijke contractwijzigingen, zodat bestaande consumenten de eerdere versie kunnen blijven gebruiken.

De configuratiewijzigingen van API Management coördineren met de implementatiestrategie voor elke API-back-end. Als u een APIOps-doorvoer terugzet, wordt alleen de configuratie hersteld die wordt vertegenwoordigd door die doorvoering. Er wordt geen incompatibele of niet-beschikbare back-end hersteld. Noteer de APIOps-doorvoer, API Management-revisie en back-endrelease die elke bekende goede implementatie vormen. Test de volledige terugdraaiprocedure in een niet-productieomgeving, inclusief beleid, benoemde waarden, geheime verwijzingen, afhankelijkheden en back-endcompatibiliteit.

Beveiliging

Beveiliging biedt garanties tegen opzettelijke aanvallen en misbruik van waardevolle gegevens en systemen. Zie de controlelijst ontwerpbeoordeling voor beveiliging voor meer informatie.

Gebruik de opslagplaats en pijplijn als het normale pad voor het toepassen van API Management-wijzigingen. Ontwikkelaars en operators hebben geen permanente schrijftoegang nodig tot productie-API Management-exemplaren. Ververleent verhoogde toegang alleen indien nodig en alleen gedurende een beperkte tijd. Eventuele resulterende wijzigingen in de opslagplaats afstemmen.

Gebruik de volgende mechanismen om de Git-opslagplaats te beveiligen waarin API Management-artefacten worden opgeslagen:

• Beoordeling van pull requests: Beveilig branches waarin configuratie wordt uitgerold en vereis beoordeling door de juiste beoordelaars.
• Isolatie van inloggegevens: Gebruik bij voorkeur een gefedereerde workloadidentiteit indien beschikbaar. Bewaar omgevingsspecifieke geheimen in een goedgekeurde geheime archief- of opslagplaatsomgeving, niet in artefacten of pijplijnbestanden.
• Doorvoerintegriteit: Ondertekende doorvoeringen vereisen om de herkomst van de doorvoer te controleren. Configureer branchbeveiliging om force-pushes en het verwijderen van branches te voorkomen, vereis multifactorauthenticatie zodat gebruikers wijzigingen kunnen goedkeuren of samenvoegen, en behoud de commit- en pullrequestgeschiedenis voor implementaties.
• Artefactbeoordeling: Inspecteer uitvoer van extractie en publiceer invoer voor geheimen, redacted markers en onbedoelde omgevingsspecifieke waarden. Controleer of een wijziging api-toegang niet verbreedt of een beleid verzwakt.

Beheer de APIOps CLI als repository-afhankelijkheid. Zet @azure-tools/apiops-cli in package.json vast op een geteste versie, commit het lockbestand en gebruik npm ci. Controleer gegenereerde identiteitsinstellingen, variabelen, triggers en beveiligingsregels voordat u een productiepijplijn inschakelt.

Kostenoptimalisatie

Kostenoptimalisatie richt zich op manieren om onnodige uitgaven te verminderen en operationele efficiëntie te verbeteren. Zie de controlelijst ontwerpbeoordeling voor Kostenoptimalisatie voor meer informatie.

APIOps CLI is opensource-software, maar in dit scenario worden kosten in rekening gebracht voor de API Management-exemplaren en het geselecteerde broncodebeheer- en CI/CD-platform. Eén vaste schatting wordt niet opgegeven omdat de prijzen van API Management variëren per regio, laag, aantal eenheden, capaciteitsmodel, beschikbaarheidszone of configuratie met meerdere regio's en gebruik. CI/CD-kosten zijn ook afhankelijk van het type runner, inclusief minuten, gelijktijdigheid, opslag en retentie.

Maak een scenariospecifieke schatting in de Azure prijscalculator en noteer de volgende veronderstellingen met de architectuurbeslissing:

Gebruik de huidige prijsinformatie voor API Management om het toepasselijke factureringsmodel te selecteren. Zie Azure DevOps prijzen en GitHub prijzen voor CI/CD en broncodebeheer. Exporteer of leg de schatting van de rekenmachine, de valuta, de prijsdatum en alle veronderstellingen vast, zodat revisoren deze kunnen reproduceren en bijwerken. Herbereken vóór de implementatie en wanneer regio's, lagen, eenheden, omgevingen of pijplijngebruik veranderen.

Operationele uitmuntendheid

Operational Excellence behandelt de operationele processen die een toepassing implementeren en deze in productie houden. Zie de controlelijst ontwerpbeoordeling voor Operational Excellence voor meer informatie.

APIOps maakt implementaties herhaalbaar en maakt een doorvoergeschiedenis voor analyse na wijzigingen. Tag of leg op een andere manier vast welke commit elke omgeving krijgt, bewaar de logboeken van de pijplijn en bewaak na de uitrol het API Management-exemplaar en de afhankelijke API's.

Voor meerdere omgevingen promoot u dezelfde beoordeelde artefact-commit door development, staging en productie. Gebruik omgevingsoverschrijvingen alleen voor waarden die moeten verschillen tussen omgevingen en controleer deze bestanden met dezelfde zorg als de artefacten. Onderliggende werkruimte-overschrijvingen worden niet toegepast bij het publiceren, dus gebruik ze niet voor promotie naar een andere omgeving. Test terugdraaiprocedures voordat een incident plaatsvindt. Een Git-herstel vereist nog steeds validatie en een gecontroleerde publicatie om API Management te herstellen.

De CLI biedt init, extracten opdrachten en publish kan GitHub Actions of Azure DevOps pijplijnen opzetten. Bekijk de opdrachtdetails in de APIOps CLI-documentatie.

Veilig migreren vanuit de verouderde APIOps Toolkit

Als uw APIOps-proces gebruikmaakt van de verouderde APIOps Toolkit, moet u een upgrade uitvoeren. Deze benadering maakt gebruik van afzonderlijke Extractor- en Publisher binaire bestanden en pijplijnsjablonen. De APIOps CLI maakt gebruik van één Node.js CLI, maar de artefactindeling is ontworpen om compatibel te zijn met bestaande toolkitartefacten. Beschouw migratie als een gecontroleerde omschakeling, niet als een rechtstreekse upgrade van de productieomgeving.

1. Tag de geverifieerde toolkit-artefacten en de pipeline, en behoud de bestaande publisher als terugvaloptie. Wijzig de verouderde uitgever niet en introduceer de nieuwe uitgever in dezelfde implementatie.

2. Gebruik in een migratiebranch de nieuwste versie van APIOps CLI en voer apiops init uit zonder --force te gebruiken. De opdracht detecteert conflicterende bestanden en sluit ze af in plaats van ze te overschrijven. Vergelijk en voeg de gegenereerde pijplijnen, identiteitsaanbevelingen, filters en overschrijvingsbestanden bewust samen.

3. Gebruik de artefacten met apiops publish --dry-run en de overschrijvingen van de doelomgeving bij een niet-productie-exemplaar van API Management. Bekijk de resources die de CLI zou maken, bijwerken of verwijderen. Test één gecontroleerde publicatie en valideer de geïmplementeerde API's, beleidsregels, benoemde waarden en afhankelijkheden.

4. Gebruik geen onderliggende overschrijvingen binnen de werkruimte, die bij het publiceren niet worden toegepast, als onderdeel van het migratie- of promotieproces. Controleer een alternatieve promotieaanpak voor getroffen onderliggende resources, of stel de migratie ervan uit totdat het bekende probleem Override-eigenschappen met werkruimtebereik niet toegepast is opgelost.

5. Sta tijdens de omschakeling slechts één uitgever toe om schrijfacties uit te voeren op een API Management-exemplaar. Schakel de verouderde uitgevertrigger uit voordat u de CLI-uitgever inschakelt. Implementeer een gecontroleerd doorvoer en bewaak het resultaat. Behoud de getagde Toolkit-pijplijn en artifact-baseline totdat de nieuwe workflow een releasecyclus succesvol heeft voltooid.

Zie Migratie van APIOps Toolkit voor compatibiliteitsdetails en voorbeelden van migratie met opdrachten per opdracht.

Dit scenario implementeren

Volg de documentatie voor APIOps CLI in de APIOps CLI GitHub-repository. Begin met een niet-productie API Management-exemplaar en gebruik de huidige APIOps CLI-releaserichtlijnen. Zie API Management-configuratie beheren met APIOps CLI om aan de slag te gaan met een niet-productieomgeving.

Bijdragers

Microsoft onderhoudt dit artikel. De volgende inzenders hebben dit artikel geschreven.

Hoofdauteurs:

• Pat Altimore | Senior Content Developer
• Wael Kdouh | Senior Principal Solution Architect
• Rishabh Saha | Senior Principal Solution Architect

Als u niet-openbare LinkedIn-profielen wilt zien, meldt u zich aan bij LinkedIn.

Volgende stappen

• APIOps CLI
• API Management-configuratie beheren met APIOps CLI
• Overzicht van GitOps

Verwante bronnen

• GitOps voor Azure Kubernetes Service (AKS)
• Een web-app migreren met API Management
• API's beveiligen met behulp van Azure Application Gateway en API Management