Automatisera API Management-konfigurationen med hjälp av APIOps CLI

Azure API Management

Azure DevOps

Azure-pipelines

GitHub

APIOps är en metod som tillämpar begreppen GitOps och DevOps på API-distribution. Den här arkitekturen visar hur du använder APIOps CLI för att extrahera, granska och höja upp Azure API Management konfiguration via ett Git-baserat arbetsflöde. Använd den här metoden för att hantera API-livscykeln, förbättra API-kvaliteten och underhålla en granskningsbar post med godkända ändringar.

Arkitektur

Följande diagram illustrerar arbetsflödet för APIOps CLI-konfigurationshöjning på hög nivå. Team granskar API Management-artefakter i Git, och därefter flyttar CI/CD-pipelines (kontinuerlig integration och kontinuerlig leverans) den godkända konfigurationen till målmiljöer för API Management.

Ladda ned en Visio fil i den här arkitekturen.

Arbetsflöde

API Management-konfigurationen startar genom att antingen extrahera en befintlig API Management-konfiguration eller genom att redigera CLI-kompatibla API Management-artefakter. Det operativa arbetsflödet börjar med någon av dessa artefaktindata. Båda sökvägarna leder till samma pull-begäran, validering, godkännande och distributionsprocess:

(A) Extrahera först: En API-operator kör apiops extract mot en befintlig API Management-instans för att skapa API Management-artefaktfiler i den utcheckade grenen i sin lokala Git-arbetskopia. Operatorn använder dessa artefakter för att föreslå en baslinje eller avbilda en godkänd konfigurationsändring.
(B) Kod först: En API-utvecklare skapar eller uppdaterar APIOps CLI-kompatibla API-specifikationer, informationsfiler, principer och relaterade API Management-artefakter i sin lokala Git-utcheckningsgren.

Använd följande livscykel för indata:

Skapa en konfigurationsändring. Efter den initiala extraheringen eller incheckningen av skapandet av artefakter enligt kod först-modellen blir API-konfigurationslagringsplatsen den auktoritativa källan för konfigurationsartefakter för API Management. Lagringsplatsen underhåller versionshistoriken och granskningsposten för varje distribution. För att göra en ändring skapar en API-operatör eller utvecklare en gren från den skyddade grenen i API-konfigurationslagringsplatsen och gör en logisk ändring relaterad till API:et.
Granska och verifiera ändringen. Operatorn eller utvecklaren öppnar en pull-begäran för att sammanfoga sin gren till en skyddad gren. De ägare och granskare som krävs för API-kontraktet, principerna och API Management-konfigurationen granskar pull-begäran. CI/CD-systemet kör följande kontroller och tester:
- lintning av API-specifikationer
- Detektering av brytande ändringar gentemot det godkända kontraktet
- Säkerhetsgenomsökning av specifikationer och lagringsplatsinnehåll
- API-tester som verifierar förväntat beteende, autentisering, principeffekter och serverdelsberoenden
Dessa kontroller kräver inte Microsoft verktyg. Teamet använder alla lämpliga verktyg som uppfyller organisationens support-, säkerhets- och licenskrav.
Godkänn oföränderliga distributionsindata. Nödvändiga ägare eller granskare godkänner pull-begäran och en auktoriserad lagringsplatsunderhållare sammanfogar de granskade ändringarna efter att alla nödvändiga kontroller och granskningar har godkänts. Den sammanslagna, oföränderliga committen och dess artifakter för den skyddade grenen blir kodförrådets granskningsbara källa till sanning.

Teamet skyddar de skyddade lagringsplatsens grenar från direkta push-överföringar, kräver godkännanden av miljö- eller tjänstanslutningar för känsliga mål och använder separata identiteter med lägsta behörighet för extrahering och publicering. De registrerar den godkända committen med tillhörande pull request, granskningar och valideringsresultat för spårbarhet.
Förhandsgranska distributionen. CI/CD-pipelinen kör apiops publish --dry-run för den godkända committen med samma mål och samma override-fil utan att publicera. Versionsgodkännaren granskar de resurser som torrkörningen skapar, uppdaterar, tar bort eller hoppar över. Teamet behandlar en lyckad torrkörning som en distributionsport, inte en ersättning för automatiserade API-tester.
Publicera och marknadsför. När den torra körningen har validerats använder CI/CD-pipelinen apiops publish för att publicera samma granskade commit. För flera miljöer håller plattformsteamet delade artefakter stabila och använder granskade åsidosättningskonfigurationsfiler för värden som serverdels-URL:er, resurs-ID:n och hemliga referenser. Teamet flyttar vidare committen genom icke-produktionsmiljöer innan den når produktionsmiljön och förhindrar att fler än en pipeline skriver till samma mål samtidigt.

