Automatizace konfigurace služby API Management pomocí rozhraní APIOps CLI

Azure API Management

Azure DevOps

Azure Pipelines

GitHubu

APIOps je metodologie, která používá koncepty GitOps a DevOps pro nasazení rozhraní API. Tato architektura ukazuje, jak pomocí rozhraní APIOps CLI extrahovat, kontrolovat a propagovat konfiguraci Azure API Management prostřednictvím pracovního postupu založeného na Gitu. Pomocí tohoto přístupu můžete spravovat životní cyklus rozhraní API, zlepšit kvalitu rozhraní API a udržovat auditovatelný záznam schválených změn.

Architektura

Následující diagram znázorňuje postup propagace konfigurace APIOps CLI na vysoké úrovni. Týmy kontrolují artefakty služby API Management v Gitu a potom kanály kontinuální integrace a kontinuálního doručování (CI/CD) nasazují schválenou konfiguraci do cílových prostředí API Management.

Načte soubor Visio této architektury.

Workflow

Konfigurace služby API Management začíná extrahováním existující konfigurace služby API Management nebo vytvořením artefaktů služby API Management kompatibilních s rozhraním příkazového řádku. Provozní postup začíná jedním z těchto vstupních artefaktů. Obě cesty vedou ke stejnému procesu pull requestu, ověření, schválení a nasazení:

(A) Nejprve extrakce: Operátor rozhraní API spustí apiops extract proti existující instanci služby API Management, aby ve své místní odhlášené větvi Gitu vytvořil soubory artefaktů služby API Management. Operátor tyto artefakty používá k návrhu směrného plánu nebo zachycení schválené změny konfigurace.
(B) Code-first: Vývojář API ve své lokální checkoutnuté větvi Gitu vytváří nebo aktualizuje specifikace API kompatibilní s nástrojem APIOps CLI, informační soubory, zásady a související artefakty služby API Management.

Pro oba vstupy použijte následující životní cyklus:

Vytvořte změnu konfigurace. Po počáteční extrakci nebo po prvním check-inu artefaktů vytvořených přístupem code-first se repozitář konfigurace API stane jediným zdrojem pravdy pro konfigurační artefakty API Managementu. Úložiště udržuje historii verzí a záznam auditu pro každé nasazení. Pokud chcete provést změnu, operátor rozhraní API nebo vývojář vytvoří větev z chráněné větve v úložišti konfigurace rozhraní API a provede jednu logickou změnu související s rozhraním API.
Zkontrolujte a ověřte změnu. Správce nebo vývojář otevře pull request, aby sloučil svou větev do chráněné větve. Požadovaní vlastníci a recenzenti kontraktu API, zásad a konfigurace služby API Management zkontrolují pull request. Systém CI/CD spouští následující kontroly a testy:
- Linting specifikace rozhraní API
- Detekce zásadních změn proti schválené smlouvě
- Kontrola zabezpečení specifikace a obsahu úložiště
- Testy rozhraní API, které ověřují očekávané chování, autentizaci, dopady zásad a závislosti na back-endu
Tyto kontroly nevyžadují nástroje Microsoft. Tým používá libovolné vhodné nástroje, které splňují požadavky organizace na podporu, zabezpečení a licencování.
Schvalte neměnný vstup pro nasazení Požadovaní vlastníci nebo recenzenti schválí požadavek na přijetí změn a oprávněný správce úložiště po sloučení všech požadovaných kontrol a revizí sloučí změny. Sloučené neměnné potvrzení a artefakty chráněné větve se stanou auditovatelným zdrojem pravdivých informací v úložišti.

Tým chrání chráněné větve repozitáře před přímým odesíláním změn, pro citlivé cíle vyžaduje schválení prostředí nebo připojení služby a pro extrakci a publikování používá samostatné identity s nejnižšími nezbytnými oprávněními. Zaznamenávají schválený commit spolu s pull requesty, recenzemi a výsledky ověření kvůli zajištění auditovatelnosti.
Prohlédněte si náhled nasazení. Kanál CI/CD se spustí apiops publish --dry-run pro schválené potvrzení s použitím stejného cíle a přepsání souboru bez publikování. Schvalovatel vydání zkontroluje zdroje, které zkušební spuštění vytvoří, aktualizuje, odstraní nebo přeskočí. Tým považuje úspěšné zkušební spuštění za podmínku nasazení, nikoli za náhradu automatizovaných testů rozhraní API.
Publikujte a propagujte. Jakmile zkušební běh projde validací, CI/CD pipeline použije apiops publish k publikování téhož zkontrolovaného commitu. Pro více prostředí platformní tým udržuje sdílené artefakty stabilní a používá zkontrolované konfigurační soubory pro přepsání hodnot, jako jsou adresy URL back-endu, ID prostředků a reference na tajné údaje. Tým nejprve nasazuje změnu do neprodukčního prostředí a teprve poté do produkčního a zabraňuje tomu, aby do stejného cíle zapisovala současně více než jedna pipeline.

