Automatizzare la configurazione di Gestione API usando l'interfaccia della riga di comando di APIOps

Gestione API di Azure

Azure DevOps

Azure Pipelines

GitHub

APIOps è una metodologia che applica i concetti di GitOps e DevOps alla distribuzione api. Questa architettura illustra come usare APIOps CLI per estrarre, esaminare e promuovere la configurazione di Gestione API di Azure tramite un flusso di lavoro basato su Git. Usare questo approccio per gestire il ciclo di vita dell'API, migliorare la qualità delle API e mantenere un record controllabile delle modifiche approvate.

Architettura

Il diagramma seguente illustra il flusso di promozione della configurazione della CLI APIOps ad alto livello. I team esaminano gli artefatti di gestione delle API in Git e quindi le pipeline di integrazione continua e distribuzione continua (CI/CD) promuovono la configurazione approvata verso gli ambienti di destinazione di gestione delle API.

Il diagramma include tre sezioni da sinistra a destra. A sinistra, l'input alternativo A usa un flusso di lavoro che prevede prima l'estrazione ed esegue `apiops extract` su una configurazione API Management di origine esistente. L'input alternativo B usa la creazione in modalità code-first degli artefatti di API Management compatibili con la CLI: file JSON di informazioni, file XML dei criteri e specifiche API. Entrambi gli input puntano al repository Git nel centro, dove il passaggio 1 crea una modifica di configurazione in un ramo, il passaggio 2 esamina e convalida la richiesta pull e il passaggio 3 approva l'input di distribuzione non modificabile come commit approvato. Una freccia conduce dal passaggio 3 al flusso di lavoro CI/CD nella sezione Distribuzione controllata a destra. Il flusso di lavoro CI/CD visualizza l'anteprima dell'input approvato nel passaggio 4 eseguendo "apiops publish --dry-run", lo pubblica e lo promuove nel passaggio 5 eseguendo "apiops publish" e convalida e riconcilia gli ambienti di Gestione API di destinazione nel passaggio 6.

Scaricare un file Visio di questa architettura.

Flusso di lavoro

La configurazione di Gestione API inizia estraendo una configurazione di Gestione API esistente o creando artefatti di Gestione API compatibili con l'interfaccia della riga di comando. Il flusso di lavoro operativo inizia con uno di questi input di artefatti. Entrambi i percorsi portano allo stesso processo di pull request, convalida, approvazione e distribuzione:

• (A) Extract-first: un operatore API esegue apiops extract su un'istanza di API Management esistente per creare i file degli artefatti di API Management nel ramo locale del checkout Git. L'operatore usa questi artefatti per proporre una linea di base o acquisire una modifica di configurazione approvata.

• (B) Code-first: Uno sviluppatore API redige o aggiorna specifiche API compatibili con APIOps CLI, file informativi, criteri e artefatti correlati di API Management nel ramo di checkout Git locale.

Usare il ciclo di vita seguente per uno degli input:

1. Creare una modifica alla configurazione. Dopo il check-in iniziale dell'estrazione o della creazione degli artefatti in modalità code-first, il repository di configurazione dell'API diventa la fonte autorevole per gli artefatti di configurazione di API Management. Il repository gestisce la cronologia delle versioni e il record di controllo per ogni distribuzione. Per apportare una modifica, un operatore API o uno sviluppatore crea un ramo dal ramo protetto nel repository di configurazione api e apporta una modifica logica correlata all'API.

2. Esaminare e convalidare la modifica. L'operatore o lo sviluppatore apre una pull request per unire il proprio ramo a un ramo protetto. I proprietari e i revisori necessari del contratto API, dei criteri e della configurazione di Gestione API esaminano la richiesta pull. Il sistema CI/CD esegue i controlli e i test seguenti:

   • Linting delle specifiche API
   • Rilevamento delle modifiche incompatibili rispetto al contratto approvato
   • Analisi della sicurezza delle specifiche e del contenuto del repository
   • Test API che verificano il comportamento previsto, l'autenticazione, gli effetti dei criteri e le dipendenze del back-end

   Questi controlli non richiedono strumenti Microsoft. Il team usa qualsiasi strumento adatto per soddisfare i requisiti di supporto, sicurezza e licenza dell'organizzazione.

3. Approvare l'input di distribuzione non modificabile. I responsabili o i revisori richiesti approvano la pull request e un responsabile autorizzato del repository integra le modifiche dopo che tutti i controlli e le revisioni richiesti sono stati superati. Il commit immutabile sottoposto a merge e i relativi artefatti del ramo protetto diventano la fonte di verità verificabile del repository.

   Il team protegge i rami di repository protetti da push diretti, richiede approvazioni dell'ambiente o della connessione al servizio per le destinazioni sensibili e usa identità con privilegi minimi separati per l'estrazione e la pubblicazione. Registrano il commit approvato con la relativa pull request, le revisioni e i risultati della convalida a fini di audit.

4. Visualizzare l'anteprima della distribuzione. La pipeline CI/CD esegue apiops publish --dry-run per il commit approvato usando la stessa destinazione e lo stesso file di override senza pubblicazione. Il responsabile dell'approvazione della release esamina le risorse che la simulazione crea, aggiorna, elimina o ignora. Il team considera una prova a secco riuscita come criterio di autorizzazione alla distribuzione, non come sostituto dei test automatici delle API.