Anmärkning

Konfigurationen accepterar underordnade åsidosättningar för arbetsytan, men tillämpar dem inte vid publicering. Publiceringen gäller endast åsidosättningar för själva arbetsytecontainern. Förlita dig inte på underordnade åsidosättningar på arbetsytenivå för att befordra miljöspecifika API:er för arbetsytor, backend-system, namngivna värden eller andra underordnade resurser. Validera en alternativ metod för publicering för dessa resurser, eller skjut upp publiceringen tills den kända frågan Åsidosättningsegenskaper med arbetsyteomfång tillämpas inte har lösts.
Verifiera och stämma av efter distributionen. Efter publicering kör driftteamet automatiserade smoke-tester och regressionstester, övervakar API Management och status för backend-systemen samt jämför den driftsatta versionen med den godkända committen. Teamet undersöker och löser oväntade ändringar genom pull-begäranden i stället för att redigera produktionen direkt.

Om en API-operatör gör en godkänd nödändring direkt i API Management måste operatören köra en extraktion i en Git-arbetskopia, granska och checka in artefaktändringen på sin gren, pusha upp grenen och öppna en pull request. De ägare eller granskare som krävs måste granska och godkänna pull-begäran, och en auktoriserad lagringsplatsunderhållare måste slå samman den så att lagringsplatsen förblir auktoritativ.

Komponenter

API Management är en hanterad tjänst som skapar konsekventa API-gatewayer för serverdelstjänster. I den här arkitekturen tillhandahåller den de källkonfigurationer som APIOps CLI extraherar och målmiljöerna där CLI publicerar godkända API-definitioner, principer, produkter, diagnostik, namngivna värden och annan konfiguration som stöds.
APIOps CLI är ett projekt med öppen källkod som tillhandahåller verktyg för en åsiktsbaserad APIOps-metod. I den här arkitekturen extraherar den API Management-konfigurationen till artefaktfiler, publicerar artefakter till API Management och kan skapa CI/CD-arbetsflöden.
En Git-lagringsplats lagrar API Management-artefakter och, i förekommande fall, API-kontrakt. Den innehåller granskningshistoriken och den godkända sanningskällan för pipelinedistributioner.
Ett CI/CD-system kör validering, extrahering och publicering med hjälp av en arbetsbelastningsidentitet eller andra icke-interaktiva autentiseringsuppgifter som stöds. I den här arkitekturen GitHub Actions eller Azure-pipelines definiera CI/CD-arbetsflöden.

Alternativ

Du kan ersätta eller utöka den här arkitekturen med andra Azure tjänster eller metoder, beroende på arbetsbelastningens funktionella och icke-funktionella krav. Överväg följande alternativ och kompromisser.

Bicep eller Terraform och APIOps kan hantera olika delar av samma lösning. Ett team som äger både API Management-konfigurationen och infrastrukturen kan använda infrastruktur som kod (IaC) för att etablera API Management-tjänsten och dess stödinfrastruktur och använda samma IaC-pipeline för att hantera API Management-konfigurationen. Välj den här metoden när infrastrukturen och konfigurationen ändras och distribueras tillsammans, och när parametrar kan uttrycka skillnaderna mellan miljöer.

Använd APIOps-mönstret när API-definitioner, principer och relaterad konfiguration har separata ägare eller en versionslivscykel som är oberoende av tjänstinfrastrukturen. APIOps är också lämpligt när du behöver extrahera befintlig konfiguration, granska API-fokuserade artefakter eller höja upp samma godkända konfiguration i flera miljöer eller API Management-instanser. Vanligare API- och principändringar eller fler miljöer ökar värdet för det här dedikerade arbetsflödet.