Note

Konfigurace podporuje přepsání podřízených položek pracovního prostoru, ale při publikování je neuplatní. Publikace uplatní přepsání pouze na samotný kontejner pracovního prostoru. Nespoléhejte na přepsání podřízených prostředků pracovního prostoru při povyšování rozhraní API pracovního prostoru specifických pro dané prostředí, backendů, pojmenovaných hodnot nebo jiných podřízených prostředků. Ověřte alternativní způsob propagace těchto prostředků nebo propagaci odložte, dokud nebude vyřešen známý problém Vlastnosti přepsání s rozsahem pracovního prostoru se nepoužijí.
Ověřte a odsouhlaste po nasazení. Po publikování provozní tým spustí automatizované smoke testy a regresní testy, monitoruje stav služby API Management a back-endu a porovná nasazený výsledek se schváleným commitem. Tým prozkoumá a vyřeší neočekávané změny prostřednictvím žádostí o přijetí změn, a ne úpravou produkčního prostředí přímo.

Pokud operátor rozhraní API provede schválenou změnu tísňového volání přímo ve službě API Management, musí spustit extrakci v pokladně Gitu, zkontrolovat a potvrdit změnu artefaktu ve své větvi, odeslat větev a otevřít žádost o přijetí změn. Požadovaní vlastníci nebo recenzenti musí požadavek na přijetí změn zkontrolovat a schválit a autorizovaný správce úložiště jej musí sloučit, aby úložiště zůstalo směrodatným zdrojem.

Komponenty

API Management je spravovaná služba, která vytváří konzistentní brány rozhraní API pro back-endové služby. V této architektuře poskytuje zdrojové konfigurace, které rozhraní APIOps CLI extrahuje, a cílové prostředí, kde rozhraní příkazového řádku publikuje schválené definice rozhraní API, zásady, produkty, diagnostiku, pojmenované hodnoty a další podporovanou konfiguraci.
APIOps CLI je open-source projekt, který poskytuje sadu nástrojů pro předem definovaný přístup k APIOps. V této architektuře extrahuje konfiguraci služby API Management do souborů artefaktů, publikuje artefakty do služby API Management a dokáže vygenerovat pracovní postupy CI/CD.
Úložiště Git ukládá artefakty služby API Management a tam, kde je to možné, kontrakty rozhraní API. Poskytuje historii revizí a schválený, jediný spolehlivý zdroj informací pro nasazování pipeline.
Systém CI/CD spouští ověřování, extrakci a publikování pomocí identity úlohy nebo jiných podporovaných neinteraktivních přihlašovacích údajů. V této architektuře GitHub Actions nebo Azure Pipelines definují pracovní postupy CI/CD.

Alternativy

Tuto architekturu můžete nahradit nebo rozšířit o jiné služby nebo přístupy Azure v závislosti na funkčních a nefunkčních požadavcích vaší úlohy. Zvažte následující alternativy a kompromisy.

Bicep nebo Terraform a APIOps můžou obsluhovat různé části stejného řešení. Tým, který vlastní konfiguraci služby API Management i infrastrukturu, může ke zřízení služby API Management a její podpůrné infrastruktury použít infrastrukturu jako kód (IaC) a ke správě konfigurace služby API Management použít stejný kanál IaC. Tento přístup zvolte, když se infrastruktura a konfigurace změní a nasadí společně a kdy parametry můžou vyjádřit rozdíly mezi prostředími.

Model APIOps použijte, když definice rozhraní API, zásady a související konfigurace mají samostatné vlastníky nebo životní cyklus vydaných verzí, který je nezávislý na infrastruktuře služby. ApiOps je také vhodné v případě, že potřebujete extrahovat existující konfiguraci, zkontrolovat artefakty zaměřené na rozhraní API nebo zvýšit úroveň stejné schválené konfigurace napříč několika prostředími nebo instancemi služby API Management. Častější změny rozhraní API a zásad nebo více prostředí zvyšují hodnotu tohoto vyhrazeného pracovního postupu.