5. Pubblicare e promuovere. Dopo che l'esecuzione secca supera la convalida, la pipeline CI/CD usa apiops publish per pubblicare lo stesso commit esaminato. Per ambienti multipli, il team della piattaforma mantiene stabili gli artefatti condivisi e utilizza file di configurazione di override revisionati per valori quali gli URL di back-end, gli ID delle risorse e i riferimenti ai segreti. Il team promuove il commit attraverso gli ambienti non di produzione prima di quello di produzione e impedisce che più di una pipeline scriva nello stesso target contemporaneamente.

   Note

   La configurazione accetta gli override figlio del workspace, ma non li applica quando pubblichi. La pubblicazione applica le sovrascritture solo al contenitore stesso dell'area di lavoro. Non fare affidamento sugli override delle risorse figlio dell'area di lavoro per portare API dell'area di lavoro specifiche per l'ambiente, backend, valori denominati o altre risorse figlio. Verificare un approccio di promozione alternativo per tali risorse o rinviare la promozione finché il problema noto Proprietà di override con ambito dell'area di lavoro non applicate non sarà risolto.

6. Convalidare e riconciliare dopo la distribuzione. Dopo la pubblicazione, il team operativo esegue test automatizzati di fumo e regressione, monitora l'integrità di Gestione API e back-end e confronta il risultato distribuito con il commit approvato. Il team esamina e risolve modifiche impreviste tramite richieste pull anziché modificare direttamente la produzione.

   Se un operatore API apporta una modifica di emergenza approvata direttamente in API Management, deve eseguire l’estrazione in un checkout Git, esaminare ed eseguire il commit della modifica dell’artefatto nel proprio ramo, eseguire il push del ramo e aprire una pull request. I responsabili o i revisori necessari devono esaminare e approvare la pull request, e un responsabile autorizzato del repository deve integrarla affinché il repository rimanga una fonte autorevole.

Componenti

• Gestione API è un servizio gestito che crea gateway API coerenti per i servizi back-end. In questa architettura fornisce le configurazioni di origine estratte dall'interfaccia della riga di comando di APIOps e gli ambienti di destinazione in cui l'interfaccia della riga di comando pubblica definizioni api approvate, criteri, prodotti, diagnostica, valori denominati e altre configurazioni supportate.

• APIOps CLI è un progetto open source che fornisce strumenti per un approccio APIOps basato su convenzioni precise. In questa architettura estrae la configurazione di Gestione API nei file degli artefatti, pubblica gli artefatti in Gestione API e può eseguire lo scaffolding dei flussi di lavoro CI/CD.

• Un repository Git archivia gli artefatti di Gestione API e, ove applicabile, i contratti API. Fornisce la cronologia delle revisioni e l'origine di verità approvata per le distribuzioni di pipeline.

• Un sistema CI/CD esegue la convalida, l'estrazione e la pubblicazione tramite un'identità del carico di lavoro o un'altra credenziale non interattiva supportata. In questa architettura, GitHub Actions o Azure Pipelines definiscono i flussi di lavoro CI/CD.

Alternative

È possibile sostituire o aumentare questa architettura con altri Azure servizi o approcci, a seconda dei requisiti funzionali e non funzionali del carico di lavoro. Prendere in considerazione le alternative e i compromessi seguenti.

Bicep o Terraform e APIOps possono gestire parti diverse della stessa soluzione. Un team proprietario sia della configurazione di Gestione API che dell'infrastruttura può usare l'infrastruttura come codice (IaC) per effettuare il provisioning del servizio Gestione API e dell'infrastruttura di supporto e usare la stessa pipeline IaC per gestire la configurazione di Gestione API. Scegliere questo approccio quando l'infrastruttura e la configurazione cambiano e si distribuiscono insieme e quando i parametri possono esprimere le differenze tra gli ambienti.

Usare il modello APIOps quando le definizioni api, i criteri e la configurazione correlata hanno proprietari separati o un ciclo di vita di versione indipendente dall'infrastruttura del servizio. APIOps è anche appropriato quando è necessario estrarre la configurazione esistente, esaminare gli artefatti incentrati sulle API o promuovere la stessa configurazione approvata in più ambienti o istanze di Gestione API. Le modifiche di API e criteri più frequenti o più ambienti aumentano il valore di questo flusso di lavoro dedicato.

Questi fattori non hanno soglie fisse. Basare la decisione principalmente sulla proprietà, rivedere i requisiti e i limiti di distribuzione. Per un'API più piccola con una bassa frequenza di modifica, iniziare con un flusso di lavoro di richiesta pull manuale e aggiungere pianificazioni di estrazione o automazione della distribuzione solo dopo la definizione della baseline del repository e del processo di approvazione.

Dettagli dello scenario

APIOps usa il controllo della versione per gestire le API e creare un audit trail delle modifiche apportate a definizioni API, criteri, prodotti, diagnostica e altre configurazioni di Gestione API. La revisione delle modifiche in precedenza e più spesso aiuta i team a identificare le deviazioni dagli standard API prima della distribuzione. Man mano che più API usano lo stesso processo, i team possono migliorare la coerenza nel proprio patrimonio API.

Questo flusso di lavoro distribuisce la configurazione di Gestione API in un'istanza di Gestione API. Non distribuisce back-end API, risorse di calcolo delle applicazioni o dati, rete o infrastruttura del servizio Gestione API. Usare pipeline di applicazioni e IaC regolamentate separate per distribuire tali livelli.

Questa soluzione consente ai team di:

• Gestire una panoramica degli ambienti e delle istanze di Gestione API.
• Tenere traccia delle modifiche critiche alle API e ai criteri.
• Creare una traccia di controllo per le distribuzioni approvate.
• Riconciliare le modifiche approvate che hanno origine all'esterno del repository.

Scegliere origini e proprietà degli artefatti

Scegli tra le seguenti modalità con cui gli artefatti entrano nel repository e chi ne è il proprietario prima di automatizzare la distribuzione:

• Extract-first: Estrarre un'istanza di API Management nota come valida per stabilire la base di riferimento iniziale degli artefatti. Esaminare gli artefatti generati sottoposti a check-in prima di considerare il repository come fonte autorevole.
• Code-first: Mantenere il contratto API, ad esempio una descrizione OpenAPI, con l'origine dell'applicazione o il repository APIOps. Definire chi trasforma il contratto negli artefatti di Gestione API pubblicati dalla pipeline. Convalidare il flusso di lavoro di importazione e artefatto previsto con un'istanza di Gestione API non di produzione. Non presupporre che un layout di origine arbitrario sia direttamente utilizzabile dall'interfaccia della riga di comando.
• Responsabilità condivisa: Stabilire se gli sviluppatori di API, gli operatori della piattaforma o entrambi siano responsabili delle modifiche ai criteri, ai prodotti, alla diagnostica, ai valori denominati e alle definizioni delle API. Dopo l'approvazione della baseline, far passare ogni modifica attraverso lo stesso repository e lo stesso processo di revisione.

Potenziali casi d'uso

• Organizzazioni che sviluppano e gestiscono API, incluse le organizzazioni con una singola API esposta tramite Gestione API.

• Settori altamente regolamentati, ad esempio assicurazioni, banche, finanze e enti pubblici che necessitano di revisioni e record di distribuzione tracciabili.

Considerazioni

Queste considerazioni implementano i pilastri di Azure Well-Architected Framework, che è un set di set di principi guida che è possibile usare per migliorare la qualità di un carico di lavoro. Per altre informazioni, vedere Well-Architected Framework.

Reliability

L'affidabilità garantisce che l'applicazione possa soddisfare gli impegni assunti dai clienti. Per maggiori informazioni, consultare la sezione Elenco di controllo per la revisione della progettazione per l'affidabilità.

Per le modifiche all'API senza interruzioni di compatibilità, usa le revisioni di API Management per distribuire e testare una revisione non corrente prima di renderla corrente. Se la validazione fallisce dopo il rilascio, ripristinare la revisione precedente come revisione corrente. Usare le versioni dell'API per le modifiche incompatibili del contratto, affinché i client esistenti possano continuare a usare la versione precedente.

Coordinare le modifiche alla configurazione di Gestione API con la strategia di distribuzione per ogni back-end API. Il ripristino di un commit APIOps ripristina solo la configurazione rappresentata da tale commit. Non ripristina un back-end incompatibile o non disponibile. Registra il commit di APIOps, la revisione di API Management e la release del back-end che costituiscono ogni distribuzione nota come valida. Testare la procedura di rollback completa in un ambiente non di produzione, inclusi criteri, valori denominati, riferimenti segreti, dipendenze e compatibilità back-end.

Sicurezza

La sicurezza offre garanzie contro attacchi intenzionali e l'uso improprio di dati e sistemi preziosi. Per altre informazioni, vedere Elenco di controllo per la revisione della progettazione per la sicurezza.

Usare il repository e la pipeline come percorso normale per l'applicazione delle modifiche di Gestione API. Gli sviluppatori e gli operatori non necessitano dell'accesso in scrittura permanente alle istanze di Gestione API di produzione. Concedere l'accesso con privilegi elevati solo quando necessario e solo per un periodo di tempo limitato. Riconcilia eventuali modifiche risultanti nel repository.

Usare i meccanismi seguenti per proteggere il repository Git che archivia gli artefatti di Gestione API:

• Revisione della richiesta pull: Proteggere i rami che distribuiscono la configurazione e richiedono la revisione da parte dei revisori appropriati.
• Isolamento delle credenziali: Preferisci l'identità federata del carico di lavoro, se disponibile. Archiviare segreti specifici dell'ambiente in un archivio segreto o in un ambiente del repository approvato, non in artefatti o file di pipeline.
• Integrità del commit: Richiedi commit firmati per verificarne la provenienza. Configurare le protezioni dei rami per impedire l'eliminazione forzata dei push e dei rami, richiedere l'autenticazione a più fattori per consentire agli utenti di approvare o unire le modifiche e mantenere la cronologia delle richieste pull e commit per le distribuzioni.
• Revisione dell'artefatto: Esaminate l'output di estrazione e gli input di pubblicazione per individuare segreti, marcatori di redazione e valori specifici dell'ambiente indesiderati. Verificare che una modifica non ampli l'accesso all'API o indebolisca un criterio.

Gestisci la CLI di APIOps come dipendenza del repository. Aggiungere @azure-tools/apiops-cli in package.json a una versione testata, eseguire il commit del file di blocco e usare npm ci. Esaminare le impostazioni di identità generate, le variabili, i trigger e le regole di protezione prima di abilitare una pipeline di produzione.

Ottimizzazione dei costi

L'ottimizzazione dei costi è incentrata sui modi per ridurre le spese non necessarie e migliorare l'efficienza operativa. Per altre informazioni, vedere Elenco di controllo per la revisione della progettazione per Ottimizzazione costi.

L'interfaccia della riga di comando di APIOps è un software open source, ma questo scenario comporta costi per le istanze di Gestione API e la piattaforma CI/CD selezionata. Una singola stima fissa non viene fornita perché i prezzi di Gestione API variano in base all'area, al livello, al numero di unità, al modello di capacità, alla configurazione della zona di disponibilità o a più aree e all'utilizzo. Anche i costi di CI/CD dipendono dal tipo di runner, dai minuti inclusi, dal parallelismo, dall'archiviazione e dal periodo di conservazione.

Creare una stima specifica dello scenario nel calcolatore prezzi Azure e registrare i presupposti seguenti con la decisione sull'architettura:

Stimare l'input	Assunzione da registrare
Area di Gestione API	Area di distribuzione per ogni istanza di sviluppo, test, gestione temporanea e produzione.
Livello e capacità	Il livello o il livello v2, il numero di unità o i gateway e le ore operative per ogni ambiente.
Resiliency	Qualsiasi distribuzione della zona di disponibilità o di un'area aggiuntiva, incluse le unità in ogni località.
Addebiti basati sull'utilizzo	Richieste o operazioni previste ed eventuali costi relativi all'area di lavoro, al gateway self-hosted, alla connettività, al monitoraggio o al trasferimento dei dati.
Piattaforma CI/CD	agenti ospitati da GitHub, ospitati autonomamente o di Azure Pipelines. Esecuzioni previste della pipeline, durata, concorrenza, spazio di archiviazione e conservazione di log o artefatti.
Controllo del codice sorgente e licenze	Numero di utenti e qualsiasi GitHub a pagamento o funzionalità del piano di Azure DevOps.

