Automatizar a configuração do Gerenciamento de API usando a CLI do APIOps

Gerenciamento de API do Azure

Azure DevOps

Azure Pipelines

GitHub

A APIOps é uma metodologia que aplica os conceitos do GitOps e do DevOps à implantação da API. Esta arquitetura demonstra como usar APIOps CLI para extrair, revisar e promover a configuração do Gerenciamento de API do Azure por meio de um fluxo de trabalho baseado em Git. Use essa abordagem para gerenciar o ciclo de vida da API, melhorar a qualidade da API e manter um registro auditável de alterações aprovadas.

Arquitetura

O diagrama a seguir ilustra o fluxo de trabalho de promoção de configuração da CLI do APIOps de alto nível. As equipes analisam os artefatos de Gerenciamento de APIs no Git e, em seguida, os pipelines de integração contínua e entrega contínua (CI/CD) promovem a configuração aprovada para os ambientes de destino do Gerenciamento de APIs.

Carrege um arquivo Visio desta arquitetura.

Workflow

A configuração de Gerenciamento de API começa extraindo uma configuração de Gerenciamento de API existente ou criando artefatos de Gerenciamento de API compatíveis com a CLI. O fluxo de trabalho operacional começa com qualquer um destes artefatos de entrada. Ambos os caminhos levam ao mesmo processo de solicitação de pull, validação, aprovação e implantação:

(A) Extrair primeiro: Um operador de API executa apiops extract em uma instância existente do API Management para criar arquivos de artefatos do API Management em sua ramificação local do Git. O operador usa esses artefatos para propor uma linha de base ou capturar uma alteração de configuração aprovada.
(B) Code-first: um desenvolvedor de API cria ou atualiza especificações de API compatíveis com a CLI do APIOps, arquivos de informação, políticas e artefatos relacionados do Gerenciamento de APIs em sua branch local do Git.

Use o seguinte ciclo de vida para qualquer entrada:

Crie uma alteração de configuração. Após a extração inicial ou a verificação de criação de artefato de código, o repositório de configuração da API se torna a fonte autoritativa da verdade para artefatos de configuração do API Management. O repositório mantém o histórico de versão e o registro de auditoria para cada implantação. Para fazer uma alteração, um operador ou desenvolvedor de API cria uma ramificação a partir da branch protegida no repositório de configuração da API e faz uma única alteração lógica relacionada à API.
Examine e valide a alteração. O operador ou desenvolvedor abre uma solicitação de pull para mesclar a ramificação em uma ramificação protegida. Os proprietários e revisores necessários do contrato de API, das políticas e da configuração do Gerenciamento de API revisam a solicitação de pull. O sistema de CI/CD executa as seguintes verificações e testes:
- Linting de especificação de API
- Detecção de alterações significativas em relação ao contrato aprovado
- Verificação de segurança de especificações e conteúdo do repositório
- Testes de API que verificam o comportamento esperado, a autenticação, os efeitos de política e as dependências de back-end
Essas verificações não exigem ferramentas de Microsoft. A equipe usa quaisquer ferramentas adequadas que atendam aos requisitos de suporte, segurança e licenciamento de sua organização.
Aprove a entrada de implantação imutável. Os proprietários ou revisores necessários aprovam a solicitação de pull e um mantenedor de repositório autorizado mescla as alterações revisadas após todas as verificações e revisões necessárias passarem. A confirmação mesclada e imutável e seus artefatos de ramificação protegida tornam-se a fonte auditável de verdade do repositório.

A equipe protege as ramificações protegidas do repositório contra envios diretos, exige aprovações de ambiente ou de conexões de serviço para alvos sensíveis e usa identidades separadas com privilégio mínimo para extração e publicação. Eles registram o commit aprovado com seu pull request, revisões e resultados de validação para fins de auditoria.
Pré-visualize a implantação. O pipeline de CI/CD executa apiops publish --dry-run para o commit aprovado usando o mesmo destino e o arquivo de substituição, sem publicar. O aprovador de versão avalia os recursos que a simulação cria, atualiza, exclui ou ignora. A equipe trata uma execução seca bem-sucedida como um portão de implantação, não um substituto para testes de API automatizados.
Publicar e promover. Depois que a execução seca passa pela validação, o pipeline de CI/CD usa apiops publish para publicar a mesma confirmação revisada. Em vários ambientes, a equipe de plataforma mantém estáveis os artefatos compartilhados e usa arquivos de configuração de sobreposição revisados para valores como URLs do back-end, IDs de recursos e referências a segredos. A equipe promove a confirmação por meio da não produção antes da produção e impede que mais de um pipeline grave para o mesmo destino ao mesmo tempo.