Tyto faktory nemají pevné prahové hodnoty. Rozhodnutí založte především na vlastnictví, požadavcích na kontrolu a hranicích nasazení. Pro menší prostředí API s nízkou mírou změn začněte s ručním pracovním postupem založeným na pull requestech a harmonogramy extrakce nebo automatizaci nasazení přidejte až poté, co bude stanoven základní stav repozitáře a proces schvalování.

Podrobnosti scénáře

APIOps používá ke správě rozhraní API správu verzí a vytvoření záznamu auditu změn definic, zásad, produktů, diagnostiky a další konfigurace služby API Management. Kontrola změn dříve a častěji pomáhá týmům identifikovat odchylky od standardů rozhraní API před nasazením. Jak bude stále více rozhraní API používat stejný proces, týmy mohou zlepšit konzistenci v celém svém API portfoliu.

Tento pracovní postup nasadí konfiguraci služby API Management do instance služby API Management. Nenasazuje back-endy rozhraní API, výpočetní prostředky aplikací nebo datové prostředky, sítě ani infrastrukturu služby API Management. K nasazení těchto vrstev použijte samostatné řízené kanály IaC a aplikací.

Toto řešení pomáhá týmům:

Udržujte přehled prostředí a instancí služby API Management.
Sledujte důležité změny rozhraní API a zásad.
Vytvořte auditní stopu o schválených nasazeních.
Odsouhlaste schválené změny, které pocházejí mimo úložiště.

Volba zdrojů artefaktů a vlastnictví

Vyberte z následujících možností, jak se artefakty dostávají do úložiště a komu patří před automatizací nasazování:

Nejdříve extrahujte: Extrahujte ověřenou instanci služby API Management k vytvoření počátečního referenčního stavu artefaktů. Než začnete považovat repozitář za zdroj pravdy, zkontrolujte vygenerované artefakty zařazené do repozitáře.
První kód: Ponechte kontrakt rozhraní API, například popis OpenAPI, se zdrojem aplikace nebo úložištěm APIOps. Definujte, kdo tento kontrakt transformuje do artefaktů API Managementu, které publikuje pipeline. Ověřte zamýšlený pracovní postup importu a artefaktu pomocí neprodukční instance služby API Management. Nepředpokládejte, že libovolnou strukturu zdrojových souborů lze přímo použít v CLI.
Sdílená odpovědnost: Určete, jestli vývojáři rozhraní API, operátoři platformy nebo obě vlastní změny zásad, produktů, diagnostiky, pojmenovaných hodnot a definic rozhraní API. Po přijetí výchozího stavu veďte všechny změny prostřednictvím stejného úložiště a procesu schvalování.

Potenciální případy použití

Organizace, které vyvíjejí a spravují rozhraní API, včetně organizací s jedním rozhraním API vystaveným prostřednictvím služby API Management.
Vysoce regulovaný sektor, jako je pojištění, bankovnictví, finance a vláda, které potřebují sledovatelné záznamy kontroly a nasazení.

Úvahy

Tyto aspekty implementují pilíře architektury Azure Well-Architected, což je sada hlavních principů, které můžete použít ke zlepšení kvality úlohy. Další informace najdete v tématu Well-Architected Framework.

Reliability

Spolehlivost pomáhá zajistit, aby vaše aplikace splňovala závazky, které jste pro své zákazníky udělali. Další informace najdete v kontrolním seznamu pro kontrolu návrhu pro spolehlivost.

V případě změn rozhraní API, které nenarušují kompatibilitu, použijte revize služby API Management k nasazení a otestování revize, která ještě není aktuální, předtím než ji nastavíte jako aktuální. Pokud se ověření po vydání nezdaří, obnovte předchozí revizi jako aktuální. K zásadním změnám kontraktů použijte verze rozhraní API, aby stávající uživatelé mohli starší verzi dál používat.

Koordinuje změny konfigurace služby API Management se strategií nasazení pro každý back-end rozhraní API. Vrácení potvrzení APIOps obnoví pouze konfiguraci reprezentovanou tímto potvrzením. Neobnoví nekompatibilní nebo nedostupný back-end. Poznamenejte si potvrzení APIOps, revizi služby API Management a back-endovou verzi, která tvoří každé známé dobré nasazení. Otestujte kompletní postup obnovení v neprodukčním prostředí, včetně zásad, pojmenovaných hodnot, odkazů na tajné údaje, závislostí a kompatibility backendu.

Zabezpečení

Zabezpečení poskytuje záruky proti záměrným útokům a zneužití cenných dat a systémů. Další informace najdete v kontrolním seznamu pro kontrolu návrhu zabezpečení.