Usare i dettagli dei prezzi correnti di Gestione API per selezionare il modello di fatturazione applicabile. Per i presupposti relativi a CI/CD e controllo del codice sorgente, vedere prezzi Azure DevOps e prezzi GitHub. Esportare o acquisire la stima del calcolatore, la valuta, la data dei prezzi e tutti i presupposti, in modo che i revisori possano riprodurlo e aggiornarlo. Ricalcola prima della distribuzione e quando cambiano regioni, livelli, numero di unità, ambienti o utilizzo della pipeline.

Eccellenza operativa

L'eccellenza operativa copre i processi operativi che distribuiscono un'applicazione e lo mantengono in esecuzione nell'ambiente di produzione. Per altre informazioni, vedere Elenco di controllo per la revisione della progettazione per l'eccellenza operativa.

APIOps rende ripetibili le distribuzioni e crea una cronologia di commit per l'analisi post-modifica. Contrassegna o registra in altro modo il commit ricevuto da ogni ambiente, conserva i log della pipeline e monitora l'istanza di Gestione API e le API dipendenti dopo la distribuzione.

Per ambienti multipli, promuovi lo stesso commit dell'artefatto revisionato attraverso sviluppo, staging e produzione. Usare gli override di ambiente solo per i valori che devono differire da un ambiente all'altro e rivedere tali file con la stessa attenzione riservata agli artefatti. Le override figlie dell'area di lavoro non vengono applicate al momento della pubblicazione, quindi non usarle per la promozione tra ambienti. Testare le procedure di rollback prima che si verifichi un evento imprevisto. Un revert in Git richiede comunque una convalida e una pubblicazione controllata per ripristinare API Management.

La CLI fornisce i comandi init, extract e publish e può generare la struttura di GitHub Actions o delle pipeline di Azure DevOps. Consulta i dettagli del comando nella documentazione di APIOps CLI.

Eseguire la migrazione in modo sicuro da APIOps Toolkit legacy

Se il tuo processo APIOps usa il toolkit APIOps precedente, pianifica un aggiornamento. Questo approccio utilizza file binari separati di Extractor e Publisher e modelli di pipeline. L'interfaccia della riga di comando di APIOps usa una singola interfaccia della riga di comando di Node.js, ma il formato dell'artefatto è progettato per essere compatibile con gli artefatti del toolkit esistenti. Considera la migrazione come un passaggio controllato, non come un aggiornamento eseguito direttamente nell'ambiente di produzione.

1. Contrassegnare gli artefatti e la pipeline del toolkit considerati affidabili e mantenere l'editore esistente come opzione di ripristino. Non modificare il server di pubblicazione legacy e introdurre il nuovo server di pubblicazione nella stessa distribuzione.

2. In un ramo di migrazione usare la versione più recente dell'interfaccia della riga di comando APIOps ed eseguire apiops init senza usare --force. Il comando rileva i file in conflitto e viene chiuso anziché sovrascriverli. Confronta e integra deliberatamente le pipeline generate, le linee guida per l'identità, i filtri e i file di override.

3. Usa gli artefatti con apiops publish --dry-run e le sovrascritture dell'ambiente di destinazione su un'istanza di API Management di non produzione. Rivedi le risorse che la CLI creerebbe, aggiornerebbe o eliminerebbe. Testare una pubblicazione controllata e convalidare le API distribuite, i criteri, i valori denominati e le dipendenze.

4. Non usare le sovrascritture figlio del workspace, che non vengono applicate in fase di pubblicazione, nella progettazione della migrazione o della promozione. Convalidare un approccio alternativo di promozione per le risorse figlie interessate oppure posticiparne la migrazione fino alla risoluzione del problema noto Proprietà di override con ambito Workspace non applicate.

5. In fase di cutover, consentire a un solo editore di scrivere in un'istanza di Gestione API. Disabilitare il trigger del publisher legacy prima di abilitare il publisher CLI. Distribuisci un commit revisionato e monitora il risultato. Mantenere la pipeline del toolkit con tag e la baseline dell'artefatto finché il nuovo flusso di lavoro non completa un ciclo di rilascio riuscito.

Per informazioni dettagliate sulla compatibilità ed esempi di migrazione tramite comando, vedere Migrazione da APIOps Toolkit.

Distribuire lo scenario

Segui la documentazione di APIOps CLI nel repository GitHub di APIOps CLI. Inizia con un'istanza di API Management non di produzione e usa le indicazioni correnti sulla versione di APIOps CLI. Per iniziare a usare un ambiente non di produzione, vedere Come gestire la configurazione di Gestione API con l'interfaccia della riga di comando apiOps.

Collaboratori

Microsoft gestisce questo articolo. I seguenti collaboratori hanno scritto questo articolo.

Autori principali:

• Pat Altimore | Sviluppatore di contenuti senior
• Wael Kdouh | Senior Principal Solution Architect
• Rishabh Saha | Senior Principal Solution Architect

Per visualizzare i profili LinkedIn non pubblici, accedere a LinkedIn.

Passaggi successivi

• Interfaccia della riga di comando di APIOps
• Come gestire la configurazione di Gestione API con l'interfaccia della riga di comando di APIOps
• Panoramica di GitOps

Risorse correlate

• GitOps per Servizio Azure Kubernetes (AKS)
• Eseguire la migrazione di un'app Web tramite Gestione API
• Proteggere le API usando il Gateway Applicazione di Azure e API Management