Note

A configuração aceita substituições de itens filho do workspace, mas não as aplica ao publicar. A publicação aplica substituições somente ao próprio contêiner do workspace. Não confie em substituições de recursos filho no workspace para promover APIs do workspace específicas do ambiente, backends, valores nomeados ou outros recursos filho. Valide uma abordagem alternativa de promoção para esses recursos ou adie a promoção até que o problema conhecido Propriedades de substituição no escopo do espaço de trabalho não são aplicadas seja resolvido.
Validar e reconciliar após a implantação. Após a publicação, a equipe de operações executa testes automatizados iniciais e de regressão, monitora o gerenciamento de APIs e a saúde do back-end, e compara a versão implantada com o commit aprovado. A equipe investiga e resolve alterações inesperadas por meio de solicitações de pull em vez de editar a produção diretamente.

Se um operador de API fizer uma alteração de emergência aprovada diretamente no Gerenciamento de API, o operador deverá executar uma extração em um check-out do Git, examinar e confirmar a alteração do artefato em seu branch, efetuar push do branch e abrir uma solicitação de pull. Os proprietários ou revisores necessários devem examinar e aprovar a solicitação de pull, e um mantenedor de repositório autorizado deve mesclá-la para que o repositório permaneça autoritativo.

Componentes

O Gerenciamento de API é um serviço gerenciado que cria gateways de API consistentes para serviços de back-end. Nessa arquitetura, ela fornece as configurações de origem que a CLI do APIOps extrai e os ambientes de destino em que a CLI publica definições de API, políticas, produtos, diagnósticos, valores nomeados e outras configurações com suporte.
A CLI do APIOps é um projeto de software livre que fornece ferramentas para uma abordagem de APIOps opinativa. Nessa arquitetura, ele extrai a configuração de Gerenciamento de API para arquivos de artefato, publica artefatos no Gerenciamento de API e pode estruturar fluxos de trabalho de CI/CD.
Um repositório Git armazena artefatos de Gerenciamento de API e, quando aplicável, contratos de API. Ele fornece o histórico de revisão e a fonte de verdade aprovada para implantações de pipeline.
Um sistema de CI/CD executa a validação, a extração e a publicação usando uma identidade de carga de trabalho ou outra credencial não interativa compatível. Nessa arquitetura, GitHub Actions ou Azure Pipelines definir os fluxos de trabalho de CI/CD.

Alternativas

Você pode substituir ou aumentar essa arquitetura por outros serviços ou abordagens Azure, dependendo dos requisitos funcionais e não funcionais da carga de trabalho. Considere as alternativas e as compensações a seguir.

Bicep ou Terraform e APIOps podem atender diferentes partes da mesma solução. Uma equipe que possui a configuração de Gerenciamento de API e a infraestrutura pode usar a infraestrutura como código (IaC) para provisionar o serviço de Gerenciamento de API e sua infraestrutura de suporte e usar o mesmo pipeline de IaC para gerenciar a configuração de Gerenciamento de API. Escolha essa abordagem quando a infraestrutura e a configuração forem alteradas e implantadas em conjunto e quando os parâmetros puderem expressar as diferenças entre os ambientes.

Use o padrão APIOps quando definições de API, políticas e configuração relacionada tiverem proprietários separados ou um ciclo de vida de versão independente da infraestrutura de serviço. A APIOps também é apropriada quando você precisa extrair a configuração existente, examinar artefatos focados em API ou promover a mesma configuração aprovada em vários ambientes ou instâncias de Gerenciamento de API. Alterações de política e API mais frequentes ou mais ambientes aumentam o valor desse fluxo de trabalho dedicado.