Jako standardní způsob provádění změn v API Managementu používejte úložiště a pipeline. Vývojáři a operátoři nepotřebují trvalý přístup k zápisu do produkčních instancí služby API Management. Udělte zvýšený přístup pouze v případě potřeby a pouze po omezenou dobu. Odsouhlaste všechny výsledné změny úložiště.

K ochraně úložiště Git, které ukládá artefakty služby API Management, použijte následující mechanismy:

Revize žádosti o přijetí změn: Chraňte větve, které slouží k nasazení konfigurace a vyžadují revizi od příslušných recenzentů.
Izolace přihlašovacích údajů: Pokud je k dispozici, upřednostněte federovanou identitu úloh. Ukládejte tajné údaje specifické pro dané prostředí do schváleného úložiště tajných údajů nebo do prostředí repozitáře, nikoli do artefaktů nebo souborů kanálu.
Integrita potvrzení: Vyžadování podepsaných potvrzení k ověření provenance potvrzení. Nakonfigurujte ochranu větví tak, aby se zabránilo vynucenému pushování a odstranění větví, vyžadujte vícefaktorové ověřování pro uživatele schvalující nebo slučující změny a zachovejte historii commitů a pull requestů pro nasazení.
Kontrola artefaktů: Zkontrolujte výstup extrakce a publikujte vstupy pro tajné kódy, redactované značky a nezamýšlené hodnoty specifické pro prostředí. Ověřte, že změna nerozšíruje přístup k rozhraní API ani neoslabuje zásady.

Správa rozhraní příkazového řádku APIOps jako závislosti úložiště Připnout @azure-tools/apiops-cli v package.json na otestovanou verzi, potvrdit soubor zámku a použít npm ci. Před povolením produkčního kanálu zkontrolujte vygenerovaná nastavení identity, proměnné, triggery a pravidla ochrany.

Optimalizace nákladů

Optimalizace nákladů se zaměřuje na způsoby, jak snížit zbytečné výdaje a zlepšit efektivitu provozu. Další informace najdete v kontrolním seznamu pro kontrolu návrhu pro optimalizaci nákladů.

APIOps CLI je software s otevřeným zdrojovým kódem, ale s tímto scénářem jsou spojeny náklady na instance API Management a vybranou platformu pro správu zdrojového kódu a CI/CD. Jeden pevný odhad není k dispozici, protože ceny služby API Management se liší podle oblasti, úrovně, počtu jednotek, modelu kapacity, konfigurace zóny dostupnosti nebo více oblastí a využití. Poplatky za CI/CD také závisí na typu spouštěče, zahrnutém počtu minut, souběžnosti, úložišti a době uchovávání.

Vytvořte odhad specifický pro scénář v cenové kalkulačce Azure a pomocí rozhodnutí o architektuře si poznamenejte následující předpoklady:

Odhadovaný vstup	Předpoklad záznamu
Oblast služby API Management	Region nasazení pro každou vývojovou, testovací, přípravnou a produkční instanci.
Úroveň a kapacita	Úroveň nebo úroveň v2, počet jednotek nebo bran a provozní hodiny pro každé prostředí.
Resiliency	Jakékoli nasazení v zóně dostupnosti nebo v dalším regionu, včetně jednotek v každém umístění.
Poplatky na základě využití	Očekávané požadavky nebo operace a veškeré související poplatky za pracovní prostory, samostatně hostovanou bránu, síťové služby, monitorování nebo přenos dat.
Platforma CI/CD	Agenti hostovaní na GitHubu, hostovaní místně nebo agenti Azure Pipelines. Očekávané spuštění kanálu, doba trvání, souběžnost, úložiště a uchovávání protokolů nebo artefaktů
Správa zdrojového kódu a licence	Počet uživatelů a všech placených funkcí plánu GitHub nebo Azure DevOps.

Pomocí aktuálních podrobností o cenách služby API Management vyberte příslušný fakturační model. Informace o předpokladech pro CI/CD a správu verzí viz Ceny Azure DevOps a Ceny GitHubu. Exportujte nebo zachyťte odhad kalkulačky, jeho měnu, datum ceny a všechny předpoklady, aby je revidující mohli reprodukovat a aktualizovat. Přepočítejte před nasazením a když se změní oblasti, úrovně, počty jednotek, prostředí nebo změna využití kanálu.

Efektivita provozu

Efektivita provozu se zabývá provozními procesy, které nasazují aplikaci a udržují ji spuštěnou v produkčním prostředí. Další informace najdete v kontrolním seznamu pro kontrolu návrhu pro efektivitu provozu.