APIOps è una metodologia che applica i concetti di GitOps e DevOps alla distribuzione api. Questa architettura illustra come usare APIOps CLI per estrarre, esaminare e promuovere la configurazione di Gestione API di Azure tramite un flusso di lavoro basato su Git. Usare questo approccio per gestire il ciclo di vita dell'API, migliorare la qualità delle API e mantenere un record controllabile delle modifiche approvate.

Architettura

Il diagramma seguente illustra il flusso di promozione della configurazione della CLI APIOps ad alto livello. I team esaminano gli artefatti di gestione delle API in Git e quindi le pipeline di integrazione continua e distribuzione continua (CI/CD) promuovono la configurazione approvata verso gli ambienti di destinazione di gestione delle API.

Il diagramma include tre sezioni da sinistra a destra. A sinistra, l'input alternativo A usa un flusso di lavoro che prevede prima l'estrazione ed esegue `apiops extract` su una configurazione API Management di origine esistente. L'input alternativo B usa la creazione in modalità code-first degli artefatti di API Management compatibili con la CLI: file JSON di informazioni, file XML dei criteri e specifiche API. Entrambi gli input puntano al repository Git nel centro, dove il passaggio 1 crea una modifica di configurazione in un ramo, il passaggio 2 esamina e convalida la richiesta pull e il passaggio 3 approva l'input di distribuzione non modificabile come commit approvato. Una freccia conduce dal passaggio 3 al flusso di lavoro CI/CD nella sezione Distribuzione controllata a destra. Il flusso di lavoro CI/CD visualizza l'anteprima dell'input approvato nel passaggio 4 eseguendo "apiops publish --dry-run", lo pubblica e lo promuove nel passaggio 5 eseguendo "apiops publish" e convalida e riconcilia gli ambienti di Gestione API di destinazione nel passaggio 6.

Scaricare un file Visio di questa architettura.

Flusso di lavoro

La configurazione di Gestione API inizia estraendo una configurazione di Gestione API esistente o creando artefatti di Gestione API compatibili con l'interfaccia della riga di comando. Il flusso di lavoro operativo inizia con uno di questi input di artefatti. Entrambi i percorsi portano allo stesso processo di pull request, convalida, approvazione e distribuzione:

• (A) Extract-first: un operatore API esegue apiops extract su un'istanza di API Management esistente per creare i file degli artefatti di API Management nel ramo locale del checkout Git. L'operatore usa questi artefatti per proporre una linea di base o acquisire una modifica di configurazione approvata.

• (B) Code-first: Uno sviluppatore API redige o aggiorna specifiche API compatibili con APIOps CLI, file informativi, criteri e artefatti correlati di API Management nel ramo di checkout Git locale.

Usare il ciclo di vita seguente per uno degli input:

1. Creare una modifica alla configurazione. Dopo il check-in iniziale dell'estrazione o della creazione degli artefatti in modalità code-first, il repository di configurazione dell'API diventa la fonte autorevole per gli artefatti di configurazione di API Management. Il repository gestisce la cronologia delle versioni e il record di controllo per ogni distribuzione. Per apportare una modifica, un operatore API o uno sviluppatore crea un ramo dal ramo protetto nel repository di configurazione api e apporta una modifica logica correlata all'API.

2. Esaminare e convalidare la modifica. L'operatore o lo sviluppatore apre una pull request per unire il proprio ramo a un ramo protetto. I proprietari e i revisori necessari del contratto API, dei criteri e della configurazione di Gestione API esaminano la richiesta pull. Il sistema CI/CD esegue i controlli e i test seguenti:

   • Linting delle specifiche API
   • Rilevamento delle modifiche incompatibili rispetto al contratto approvato
   • Analisi della sicurezza delle specifiche e del contenuto del repository
   • Test API che verificano il comportamento previsto, l'autenticazione, gli effetti dei criteri e le dipendenze del back-end

   Questi controlli non richiedono strumenti Microsoft. Il team usa qualsiasi strumento adatto per soddisfare i requisiti di supporto, sicurezza e licenza dell'organizzazione.

3. Approvare l'input di distribuzione non modificabile. I responsabili o i revisori richiesti approvano la pull request e un responsabile autorizzato del repository integra le modifiche dopo che tutti i controlli e le revisioni richiesti sono stati superati. Il commit immutabile sottoposto a merge e i relativi artefatti del ramo protetto diventano la fonte di verità verificabile del repository.

   Il team protegge i rami di repository protetti da push diretti, richiede approvazioni dell'ambiente o della connessione al servizio per le destinazioni sensibili e usa identità con privilegi minimi separati per l'estrazione e la pubblicazione. Registrano il commit approvato con la relativa pull request, le revisioni e i risultati della convalida a fini di audit.

4. Visualizzare l'anteprima della distribuzione. La pipeline CI/CD esegue apiops publish --dry-run per il commit approvato usando la stessa destinazione e lo stesso file di override senza pubblicazione. Il responsabile dell'approvazione della release esamina le risorse che la simulazione crea, aggiorna, elimina o ignora. Il team considera una prova a secco riuscita come criterio di autorizzazione alla distribuzione, non come sostituto dei test automatici delle API.

5. Pubblicare e promuovere. Dopo che l'esecuzione secca supera la convalida, la pipeline CI/CD usa apiops publish per pubblicare lo stesso commit esaminato. Per ambienti multipli, il team della piattaforma mantiene stabili gli artefatti condivisi e utilizza file di configurazione di override revisionati per valori quali gli URL di back-end, gli ID delle risorse e i riferimenti ai segreti. Il team promuove il commit attraverso gli ambienti non di produzione prima di quello di produzione e impedisce che più di una pipeline scriva nello stesso target contemporaneamente.

   Note

   La configurazione accetta gli override figlio del workspace, ma non li applica quando pubblichi. La pubblicazione applica le sovrascritture solo al contenitore stesso dell'area di lavoro. Non fare affidamento sugli override delle risorse figlio dell'area di lavoro per portare API dell'area di lavoro specifiche per l'ambiente, backend, valori denominati o altre risorse figlio. Verificare un approccio di promozione alternativo per tali risorse o rinviare la promozione finché il problema noto Proprietà di override con ambito dell'area di lavoro non applicate non sarà risolto.