Dessa faktorer har inte fasta tröskelvärden. Basera beslutet främst på ägarskap, granskningskrav och distributionsgränser. För en mindre API-egendom med en låg ändringstakt börjar du med ett manuellt arbetsflöde för pull-begäranden och lägger till extraheringsscheman eller distributionsautomatisering först efter att lagringsplatsens baslinje och godkännandeprocess har upprättats.

Information om scenario

APIOps använder versionskontroll för att hantera API:er och skapa en spårningslogg med ändringar i API-definitioner, principer, produkter, diagnostik och annan API Management-konfiguration. Genom att granska ändringar tidigare och oftare kan team identifiera avvikelser från API-standarder före distributionen. När fler API:er använder samma process kan teamen öka enhetligheten i sin API-miljö.

Det här arbetsflödet distribuerar API Management-konfigurationen till en API Management-instans. Den distribuerar inte API-serverdelar, programberäkning eller dataresurser, nätverk eller API Management-tjänstens infrastruktur. Använd separata reglerade IaC- och programpipelines för att distribuera dessa lager.

Den här lösningen hjälper teamen:

Underhålla en översikt över miljöer och API Management-instanser.
Spåra viktiga ändringar i API:er och principer.
Skapa en revisionslogg för godkända driftsättningar.
Sammanfoga godkända ändringar som härrör från utanför lagringsplatsen.

Välj artefaktkällor och ägarskap

Välj bland följande sätt som artefakter hamnar i lagringsplatsen och vem som äger dem innan du automatiserar distribution.

Extrahera först: Extrahera en verifierat fungerande API Management-instans för att fastställa en inledande baslinje för artefakterna. Granska de incheckade genererade artefakterna innan du behandlar lagringsplatsen som sanningskälla.
Kod först: Behåll API-kontraktet, till exempel en OpenAPI-beskrivning, med programkällan eller APIOps-lagringsplatsen. Definiera vem som omvandlar kontraktet till API Management-artefakterna som pipelinen publicerar. Verifiera det avsedda arbetsflödet för import och artefakt med en instans av API Management som inte är produktionsbaserad. Anta inte att en godtycklig källlayout är direkt användbar för CLI:t.
Delat ansvar: Fastställa om API-utvecklare, plattformsoperatorer eller båda äger ändringar i principer, produkter, diagnostik, namngivna värden och API-definitioner. När baslinjen har godkänts dirigerar du varje ändring via samma lagringsplats och granskningsprocess.

Potentiella användningsfall

Organisationer som utvecklar och hanterar API:er, inklusive organisationer med ett enda API som exponeras via API Management.
Strikt reglerade sektorer som försäkring, bank, finans och myndigheter som behöver spårningsbara gransknings- och distributionsregister.

Att tänka på

Dessa överväganden implementerar grundpelarna i Azure Well-Architected Framework, som är en uppsättning vägledande grundsatser som du kan använda för att förbättra kvaliteten på en arbetsbelastning. För mer information, se Well-Architected Framework.

Reliability

Tillförlitlighet hjälper till att säkerställa att ditt program kan uppfylla de åtaganden som du gör gentemot dina kunder. Mer information finns i Checklista för designgranskning för tillförlitlighet.

För API-ändringar som inte medför kompatibilitetsbrott använder du revisioner i API Management för att distribuera och testa en revision som inte är aktuell innan du gör den aktuell. Om verifieringen misslyckas efter lanseringen återställer du den tidigare revisionen som aktuell. Använd API-versioner för att bryta avtalsändringar så att befintliga konsumenter kan fortsätta att använda den tidigare versionen.

Samordna API Management-konfigurationsändringar med distributionsstrategin för varje API-serverdel. Om du återställer en APIOps-incheckning återställs endast den konfiguration som representeras av incheckningen. Den återställer inte en inkompatibel eller otillgänglig serverdel. Registrera APIOps-incheckningen, API Management-revisionen och serverdelsutgåvan som utgör varje verifierad distribution. Testa den fullständiga återställningsproceduren i en icke-produktionsmiljö, inklusive principer, namngivna värden, hemliga referenser, beroenden och backend-kompatibilitet.

Säkerhet