Esses fatores não têm limites fixos. Baseie a decisão principalmente em propriedade, requisitos de revisão e limites de implantação. Para um conjunto menor de APIs com uma baixa taxa de mudanças, comece com um fluxo de trabalho manual com pull requests e adicione agendamentos de extração ou automação de implantação somente depois que a linha de base do repositório e o processo de aprovação estiverem estabelecidos.

Detalhes do cenário

A APIOps usa o controle de versão para gerenciar APIs e criar uma trilha de auditoria de alterações em definições de API, políticas, produtos, diagnósticos e outras configurações de Gerenciamento de API. Examinar as alterações anteriores e, com mais frequência, ajuda as equipes a identificar desvios dos padrões de API antes da implantação. À medida que mais APIs adotam o mesmo processo, as equipes podem melhorar a consistência em todo o seu ecossistema de APIs.

Esse fluxo de trabalho implanta a configuração de Gerenciamento de API em uma instância de Gerenciamento de API. Ele não implanta back-ends de API, computação de aplicativos ou recursos de dados, rede ou a infraestrutura do serviço de Gerenciamento de API. Use a IaC governada separada e os pipelines de aplicativo para implantar essas camadas.

Esta solução ajuda as equipes:

Mantenha uma visão geral de ambientes e instâncias de Gerenciamento de API.
Acompanhe as alterações críticas nas APIs e nas políticas.
Crie uma trilha de auditoria para implantações aprovadas.
Reconciliar alterações aprovadas que se originam fora do repositório.

Escolha as origens dos artefatos e o proprietário

Escolha entre as seguintes maneiras pelas quais os artefatos entram no repositório e quem os possui antes de automatizar a implantação:

Extrair primeiro: Extraia uma instância confiável do API Management para estabelecer a linha de base inicial dos artefatos. Examine os artefatos gerados pelo check-in antes de tratar o repositório como a fonte da verdade.
Code-first: Mantenha o contrato da API, como uma descrição OpenAPI, junto ao código-fonte do aplicativo ou ao repositório de APIOps. Defina quem transforma esse contrato nos artefatos de Gerenciamento de API publicados pelo pipeline. Valide o fluxo de trabalho de importação e de artefatos planejado com uma instância do Gerenciamento de API que não seja de produção. Não suponha que um layout de origem arbitrário seja diretamente consumível pela CLI.
Responsabilidade compartilhada: Estabeleça se desenvolvedores de API, operadores de plataforma ou ambas possuem alterações em políticas, produtos, diagnósticos, valores nomeados e definições de API. Depois que a linha de base for aprovada, encaminhe todas as alterações pelo mesmo repositório e pelo mesmo processo de revisão.

Possíveis casos de uso

Organizações que desenvolvem e gerenciam APIs, incluindo organizações com uma única API exposta por meio do Gerenciamento de API.
Setores altamente regulamentados, como seguros, bancários, financeiros e governos que precisam de registros rastreáveis de revisão e implantação.

Considerações

Essas considerações implementam os pilares do Azure Well-Architected Framework, que é um conjunto de princípios orientadores que você pode usar para melhorar a qualidade de uma carga de trabalho. Para obter mais informações, consulte Well-Architected Framework.

Reliability

A confiabilidade ajuda a garantir que seu aplicativo possa cumprir os compromissos que você faz aos seus clientes. Para obter mais informações, consulte Lista de verificação da revisão de projeto para Confiabilidade.

Para alterações na API que não causam interrupção, use as revisões no Gerenciamento de API para implantar e testar uma revisão não atual antes de defini-la como atual. Se a validação falhar após a versão, restaure a revisão anterior como atual. Use versões de API para alterar o contrato para que os consumidores existentes possam continuar a usar a versão anterior.

Coordene as alterações de configuração do Gerenciamento de API com a estratégia de implantação para cada back-end de API. Reverter uma confirmação de APIOps restaura apenas a configuração representada por essa confirmação. Ele não restaura um back-end incompatível ou indisponível. Registre o commit do APIOps, a revisão do API Management e o release do back-end que compõem cada implantação validada. Teste o procedimento de reversão completo em um ambiente de não produção, incluindo políticas, valores nomeados, referências secretas, dependências e compatibilidade de back-end.