6. Convalidare e riconciliare dopo la distribuzione. Dopo la pubblicazione, il team operativo esegue test automatizzati di fumo e regressione, monitora l'integrità di Gestione API e back-end e confronta il risultato distribuito con il commit approvato. Il team esamina e risolve modifiche impreviste tramite richieste pull anziché modificare direttamente la produzione.

   Se un operatore API apporta una modifica di emergenza approvata direttamente in API Management, deve eseguire l’estrazione in un checkout Git, esaminare ed eseguire il commit della modifica dell’artefatto nel proprio ramo, eseguire il push del ramo e aprire una pull request. I responsabili o i revisori necessari devono esaminare e approvare la pull request, e un responsabile autorizzato del repository deve integrarla affinché il repository rimanga una fonte autorevole.

Componenti

• Gestione API è un servizio gestito che crea gateway API coerenti per i servizi back-end. In questa architettura fornisce le configurazioni di origine estratte dall'interfaccia della riga di comando di APIOps e gli ambienti di destinazione in cui l'interfaccia della riga di comando pubblica definizioni api approvate, criteri, prodotti, diagnostica, valori denominati e altre configurazioni supportate.

• APIOps CLI è un progetto open source che fornisce strumenti per un approccio APIOps basato su convenzioni precise. In questa architettura estrae la configurazione di Gestione API nei file degli artefatti, pubblica gli artefatti in Gestione API e può eseguire lo scaffolding dei flussi di lavoro CI/CD.

• Un repository Git archivia gli artefatti di Gestione API e, ove applicabile, i contratti API. Fornisce la cronologia delle revisioni e l'origine di verità approvata per le distribuzioni di pipeline.

• Un sistema CI/CD esegue la convalida, l'estrazione e la pubblicazione tramite un'identità del carico di lavoro o un'altra credenziale non interattiva supportata. In questa architettura, GitHub Actions o Azure Pipelines definiscono i flussi di lavoro CI/CD.

Alternative

È possibile sostituire o aumentare questa architettura con altri Azure servizi o approcci, a seconda dei requisiti funzionali e non funzionali del carico di lavoro. Prendere in considerazione le alternative e i compromessi seguenti.

Bicep o Terraform e APIOps possono gestire parti diverse della stessa soluzione. Un team proprietario sia della configurazione di Gestione API che dell'infrastruttura può usare l'infrastruttura come codice (IaC) per effettuare il provisioning del servizio Gestione API e dell'infrastruttura di supporto e usare la stessa pipeline IaC per gestire la configurazione di Gestione API. Scegliere questo approccio quando l'infrastruttura e la configurazione cambiano e si distribuiscono insieme e quando i parametri possono esprimere le differenze tra gli ambienti.

Usare il modello APIOps quando le definizioni api, i criteri e la configurazione correlata hanno proprietari separati o un ciclo di vita di versione indipendente dall'infrastruttura del servizio. APIOps è anche appropriato quando è necessario estrarre la configurazione esistente, esaminare gli artefatti incentrati sulle API o promuovere la stessa configurazione approvata in più ambienti o istanze di Gestione API. Le modifiche di API e criteri più frequenti o più ambienti aumentano il valore di questo flusso di lavoro dedicato.

Questi fattori non hanno soglie fisse. Basare la decisione principalmente sulla proprietà, rivedere i requisiti e i limiti di distribuzione. Per un'API più piccola con una bassa frequenza di modifica, iniziare con un flusso di lavoro di richiesta pull manuale e aggiungere pianificazioni di estrazione o automazione della distribuzione solo dopo la definizione della baseline del repository e del processo di approvazione.

Dettagli dello scenario

APIOps usa il controllo della versione per gestire le API e creare un audit trail delle modifiche apportate a definizioni API, criteri, prodotti, diagnostica e altre configurazioni di Gestione API. La revisione delle modifiche in precedenza e più spesso aiuta i team a identificare le deviazioni dagli standard API prima della distribuzione. Man mano che più API usano lo stesso processo, i team possono migliorare la coerenza nel proprio patrimonio API.

Questo flusso di lavoro distribuisce la configurazione di Gestione API in un'istanza di Gestione API. Non distribuisce back-end API, risorse di calcolo delle applicazioni o dati, rete o infrastruttura del servizio Gestione API. Usare pipeline di applicazioni e IaC regolamentate separate per distribuire tali livelli.

Questa soluzione consente ai team di:

• Gestire una panoramica degli ambienti e delle istanze di Gestione API.
• Tenere traccia delle modifiche critiche alle API e ai criteri.
• Creare una traccia di controllo per le distribuzioni approvate.
• Riconciliare le modifiche approvate che hanno origine all'esterno del repository.

Scegliere origini e proprietà degli artefatti

Scegli tra le seguenti modalità con cui gli artefatti entrano nel repository e chi ne è il proprietario prima di automatizzare la distribuzione:

• Extract-first: Estrarre un'istanza di API Management nota come valida per stabilire la base di riferimento iniziale degli artefatti. Esaminare gli artefatti generati sottoposti a check-in prima di considerare il repository come fonte autorevole.
• Code-first: Mantenere il contratto API, ad esempio una descrizione OpenAPI, con l'origine dell'applicazione o il repository APIOps. Definire chi trasforma il contratto negli artefatti di Gestione API pubblicati dalla pipeline. Convalidare il flusso di lavoro di importazione e artefatto previsto con un'istanza di Gestione API non di produzione. Non presupporre che un layout di origine arbitrario sia direttamente utilizzabile dall'interfaccia della riga di comando.
• Responsabilità condivisa: Stabilire se gli sviluppatori di API, gli operatori della piattaforma o entrambi siano responsabili delle modifiche ai criteri, ai prodotti, alla diagnostica, ai valori denominati e alle definizioni delle API. Dopo l'approvazione della baseline, far passare ogni modifica attraverso lo stesso repository e lo stesso processo di revisione.

Potenziali casi d'uso

• Organizzazioni che sviluppano e gestiscono API, incluse le organizzazioni con una singola API esposta tramite Gestione API.

• Settori altamente regolamentati, ad esempio assicurazioni, banche, finanze e enti pubblici che necessitano di revisioni e record di distribuzione tracciabili.

Considerazioni

Queste considerazioni implementano i pilastri di Azure Well-Architected Framework, che è un set di set di principi guida che è possibile usare per migliorare la qualità di un carico di lavoro. Per altre informazioni, vedere Well-Architected Framework.

Reliability

L'affidabilità garantisce che l'applicazione possa soddisfare gli impegni assunti dai clienti. Per maggiori informazioni, consultare la sezione Elenco di controllo per la revisione della progettazione per l'affidabilità.

Per le modifiche all'API senza interruzioni di compatibilità, usa le revisioni di API Management per distribuire e testare una revisione non corrente prima di renderla corrente. Se la validazione fallisce dopo il rilascio, ripristinare la revisione precedente come revisione corrente. Usare le versioni dell'API per le modifiche incompatibili del contratto, affinché i client esistenti possano continuare a usare la versione precedente.

Coordinare le modifiche alla configurazione di Gestione API con la strategia di distribuzione per ogni back-end API. Il ripristino di un commit APIOps ripristina solo la configurazione rappresentata da tale commit. Non ripristina un back-end incompatibile o non disponibile. Registra il commit di APIOps, la revisione di API Management e la release del back-end che costituiscono ogni distribuzione nota come valida. Testare la procedura di rollback completa in un ambiente non di produzione, inclusi criteri, valori denominati, riferimenti segreti, dipendenze e compatibilità back-end.

Sicurezza

La sicurezza offre garanzie contro attacchi intenzionali e l'uso improprio di dati e sistemi preziosi. Per altre informazioni, vedere Elenco di controllo per la revisione della progettazione per la sicurezza.

Usare il repository e la pipeline come percorso normale per l'applicazione delle modifiche di Gestione API. Gli sviluppatori e gli operatori non necessitano dell'accesso in scrittura permanente alle istanze di Gestione API di produzione. Concedere l'accesso con privilegi elevati solo quando necessario e solo per un periodo di tempo limitato. Riconcilia eventuali modifiche risultanti nel repository.

Usare i meccanismi seguenti per proteggere il repository Git che archivia gli artefatti di Gestione API:

• Revisione della richiesta pull: Proteggere i rami che distribuiscono la configurazione e richiedono la revisione da parte dei revisori appropriati.
• Isolamento delle credenziali: Preferisci l'identità federata del carico di lavoro, se disponibile. Archiviare segreti specifici dell'ambiente in un archivio segreto o in un ambiente del repository approvato, non in artefatti o file di pipeline.
• Integrità del commit: Richiedi commit firmati per verificarne la provenienza. Configurare le protezioni dei rami per impedire l'eliminazione forzata dei push e dei rami, richiedere l'autenticazione a più fattori per consentire agli utenti di approvare o unire le modifiche e mantenere la cronologia delle richieste pull e commit per le distribuzioni.
• Revisione dell'artefatto: Esaminate l'output di estrazione e gli input di pubblicazione per individuare segreti, marcatori di redazione e valori specifici dell'ambiente indesiderati. Verificare che una modifica non ampli l'accesso all'API o indebolisca un criterio.

Gestisci la CLI di APIOps come dipendenza del repository. Aggiungere @azure-tools/apiops-cli in package.json a una versione testata, eseguire il commit del file di blocco e usare npm ci. Esaminare le impostazioni di identità generate, le variabili, i trigger e le regole di protezione prima di abilitare una pipeline di produzione.

Ottimizzazione dei costi

L'ottimizzazione dei costi è incentrata sui modi per ridurre le spese non necessarie e migliorare l'efficienza operativa. Per altre informazioni, vedere Elenco di controllo per la revisione della progettazione per Ottimizzazione costi.

L'interfaccia della riga di comando di APIOps è un software open source, ma questo scenario comporta costi per le istanze di Gestione API e la piattaforma CI/CD selezionata. Una singola stima fissa non viene fornita perché i prezzi di Gestione API variano in base all'area, al livello, al numero di unità, al modello di capacità, alla configurazione della zona di disponibilità o a più aree e all'utilizzo. Anche i costi di CI/CD dipendono dal tipo di runner, dai minuti inclusi, dal parallelismo, dall'archiviazione e dal periodo di conservazione.

Creare una stima specifica dello scenario nel calcolatore prezzi Azure e registrare i presupposti seguenti con la decisione sull'architettura:

Stimare l'input	Assunzione da registrare
Area di Gestione API	Area di distribuzione per ogni istanza di sviluppo, test, gestione temporanea e produzione.
Livello e capacità	Il livello o il livello v2, il numero di unità o i gateway e le ore operative per ogni ambiente.
Resiliency	Qualsiasi distribuzione della zona di disponibilità o di un'area aggiuntiva, incluse le unità in ogni località.
Addebiti basati sull'utilizzo	Richieste o operazioni previste ed eventuali costi relativi all'area di lavoro, al gateway self-hosted, alla connettività, al monitoraggio o al trasferimento dei dati.
Piattaforma CI/CD	agenti ospitati da GitHub, ospitati autonomamente o di Azure Pipelines. Esecuzioni previste della pipeline, durata, concorrenza, spazio di archiviazione e conservazione di log o artefatti.
Controllo del codice sorgente e licenze	Numero di utenti e qualsiasi GitHub a pagamento o funzionalità del piano di Azure DevOps.