Säkerhet ger garantier mot avsiktliga attacker och missbruk av värdefulla data och system. Mer information finns i Checklista för designgranskning för säkerhet.

Använd repot och pipelinen som det normala sättet att genomföra ändringar i API Management. Utvecklare och operatörer behöver inte beständig skrivåtkomst till API Management-produktionsinstanser. Bevilja endast förhöjd åtkomst vid behov och endast under en begränsad tid. Stäm av eventuella ändringar som uppstår i lagringsplatsen.

Använd följande mekanismer för att skydda Git-lagringsplatsen som lagrar API Management-artefakter:

Granskning av pull-begäran: Skydda grenar som distribuerar konfiguration och kräver granskning av lämpliga granskare.
Isolering av autentiseringsuppgifter: Föredrar federerad arbetsbelastningsidentitet om den är tillgänglig. Lagra miljöspecifika hemligheter i en godkänd hemlig lagringsplats eller lagringsplatsmiljö, inte i artefakter eller pipelinefiler.
Incheckningsintegritet: Kräv signerade incheckningar för att verifiera incheckningens proveniens. Konfigurera grenskydd för att förhindra borttagning av framtvingade push-meddelanden och grenar, kräva multifaktorautentisering för att användare ska kunna godkänna eller slå samman ändringar och bevara historiken för inchecknings- och pull-begäranden för distributioner.
Granskning av artefakter: Granska utdata från extrahering och indata för publicering med avseende på hemliga uppgifter, maskeringsmarkörer och oavsiktliga miljöspecifika värden. Kontrollera att en ändring inte breddar API-åtkomsten eller försvagar en princip.

Hantera APIOps CLI som ett lagringsplatsberoende. Lås @azure-tools/apiops-cli i package.json till en testad version, checka in låsfilen och använd npm ci. Granska genererade identitetsinställningar, variabler, utlösare och skyddsregler innan du aktiverar en produktionspipeline.

Kostnadsoptimering

Kostnadsoptimering fokuserar på sätt att minska onödiga utgifter och förbättra drifteffektiviteten. Mer information finns i Checklista för designgranskning för kostnadsoptimering.

APIOps CLI är programvara med öppen källkod, men det här scenariot medför kostnader för API Management-instanserna och den valda källkontrollen och CI/CD-plattformen. En enda fast uppskattning tillhandahålls inte eftersom API Management-priserna varierar beroende på region, nivå, antal enheter, kapacitetsmodell, tillgänglighetszon eller konfiguration i flera regioner och användning. CI/CD-avgifter beror också på typ av löpare, inkluderade minuter, samtidighet, lagring och kvarhållning.

Skapa en scenariospecifik uppskattning i priskalkylatorn för Azure och registrera följande antaganden med arkitekturbeslutet:

Uppskatta indata	Antagande att registrera
API Management-region	Distributionsregionen för varje utvecklings-, test-, mellanlagrings- och produktionsinstans.
Nivå och kapacitet	Nivån eller v2-nivån, antalet enheter eller gatewayer och drifttimmar för varje miljö.
Motståndskraft	All distribution i tillgänglighetszoner eller ytterligare regioner, inklusive enheterna på varje plats.
Användningsbaserade avgifter	Förväntade förfrågningar eller åtgärder samt eventuella tillämpliga avgifter för arbetsyta, lokalt hanterad gateway, nätverk, övervakning eller dataöverföring.
CI/CD-plattform	GitHub-hanterade, självhanterade eller Azure-pipelines-agenter. Förväntade pipelinekörningar, varaktighet, samtidighet, lagring och logg- eller artefaktkvarhållning.
Källkontroll och licenser	Antal användare och eventuella funktioner i betalda GitHub- eller Azure DevOps-abonnemang.

Använd den aktuella prisinformationen för API Management för att välja den tillämpliga faktureringsmodellen. Information om antaganden för CI/CD och källkontroll finns i Azure DevOps prissättning och GitHub prissättning. Exportera eller samla in kalkylatorns uppskattning, dess valuta, prisdatum och alla antaganden så att granskare kan återskapa och uppdatera den. Beräkna om före distributionen och när regioner, nivåer, antal enheter, miljöer eller pipelineanvändning ändras.