Segurança

A segurança fornece garantias contra ataques deliberados e o uso indevido de dados e sistemas valiosos. Para obter mais informações, consulte a lista de verificação de revisão de design para Segurança.

Use o repositório e o pipeline como o caminho normal para aplicar alterações de Gerenciamento de API. Os desenvolvedores e operadores não precisam de acesso de gravação persistente às instâncias de Gerenciamento de API de produção. Conceda acesso elevado somente quando necessário e somente por um tempo limitado. Reconciliar qualquer alteração resultante para o repositório.

Use os seguintes mecanismos para proteger o repositório Git que armazena artefatos de Gerenciamento de API:

Revisão da solicitação de pull: Proteja branches que implantam a configuração e exijam revisão pelos revisores apropriados.
Isolamento de credenciais: Prefira a identidade federada da carga de trabalho, se disponível. Armazene segredos específicos do ambiente em um cofre de segredos aprovado ou no ambiente do repositório, não em artefatos ou arquivos de pipeline.
Integridade de confirmação: Exigir confirmações assinadas para verificar a procedência de confirmação. Configure proteções de branch para evitar pushes forçados e a exclusão de branches, exigir autenticação multifator para que os usuários aprovem ou mesclem alterações e preservar o histórico de commits e pull requests para as implantações.
Revisão de artefato: Inspecione a saída de extração e publique entradas para segredos, marcadores redigidos e valores não intencionais específicos do ambiente. Valide se uma alteração não amplia o acesso à API nem enfraquece uma política.

Gerencie a CLI do APIOps como uma dependência de repositório. Fixe @azure-tools/apiops-cli em package.json uma versão testada, confirme do arquivo de bloqueio e use npm ci. Revise as configurações de identidade, variáveis, gatilhos e regras de proteção gerados antes de habilitar um pipeline de produção.

Otimização de custos

A Otimização de Custos concentra-se em maneiras de reduzir despesas desnecessárias e melhorar a eficiência operacional. Para obter mais informações, consulte a lista de verificação de revisão de design para Otimização de Custos.

A CLI do APIOps é um software de software livre, mas esse cenário gera custos para as instâncias de Gerenciamento de API e para o controle do código-fonte e a plataforma de CI/CD selecionadas. Uma única estimativa fixa não é fornecida porque os preços do Gerenciamento de API variam por região, camada, contagem de unidades, modelo de capacidade, configuração e uso de zona de disponibilidade ou multiregião. As cobranças de CI/CD também dependem do tipo de runner, dos minutos incluídos, da concorrência, do armazenamento e da retenção.

Crie uma estimativa específica do cenário na calculadora de preços Azure e registre as seguintes suposições com a decisão de arquitetura:

Estimar entrada	Premissa a ser registrada
Região de Gerenciamento de API	A região de implantação para cada instância de desenvolvimento, teste, preparo e produção.
Nível e capacidade	A camada ou a camada v2, o número de unidades ou gateways e as horas de operação para cada ambiente.
Resiliency	Qualquer implantação de zona de disponibilidade ou região adicional, incluindo as unidades em cada local.
Cobranças baseadas no uso	Solicitações ou operações esperadas e cobranças aplicáveis de espaço de trabalho, gateway auto-hospedado, rede, monitoramento ou transferência de dados.
Plataforma CI/CD	agentes hospedados no GitHub, hospedados pelo próprio usuário ou do Azure Pipelines. Execuções de pipeline esperadas, duração, simultaneidade, armazenamento e retenção de log ou artefato.
Controle do código-fonte e licenças	Número de usuários e quaisquer recursos de plano de GitHub ou Azure DevOps pagos.

Use os detalhes de preços atuais do Gerenciamento de API para selecionar o modelo de cobrança aplicável. Para suposições de CI/CD e controle do código-fonte, consulte Azure DevOps preços e preços de GitHub. Exporte ou capture a estimativa da calculadora, sua moeda, a data de preço e todas as suposições para que os revisores possam reproduzi-la e atualizá-la. Recalcule antes da implantação e quando regiões, camadas, quantidades de unidades, ambientes ou uso do pipeline mudarem.