Usare i dettagli dei prezzi correnti di Gestione API per selezionare il modello di fatturazione applicabile. Per i presupposti relativi a CI/CD e controllo del codice sorgente, vedere prezzi Azure DevOps e prezzi GitHub. Esportare o acquisire la stima del calcolatore, la valuta, la data dei prezzi e tutti i presupposti, in modo che i revisori possano riprodurlo e aggiornarlo. Ricalcola prima della distribuzione e quando cambiano regioni, livelli, numero di unità, ambienti o utilizzo della pipeline.

Eccellenza operativa

L'eccellenza operativa copre i processi operativi che distribuiscono un'applicazione e lo mantengono in esecuzione nell'ambiente di produzione. Per altre informazioni, vedere Elenco di controllo per la revisione della progettazione per l'eccellenza operativa.

APIOps rende ripetibili le distribuzioni e crea una cronologia di commit per l'analisi post-modifica. Contrassegna o registra in altro modo il commit ricevuto da ogni ambiente, conserva i log della pipeline e monitora l'istanza di Gestione API e le API dipendenti dopo la distribuzione.

Per ambienti multipli, promuovi lo stesso commit dell'artefatto revisionato attraverso sviluppo, staging e produzione. Usare gli override di ambiente solo per i valori che devono differire da un ambiente all'altro e rivedere tali file con la stessa attenzione riservata agli artefatti. Le override figlie dell'area di lavoro non vengono applicate al momento della pubblicazione, quindi non usarle per la promozione tra ambienti. Testare le procedure di rollback prima che si verifichi un evento imprevisto. Un revert in Git richiede comunque una convalida e una pubblicazione controllata per ripristinare API Management.

La CLI fornisce i comandi init, extract e publish e può generare la struttura di GitHub Actions o delle pipeline di Azure DevOps. Consulta i dettagli del comando nella documentazione di APIOps CLI.

Eseguire la migrazione in modo sicuro da APIOps Toolkit legacy

Se il tuo processo APIOps usa il toolkit APIOps precedente, pianifica un aggiornamento. Questo approccio utilizza file binari separati di Extractor e Publisher e modelli di pipeline. L'interfaccia della riga di comando di APIOps usa una singola interfaccia della riga di comando di Node.js, ma il formato dell'artefatto è progettato per essere compatibile con gli artefatti del toolkit esistenti. Considera la migrazione come un passaggio controllato, non come un aggiornamento eseguito direttamente nell'ambiente di produzione.

1. Contrassegnare gli artefatti e la pipeline del toolkit considerati affidabili e mantenere l'editore esistente come opzione di ripristino. Non modificare il server di pubblicazione legacy e introdurre il nuovo server di pubblicazione nella stessa distribuzione.

2. In un ramo di migrazione usare la versione più recente dell'interfaccia della riga di comando APIOps ed eseguire apiops init senza usare --force. Il comando rileva i file in conflitto e viene chiuso anziché sovrascriverli. Confronta e integra deliberatamente le pipeline generate, le linee guida per l'identità, i filtri e i file di override.

3. Usa gli artefatti con apiops publish --dry-run e le sovrascritture dell'ambiente di destinazione su un'istanza di API Management di non produzione. Rivedi le risorse che la CLI creerebbe, aggiornerebbe o eliminerebbe. Testare una pubblicazione controllata e convalidare le API distribuite, i criteri, i valori denominati e le dipendenze.

4. Non usare le sovrascritture figlio del workspace, che non vengono applicate in fase di pubblicazione, nella progettazione della migrazione o della promozione. Convalidare un approccio alternativo di promozione per le risorse figlie interessate oppure posticiparne la migrazione fino alla risoluzione del problema noto Proprietà di override con ambito Workspace non applicate.

5. In fase di cutover, consentire a un solo editore di scrivere in un'istanza di Gestione API. Disabilitare il trigger del publisher legacy prima di abilitare il publisher CLI. Distribuisci un commit revisionato e monitora il risultato. Mantenere la pipeline del toolkit con tag e la baseline dell'artefatto finché il nuovo flusso di lavoro non completa un ciclo di rilascio riuscito.

Per informazioni dettagliate sulla compatibilità ed esempi di migrazione tramite comando, vedere Migrazione da APIOps Toolkit.

Distribuire lo scenario

Segui la documentazione di APIOps CLI nel repository GitHub di APIOps CLI. Inizia con un'istanza di API Management non di produzione e usa le indicazioni correnti sulla versione di APIOps CLI. Per iniziare a usare un ambiente non di produzione, vedere Come gestire la configurazione di Gestione API con l'interfaccia della riga di comando apiOps.

Collaboratori

Microsoft gestisce questo articolo. I seguenti collaboratori hanno scritto questo articolo.

Autori principali:

• Pat Altimore | Sviluppatore di contenuti senior
• Wael Kdouh | Senior Principal Solution Architect
• Rishabh Saha | Senior Principal Solution Architect

Per visualizzare i profili LinkedIn non pubblici, accedere a LinkedIn.

Passaggi successivi

• Interfaccia della riga di comando di APIOps
• Come gestire la configurazione di Gestione API con l'interfaccia della riga di comando di APIOps
• Panoramica di GitOps

Risorse correlate

• GitOps per Servizio Azure Kubernetes (AKS)
• Eseguire la migrazione di un'app Web tramite Gestione API
• Proteggere le API usando il Gateway Applicazione di Azure e API Management