Operativ skicklighet

Operational Excellence omfattar de driftsprocesser som distribuerar ett program och håller det igång i produktion. Mer information finns i Checklista för designgranskning för Operational Excellence.

APIOps gör distributioner repeterbara och skapar en incheckningshistorik för analys efter ändring. Tagga eller på annat sätt registrera incheckningen som varje miljö tar emot, behålla pipelineloggar och övervaka API Management-instansen och beroende API:er efter distributionen.

För flera miljöer kan samma granskade artefakt-commit flyttas vidare genom utveckling, test och produktion. Använd endast miljö åsidosättningar för värden som måste skilja sig åt mellan miljöer och granska filerna med samma försiktighet som artefakterna. Underordnad åsidosättning av arbetsyta tillämpas inte vid publiceringstillfället, så använd dem inte för miljöhöjning. Testa återgångsprocedurer innan en incident inträffar. En Git-återställning kräver fortfarande validering och en kontrollerad publicering för att återställa API Management.

CLI:t innehåller kommandona init, extract och publish och kan generera GitHub Actions eller Azure DevOps-pipelines. Granska kommandoinformationen i APIOps CLI-dokumentationen.

Migrera på ett säkert sätt från det äldre APIOps Toolkit

Om din APIOps-process använder det äldre APIOps Toolkit planerar du att uppgradera. Den metoden använder separata extraktor- och Publisher binärfiler och pipelinemallar. APIOps CLI använder en enda Node.js CLI, men dess artefaktformat är utformat för att vara kompatibelt med befintliga verktygsartefakter. Behandla migreringen som en kontrollerad snabbmigrering, inte som en produktionsuppgradering på plats.

Tagga de kända verktygstefakterna och pipelinen och bevara den befintliga utgivaren som ett återställningsalternativ. Ändra inte den äldre utgivaren och introducera den nya utgivaren i samma distribution.
I en migreringsgren använder du den senaste APIOps CLI-versionen och kör apiops init utan att använda --force. Kommandot identifierar filer som är i konflikt och avslutas i stället för att skriva över dem. Jämför och integrera avsiktligt genererade pipelines, identitetsvägledning, filter och åsidosättningsfiler.
Använd artefakterna med apiops publish --dry-run och målmiljöns åsidosättningar mot en icke-produktionsinstans av API Management. Granska de resurser som CLI skulle skapa, uppdatera eller ta bort. Testa en kontrollerad publicering och verifiera distribuerade API:er, principer, namngivna värden och beroenden.
Använd inte underordnade åsidosättningar för arbetsytan, som inte tillämpas vid publiceringstillfället, som en del av migrerings- eller befordransdesignen. Validera en alternativ metod för uppflyttning för berörda underresurser, eller skjut upp migreringen tills den kända frågan Åsidosättningsegenskaper med arbetsyteomfång tillämpas inte har lösts.
Vid driftsättning ska endast en publicerare tillåtas att skriva till en API Management-instans. Inaktivera den äldre utgivarutlösaren innan du aktiverar CLI-utgivaren. Driftsätt en granskad commit och övervaka resultatet. Behåll den taggade Toolkit-pipelinen och artefaktbaslinjen tills det nya arbetsflödet har slutfört en lyckad releasecykel.

Kompatibilitetsinformation och exempel på kommando-för-kommando-migrering finns i Migrering från APIOps Toolkit.

Distribuera det här scenariot

Följ APIOps CLI-dokumentationen i APIOps CLI-GitHub-lagringsplatsen. Börja med en API Management-instans som inte är avsedd för produktion och använd vägledningen för den aktuella versionen av APIOps CLI. Information om hur du kommer igång med en icke-produktionsmiljö finns i Hantera API Management-konfiguration med APIOps CLI.

Deltagare

Microsoft ansvarar för den här artikeln. Följande bidragsgivare skrev den här artikeln.

Huvudsakliga författare:

Pat Altimore | Senior innehållsutvecklare
Wael Kdouh | Senior Principal Solution Architect
Rishabh Saha | Senior Principal Solution Architect

Om du vill se linkedin-profiler som inte är offentliga loggar du in på LinkedIn.

Nästa steg

Feedback

Var den här sidan till hjälp?