Excelência operacional

A Excelência operacional abrange os processos de operações que implantam uma aplicação e as mantêm em execução em produção. Para obter mais informações, consulte a lista de verificação de revisão de design para Excelência Operacional.

A APIOps torna as implantações repetíveis e cria um histórico de confirmação para análise pós-alteração. Identifique ou registre de outra forma o commit que cada ambiente recebe, retenha os logs do pipeline e monitore a instância do Gerenciamento de API e as APIs dependentes após a implantação.

Para vários ambientes, promova a mesma confirmação de artefato revisada por meio de desenvolvimento, preparo e produção. Use substituições por ambiente apenas para valores que precisam diferir entre ambientes e revise esses arquivos com o mesmo cuidado dedicado aos artefatos. As substituições filho do workspace não são aplicadas no momento da publicação, portanto, não as use para promoção do ambiente. Teste os procedimentos de reversão antes de ocorrer um incidente. Uma reversão do Git ainda requer validação e uma publicação controlada para restaurar o Gerenciamento de API.

A CLI oferece os comandos init, extract e publish e pode gerar a estrutura de GitHub Actions ou pipelines do Azure DevOps. Examine os detalhes do comando na documentação da CLI do APIOps.

Faça a migração com segurança do kit de ferramentas APIOps legado

Se o seu processo de APIOps usa o kit de ferramentas legado do APIOps, planeje a atualização. Essa abordagem usa binários separados do Extractor e do Publisher e templates de pipeline. O APIOps CLI usa uma única CLI em Node.js, mas seu formato de artefato foi projetado para ser compatível com artefatos de kits de ferramentas existentes. Trate a migração como uma transição controlada, e não como uma atualização diretamente no ambiente de produção.

Marque os artefatos do kit de ferramentas e o pipeline comprovadamente válidos e preserve o editor existente como opção de reversão. Não altere o publicador legado nem implante o novo publicador na mesma implantação.
Em um branch de migração, use a versão mais recente da CLI do APIOps e execute apiops init sem usar --force. O comando detecta arquivos conflitantes e sai em vez de substituí-los. Compare e integre deliberadamente os pipelines gerados, as diretrizes de identidade, os filtros e os arquivos de substituição.
Use os artefatos com apiops publish --dry-run e as substituições do ambiente de destino em uma instância do API Management de não produção. Examine os recursos que a CLI criaria, atualizaria ou excluiria. Teste uma publicação controlada e valide as APIs implantadas, as políticas, os valores nomeados e as dependências.
Não use substituições de elementos filhos do workspace, que não são aplicadas durante a publicação, como parte do planejamento da migração ou da promoção. Valide uma abordagem alternativa de promoção para os recursos filhos afetados ou adie a migração deles até que o problema conhecido propriedades de substituição com escopo de espaço de trabalho não aplicadas seja resolvido.
No momento da transição, permita que apenas um publicador grave em uma instância do Gerenciamento de API. Desabilite o gatilho do editor herdado antes de habilitar o editor da CLI. Implante um commit revisado e monitore o resultado. Mantenha o pipeline do Toolkit com tag e a linha de base de artefatos até que o novo fluxo de trabalho conclua com sucesso um ciclo de lançamento.

Para obter detalhes de compatibilidade e exemplos de migração comando por comando, consulte Migração do Kit de Ferramentas do APIOps.

Implantar este cenário

Siga a Documentação da CLI do APIOps no repositório de GitHub da CLI do APIOps. Comece com uma instância de Gerenciamento de API de não produção e use as diretrizes de versão da CLI do APIOps atual. Para começar a usar um ambiente de não produção, consulte Como gerenciar a configuração de Gerenciamento de API com a CLI do APIOps.

Colaboradores

A Microsoft mantém este artigo. Os colaboradores a seguir escreveram este artigo.

Autores principais:

Pat Altimore | Desenvolvedor sênior de conteúdo
Wael Kdouh | Arquiteto Principal Sênior de Soluções
Rishabh Saha | Arquiteto Principal Sênior de Soluções

Para ver perfis de LinkedIn não públicos, entre em LinkedIn.

Próximas etapas

Comentários

Esta página foi útil?