Rozhraní APIOps umožňuje nasazení opakovat a vytvoří historii potvrzení pro analýzu po změně. Označte nebo jinak zaznamenejte commit, který je nasazen do každého prostředí, uchovávejte protokoly pipeline a po nasazení monitorujte instanci služby API Management a závislá rozhraní API.

U více prostředí propagujte stejné zkontrolované potvrzení artefaktů prostřednictvím vývoje, přípravy a produkce. Přepsání pro jednotlivá prostředí používejte pouze pro hodnoty, které se v jednotlivých prostředích musí lišit, a tyto soubory kontrolujte se stejnou pečlivostí jako artefakty. Přepsání podřízeného pracovního prostoru se při publikování neuplatní, proto je nepoužívejte k povýšení do jiného prostředí. Před výskytem incidentu otestujte postupy vrácení zpět. Vrácení Gitu stále vyžaduje ověření a řízené publikování pro obnovení služby API Management.

CLI poskytuje příkazy init, extract a publish a může vytvářet GitHub Actions nebo Azure DevOps pipeliney. Podrobné informace o příkazu najdete v dokumentaci k rozhraní příkazového řádku APIOps.

Bezpečně migrovat ze starší sady nástrojů APIOps

Pokud váš proces APIOps používá starší sadu nástrojů APIOps, naplánujte upgrade. Tento přístup používá samostatné binární soubory Extractor a Publisher a šablony kanálů zpracování. APIOps CLI používá jediný nástroj příkazového řádku v Node.js, ale jeho formát artefaktů je navržen tak, aby byl kompatibilní s artefakty stávající sady nástrojů. Považujte migraci za řízené přepnutí, nikoli za aktualizaci produkčního prostředí na místě.

Označte ověřené artefakty sady nástrojů a pipeline a zachovejte stávající publikační profil pro případ vrácení změn. V rámci jednoho nasazení neměňte stávajícího vydavatele a nezavádějte nového vydavatele.
Ve větvi migrace použijte nejnovější verzi rozhraní příkazového řádku APIOps a spusťte apiops init ji bez použití --force. Příkaz zjistí konfliktní soubory a ukončí je a nepřepíše je. Porovnejte a záměrně integrujte vygenerované pipeliney, pokyny pro práci s identitou, filtry a přepisovací soubory.
Použijte artefakty s apiops publish --dry-run a přepsáními pro cílové prostředí vůči neprodukční instanci služby API Management. Zkontrolujte prostředky, které rozhraní příkazového řádku vytvoří, aktualizuje nebo odstraní. Otestujte jedno řízené publikování a ověřte nasazená rozhraní API, zásady, pojmenované hodnoty a závislosti.
Nepoužívejte přepsání podřízených položek pracovního prostoru, která se při publikování neuplatňují, jako součást návrhu migrace nebo nasazení. Ověřte alternativní způsob propagace pro dotčené podřízené prostředky nebo odložte jejich migraci, dokud nebude vyřešen známý problém Vlastnosti přepsání s rozsahem pracovního prostoru se nepoužijí.
Při přepnutí povolte pouze jednomu vydavateli zapisovat do instance služby API Management. Před povolením vydavatele CLI zakažte aktivační prvek staršího vydavatele. Nasaďte zkontrolovaný commit a sledujte výsledek. Ponechte označený kanál sady Nástrojů a směrný plán artefaktů, dokud nový pracovní postup neskonží úspěšný cyklus vydání.

Podrobnosti o kompatibilitě a příklady migrace příkazů podle příkazů najdete v tématu Migrace ze sady APIOps Toolkit.

Nasazení tohoto scénáře

Postupujte podle dokumentace k rozhraní příkazového řádku APIOps v úložišti rozhraní příkazového řádku APIOps GitHub. Začněte s neprodukční instancí API Managementu a použijte pokyny pro aktuální vydání nástroje APIOps CLI. Pokud chcete začít s neprodukčním prostředím, přečtěte si téma Správa konfigurace služby API Management pomocí rozhraní APIOps CLI.

Přispěvatelé

Microsoft udržuje tento článek. Tento článek napsali následující přispěvatelé.

Hlavní autoři:

Pat Altimore | Vedoucí vývojář obsahu
Wael Kdouh | Hlavní architekt řešení
Rishabh Saha | Hlavní architekt řešení

Pokud chcete zobrazit nepublikované profily LinkedIn, přihlaste se k LinkedIn.

Další kroky

Váš názor

Byla tato stránka užitečná?