Automatize a configuração de Gestão de APIs utilizando a CLI APIOps

API Management do Azure

Azure DevOps

Azure Pipelines

GitHub

APIOps é uma metodologia que aplica os conceitos de GitOps e DevOps à implantação de API. Esta arquitetura demonstra como usar a CLI APIOps para extrair, rever e promover a configuração do API Management do Azure através de um fluxo de trabalho baseado em Git. Use esta abordagem para gerir o ciclo de vida da API, melhorar a qualidade da API e manter um registo auditável das alterações aprovadas.

Arquitetura

O diagrama seguinte ilustra o fluxo de trabalho de promoção da configuração da CLI APIOps de alto nível. As equipas analisam artefactos do API Management 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 API Management.

O diagrama tem três secções da esquerda para a direita. À esquerda, a entrada alternativa A utiliza um fluxo de trabalho extract-first que executa o 'apiops extract' numa configuração existente de gestão de API source. A entrada alternativa B utiliza a abordagem de código primeiro para criar artefactos de Gestão de APIs compatíveis com a CLI: ficheiros JSON de informação, XML de políticas e especificações de API. Ambas as entradas apontam para o repositório Git no centro, onde o passo 1 cria uma alteração de configuração num branch, o passo 2 revê e valida o pull request, e o passo 3 aprova a entrada de implementação imutável como um commit aprovado. Uma seta conduz do passo 3 ao fluxo de trabalho CI/CD na secção de Implementação Controlada à direita. O fluxo de trabalho CI/CD pré-visualiza a entrada aprovada no passo 4 executando 'apiops publish --dry-run', publica-a e promove-a no passo 5 executando o 'apiops publish', e valida e reconcilia os ambientes de gestão de API alvo no passo 6.

Descarregue um ficheiro Visio desta arquitetura.

Workflow

A configuração de Gestão de APIs começa por extrair uma configuração de Gestão de APIs existente ou por criar artefactos de Gestão de APIs compatíveis com CLI. O fluxo de trabalho operacional começa com qualquer um destes artefactos. Ambos os caminhos conduzem ao mesmo processo de pull request, validação, aprovação e implementação:

• (A) Extrair primeiro: Um operador de API executa apiops extract numa instância existente do API Management para criar ficheiros de artefactos do API Management no ramo local da cópia de trabalho do Git. O operador utiliza estes artefactos para propor uma linha de base ou captar uma alteração de configuração aprovada.

• (B) Code-first: Um programador de API cria ou atualiza especificações APIOps compatíveis com CLI, ficheiros de informação, políticas e artefactos relacionados de gestão de API no seu branch local de checkout Git.

Use o seguinte ciclo de vida para qualquer uma das entradas:

1. Crie uma alteração de configuração. Após a extração inicial ou verificação de criação de artefactos baseada no código, o repositório de configuração da API torna-se a fonte autoritativa de verdade para artefactos de configuração de Gestão de APIs. O repositório mantém o histórico de versões e o registo de auditoria de cada implementação. Para fazer uma alteração, um operador ou programador da API cria uma ramificação a partir da ramificação protegida no repositório de configuração da API e faz uma alteração lógica relacionada com a API.

2. Revê e valida a alteração. O operador ou programador abre um pull request para fundir o seu ramal num ramal protegido. Os proprietários e revisores obrigatórios do contrato da API, das políticas e da configuração de Gestão da API analisam o pull request. O sistema CI/CD executa as seguintes verificações e testes:

   • Linting de especificações de API
   • Deteção de alteração disruptiva em relação ao contrato aprovado
   • Varredura de segurança das especificações e do conteúdo do repositório
   • Testes de API que verificam comportamentos esperados, autenticação, efeitos de políticas e dependências do back-end

   Estas verificações não requerem ferramentas da Microsoft. A equipa utiliza as ferramentas adequadas que cumpram os requisitos de suporte, segurança e licenciamento da sua organização.

3. Aprove a entrada de implementação imutável. Os proprietários ou revisores obrigatórios aprovam o pull request, e um mantenedor autorizado do repositório faz a fusão das alterações revistas depois de todas as verificações e revisões obrigatórias terem sido aprovadas. O commit resultante da fusão, imutável, e os seus artefactos do ramo protegido tornam-se a fonte de verdade auditável do repositório.

   A equipa protege as ramificações protegidas do repositório contra envios diretos, exige aprovações de ambiente ou de ligações de serviço para destinos sensíveis e utiliza identidades separadas com o menor nível de privilégios para extração e publicação. Registam o commit aprovado com o respetivo pedido de integração, revisões e resultados de validação para efeitos de auditoria.

4. Pré-visualize a implementação. O pipeline de CI/CD executa apiops publish --dry-run para o commit aprovado utilizando o mesmo destino e o mesmo ficheiro de substituição sem publicar. O aprovador da versão revê os recursos que a simulação cria, atualiza, elimina ou ignora. A equipa trata um ensaio bem-sucedido como uma porta de implementação, não como um substituto dos testes automáticos da API.

5. Publica e promove. Depois de a execução de teste passar na validação, o pipeline de CI/CD usa apiops publish para publicar o mesmo commit revisto. Para múltiplos ambientes, a equipa da plataforma mantém artefactos partilhados estáveis e utiliza ficheiros de configuração de override revistos para valores como URLs de back-end, IDs de recursos e referências secretas. A equipa promove o commit através da não-produção antes da produção e impede que mais do que um pipeline escreva no mesmo alvo ao mesmo tempo.

   Note

   A configuração aceita substituições dos itens subordinados do workspace, mas não as aplica ao publicar. Publicar aplica sobreposições apenas ao contentor do espaço de trabalho em si. Não recorra a substituições dos elementos subordinados do espaço de trabalho para expor APIs do espaço de trabalho específicas do ambiente, serviços de back-end, valores com nome ou outros recursos subordinados. Valide uma abordagem alternativa de promoção para esses recursos, ou adie a promoção até que as propriedades de sobreposição com âmbito de Workspace não aplicadas e o problema conhecido sejam resolvidas.

6. Valide e reconcilie após a implementação. Após a publicação, a equipa de operações executa testes automáticos de fumo e regressão, monitoriza a gestão da API e o estado do back-end, e compara o resultado implementado com o commit aprovado. A equipa investiga e resolve alterações inesperadas através de pull requests, em vez de editar diretamente a produção.

   Se um operador de API fizer uma alteração de emergência aprovada diretamente na API Management, deve executar uma extração numa verificação Git, rever e confirmar a alteração do artefacto no seu branch, empurrar o branch e abrir um pull request. Os proprietários ou revisores obrigados devem rever e aprovar o pull request, e um mantenedor autorizado do repositório deve fundi-lo para que o repositório permaneça autoritativo.

Componentes

• A Gestão de APIs é um serviço gerido que cria gateways de API consistentes para serviços de back-end. Nesta arquitetura, fornece as configurações de origem extraídas pela CLI APIOps e os ambientes-alvo onde a CLI publica definições aprovadas da API, políticas, produtos, diagnósticos, valores nomeados e outras configurações suportadas.

• APIOps CLI é um projeto open-source que fornece ferramentas para uma abordagem APIOps opinativa. Nesta arquitetura, extrai a configuração de Gestão de APIs para ficheiros de artefactos, publica artefactos para a Gestão de APIs e pode apoiar fluxos de trabalho CI/CD.

• Um repositório Git armazena artefactos de Gestão de APIs e, quando aplicável, contratos de API. Fornece o histórico de revisões e a fonte de referência aprovada para as implementações do pipeline.

• Um sistema CI/CD executa validação, extração e publicação utilizando uma identidade de carga de trabalho ou outra credencial não interativa suportada. Nesta arquitetura, os GitHub Actions ou Azure Pipelines definem os fluxos de trabalho CI/CD.

Alternativas

Pode substituir ou complementar esta arquitetura por outros serviços ou abordagens do Azure, dependendo dos requisitos funcionais e não funcionais da sua carga de trabalho. Considere as seguintes alternativas e compensações.

Bicep ou Terraform e APIOps podem servir diferentes partes da mesma solução. Uma equipa que detenha tanto a configuração como a infraestrutura de Gestão de APIs pode usar a infraestrutura como código (IaC) para provisionar o serviço de Gestão de APIs e a sua infraestrutura de suporte, e usar o mesmo pipeline IaC para gerir a configuração de Gestão de APIs. Escolha esta abordagem quando a infraestrutura e a configuração mudam e implementam em conjunto, e quando os parâmetros possam expressar as diferenças entre ambientes.

Use o padrão APIOps quando definições API, políticas e configurações relacionadas tiverem proprietários separados ou um ciclo de vida de lançamento independente da infraestrutura de serviço. O APIOps também é adequado quando precisa de extrair configuração existente, rever artefactos focados em APIs ou promover a mesma configuração aprovada em múltiplos ambientes ou instâncias de Gestão de APIs. Alterações mais frequentes na API e nas políticas, ou mais ambientes, aumentam o valor deste fluxo de trabalho dedicado.

Estes fatores não têm limiares fixos. Baseie a decisão principalmente na titularidade, nos requisitos de revisão e nos limites de implantação. Para um conjunto de API mais pequeno com baixa taxa de alteração, comece com um fluxo manual de pull request e adicione agendas de extração ou automação de implementação apenas depois de a linha base do repositório e o processo de aprovação estarem estabelecidos.

Detalhes do cenário

O APIOps utiliza controlo de versões para gerir APIs e criar um registo de auditoria das alterações às definições, políticas, produtos, diagnósticos e outras configurações de gestão de APIs. Rever as alterações mais cedo e com mais frequência ajuda as equipas a identificar desvios em relação aos padrões da API antes da implementação. À medida que mais APIs utilizam o mesmo processo, as equipas podem melhorar a consistência em todo o seu ecossistema de APIs.

Este fluxo de trabalho implementa a configuração de Gestão de APIs para uma instância de Gestão de APIs. Não implementa componentes de back-end da API, recursos de computação de aplicações ou de dados, recursos de rede nem a infraestrutura do serviço API Management. Utilize pipelines separados e governados de IaC e de aplicação para implementar essas camadas.

Esta solução ajuda as equipas:

• Mantenha uma visão geral dos ambientes e das instâncias de Gestão de APIs.
• Acompanhar alterações críticas às APIs e políticas.
• Crie um registo de auditoria para as implementações aprovadas.
• Reconciliar alterações aprovadas que tenham origem fora do repositório.

Escolha as origens dos artefactos e os proprietários

Escolha entre as seguintes formas como os artefactos entram no repositório e quem os possui antes de automatizar a implementação:

• Extrair primeiro: Extrair uma instância de Gestão de API conhecida para estabelecer a linha base inicial do artefacto. Verifique os artefactos gerados confirmados no repositório antes de considerar o repositório como fonte fidedigna.
• Código em primeiro lugar: Mantenha o contrato da API, como uma descrição OpenAPI, com o código-fonte da aplicação ou o repositório APIOps. Defina quem transforma esse contrato nos artefactos de Gestão de APIs que o pipeline publica. Valide o fluxo de trabalho de importação e artefactos pretendido com uma instância de Gestão de API não produtiva. Não parta do princípio de que uma estrutura de origem arbitrária pode ser diretamente utilizada pela CLI.
• Responsabilidade partilhada: Determinar se os desenvolvedores da API, operadores da plataforma ou ambos possuem alterações a políticas, produtos, diagnósticos, valores nomeados e definições da API. Depois de a linha de base ser aceite, faça passar todas as alterações através do mesmo repositório e do mesmo processo de revisão.

Potenciais casos de utilização

• Organizações que desenvolvem e gerem APIs, incluindo organizações com uma única API exposta através da Gestão de APIs.

• Setores altamente regulados, como seguros, banca, finanças e governo, que precisam de registos de revisão e implementação rastreáveis.

Considerações

Estas considerações implementam os pilares do Azure Well-Architected Framework, que é um conjunto de princípios orientadores que 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ê assume com seus clientes. Para obter mais informações, consulte Lista de verificação de revisão de design para confiabilidade.

Para alterações à API sem quebra de compatibilidade, use as revisões da Gestão de API para implementar e testar uma revisão que ainda não está atual antes de a tornar atual. Se a validação falhar após o lançamento, restaure a versão anterior como atual. Use versões da API para quebrar alterações contratuais, de modo a que os consumidores existentes possam continuar a usar a versão anterior.

Coordenar as alterações de configuração da Gestão da API com a estratégia de implementação para cada back-end da API. Reverter um commit APIOps restaura apenas a configuração representada por esse commit. Não restaura um backend incompatível ou indisponível. Registar o commit do APIOps, a revisão do API Management e a versão do back-end que constituem cada implementação validada. Teste o procedimento completo de reversão num ambiente não produtivo, incluindo políticas, valores nomeados, referências a segredos, dependências e compatibilidade com o 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 Lista de verificação de revisão de design para segurança.

Use o repositório e o pipeline como caminho normal para aplicar alterações de Gestão de APIs. Os programadores e operadores não precisam de acesso persistente de escrita às instâncias de Gestão de APIs de produção. Conceder acesso elevado apenas quando necessário e apenas por tempo limitado. Reconcilie qualquer alteração resultante no repositório.

Use os seguintes mecanismos para proteger o repositório Git que armazena artefactos de Gestão de APIs:

• Revisão por pull request: Proteger os ramos que implementam a configuração e que exigem revisão pelos revisores apropriados.
• Isolamento de credenciais: Prefira identidade de carga de trabalho federada, se disponível. Armazenar segredos específicos do ambiente num ambiente de armazenamento ou repositório secreto aprovado, não em artefactos ou ficheiros de pipeline.
• Integridade dos commits: Exija commits assinados para confirmar a proveniência dos commits. Configurar proteções de ramificações para impedir submissões forçadas e a eliminação de ramificações, exigir autenticação multifator para que os utilizadores possam aprovar ou intercalar alterações e preservar o histórico de confirmações e de pedidos de integração para implementações.
• Revisão de artefactos: Inspecionar a saída da extração e publicar entradas para segredos, marcadores censurados e valores não intencionais específicos do ambiente. Validar que uma alteração não alarga o acesso à API nem enfraquece uma política.

Gerir a CLI APIOps como uma dependência de repositório. Fixe @azure-tools/apiops-cli numa versão testada em package.json, submeta o ficheiro de bloqueio e use npm ci. Revise as definições de identidade geradas, variáveis, gatilhos e regras de proteção antes de ativar um pipeline de produção.

Otimização de Custos

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

O APIOps CLI é software de código aberto, mas este cenário acarreta custos para as instâncias do API Management e para a plataforma de controlo de código-fonte e CI/CD selecionada. Não é fornecida uma única estimativa fixa porque os preços da API Management variam consoante a região, nível, número de unidades, modelo de capacidade, configuração de zonas de disponibilidade ou multirregional e utilização. Os custos de CI/CD também dependem do tipo de runner, dos minutos incluídos, da simultaneidade, do armazenamento e da retenção.

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

Entrada de estimativas	Suposição para registar
Região de Gestão de APIs	A região de implantação para cada instância de desenvolvimento, teste, pré-produção e produção.
Nível e capacidade	O tier ou tier v2, o número de unidades ou gateways e as horas de funcionamento para cada ambiente.
Resiliency	Qualquer destacamento em zona de disponibilidade ou região adicional, incluindo as unidades em cada local.
Encargos baseados na utilização	Solicitações ou operações previstas e quaisquer custos aplicáveis da área de trabalho, do gateway autoalojado, de rede, de monitorização ou de transferência de dados.
Plataforma CI/CD	Agentes alojados no GitHub, autoalojados ou do Azure Pipelines. Execuções esperadas do pipeline, duração, concorrência, armazenamento e retenção de logs ou artefactos.
Controlo de código-fonte e licenças	Número de utilizadores e quaisquer funcionalidades pagas do plano GitHub ou Azure DevOps.

Utilize os detalhes atuais de preços da API Management para selecionar o modelo de faturação aplicável. Para pressupostos sobre CI/CD e controlo de versão, veja preços do Azure DevOps e preços do GitHub. Exporte ou capture a estimativa da calculadora, a sua moeda, a data de preços e todas as suposições para que os revisores possam reproduzi-la e atualizá-la. Recalcule antes da implementação e sempre que as regiões, os escalões, o número de unidades, os ambientes ou a utilização do pipeline mudarem.

Excelência Operacional

A Excelência Operacional abrange os processos operacionais que implantam um aplicativo e o mantêm em execução na produção. Para obter mais informações, consulte Lista de verificação de revisão de design para excelência operacional.

O APIOps torna as implementações repetíveis e cria um histórico de commits para análise pós-alteração. Marcar ou registar de outra forma o commit que cada ambiente recebe, manter os logs do pipeline e monitorizar a instância de Gestão de API e as APIs dependentes após a implementação.

Para múltiplos ambientes, promova o mesmo commit de artefacto revisto através do desenvolvimento, staging e produção. Use sobreposições de ambiente apenas para valores que tenham de diferir entre ambientes e reveja esses ficheiros com o mesmo cuidado que os artefactos. As substituições de filhos do workspace não são aplicadas na altura da publicação, por isso não as uses para promoção do ambiente. Teste os procedimentos de rollback antes de ocorrer um incidente. Um revert Git ainda requer validação e uma publicação controlada para restaurar a Gestão da API.

A CLI fornece init, extract, e publish comandos e pode estruturar pipelines GitHub Actions ou Azure DevOps. Consulte os detalhes dos comandos na documentação da CLI do APIOps.

Migrar em segurança a partir do Kit de Ferramentas APIOps legado

Se o seu processo APIOps usar o antigo APIOps Toolkit, planeie atualizar. Esta abordagem utiliza binários separados para o Extractor e o Publisher, bem como modelos de pipeline. A CLI APIOps utiliza uma única Node.js CLI, mas o seu formato de artefacto foi concebido para ser compatível com artefactos existentes do toolkit. Trate a migração como uma transição controlada, não como uma atualização de produção no local.

1. Marque os artefactos validados do conjunto de ferramentas e o pipeline, e preserve o publicador existente como opção de reversão. Não altere o publicador antigo nem introduza o novo publicador na mesma implementação.

2. Numa ramificação de migração, use a versão mais recente da CLI APIOps e execute apiops init sem usar --force. O comando deteta ficheiros e saídas conflitantes em vez de os sobrescrever. Compare e integre de forma deliberada os pipelines gerados, as diretrizes de identidade, os filtros e os ficheiros de substituição.

3. Use os artefactos com apiops publish --dry-run e as sobrescrições do ambiente alvo contra uma instância de Gestão de API não produtiva. Revise os recursos que a CLI criaria, atualizaria ou eliminaria. Teste uma publicação controlada e valide as APIs implementadas, as políticas, os valores com nome e as dependências.

4. Não utilize substituições filhas do workspace, que não são aplicadas na altura da publicação, como parte do design da migração ou promoção. Validar uma abordagem alternativa de promoção para recursos filhos afetados, ou adiar a sua migração até que as propriedades de sobreposição no âmbito do Workspace não aplicadas sejam resolvidas.

5. Na transição, permita que apenas um publicador escreva numa instância de gestão de APIs. Desative o gatilho do editor legado antes de ativar o editor da CLI. Faz a implementação de um commit revisto e monitoriza o resultado. Mantém o pipeline marcado do Toolkit e a linha base de artefactos até que o novo fluxo de trabalho complete um ciclo de lançamento bem-sucedido.

Para detalhes de compatibilidade e exemplos de migração comando a comando, consulte Migração a partir do APIOps Toolkit.

Implementar este cenário

Siga a Documentação da CLI APIOps no repositório GitHub da APIOps CLI. Comece com uma instância de Gestão de API não produtiva e use as orientações atuais de lançamento da CLI APIOps. Para começar com um ambiente de não-produção, veja Como gerir a configuração de Gestão de APIs com API CLI.

Contribuidores

A Microsoft mantém este artigo. Os seguintes colaboradores escreveram este artigo.

Principais autores:

• Pat Altimore | Desenvolvedor Sénior de Conteúdos
• Wael Kdouh | Arquiteto Principal Sénior de Soluções
• Rishabh Saha | Arquiteto Principal Sénior de Soluções

Para ver perfis não públicos do LinkedIn, faça login no LinkedIn.

Próximos passos

• APIOps CLI
• Como gerir a configuração de Gestão de API com APIOps CLI
• Visão geral do GitOps

Recursos relacionados

• GitOps for Azure Kubernetes Service (AKS)
• Migre uma aplicação web utilizando a Gestão de APIs
• Proteja APIs usando o Gateway de Aplicativo do Azure e o Gerenciamento de API

APIOps é uma metodologia que aplica os conceitos de GitOps e DevOps à implantação de API. Esta arquitetura demonstra como usar a CLI APIOps para extrair, rever e promover a configuração do API Management do Azure através de um fluxo de trabalho baseado em Git. Use esta abordagem para gerir o ciclo de vida da API, melhorar a qualidade da API e manter um registo auditável das alterações aprovadas.

Arquitetura

O diagrama seguinte ilustra o fluxo de trabalho de promoção da configuração da CLI APIOps de alto nível. As equipas analisam artefactos do API Management 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 API Management.

O diagrama tem três secções da esquerda para a direita. À esquerda, a entrada alternativa A utiliza um fluxo de trabalho extract-first que executa o 'apiops extract' numa configuração existente de gestão de API source. A entrada alternativa B utiliza a abordagem de código primeiro para criar artefactos de Gestão de APIs compatíveis com a CLI: ficheiros JSON de informação, XML de políticas e especificações de API. Ambas as entradas apontam para o repositório Git no centro, onde o passo 1 cria uma alteração de configuração num branch, o passo 2 revê e valida o pull request, e o passo 3 aprova a entrada de implementação imutável como um commit aprovado. Uma seta conduz do passo 3 ao fluxo de trabalho CI/CD na secção de Implementação Controlada à direita. O fluxo de trabalho CI/CD pré-visualiza a entrada aprovada no passo 4 executando 'apiops publish --dry-run', publica-a e promove-a no passo 5 executando o 'apiops publish', e valida e reconcilia os ambientes de gestão de API alvo no passo 6.

Descarregue um ficheiro Visio desta arquitetura.

Workflow

A configuração de Gestão de APIs começa por extrair uma configuração de Gestão de APIs existente ou por criar artefactos de Gestão de APIs compatíveis com CLI. O fluxo de trabalho operacional começa com qualquer um destes artefactos. Ambos os caminhos conduzem ao mesmo processo de pull request, validação, aprovação e implementação:

• (A) Extrair primeiro: Um operador de API executa apiops extract numa instância existente do API Management para criar ficheiros de artefactos do API Management no ramo local da cópia de trabalho do Git. O operador utiliza estes artefactos para propor uma linha de base ou captar uma alteração de configuração aprovada.

• (B) Code-first: Um programador de API cria ou atualiza especificações APIOps compatíveis com CLI, ficheiros de informação, políticas e artefactos relacionados de gestão de API no seu branch local de checkout Git.

Use o seguinte ciclo de vida para qualquer uma das entradas:

1. Crie uma alteração de configuração. Após a extração inicial ou verificação de criação de artefactos baseada no código, o repositório de configuração da API torna-se a fonte autoritativa de verdade para artefactos de configuração de Gestão de APIs. O repositório mantém o histórico de versões e o registo de auditoria de cada implementação. Para fazer uma alteração, um operador ou programador da API cria uma ramificação a partir da ramificação protegida no repositório de configuração da API e faz uma alteração lógica relacionada com a API.

2. Revê e valida a alteração. O operador ou programador abre um pull request para fundir o seu ramal num ramal protegido. Os proprietários e revisores obrigatórios do contrato da API, das políticas e da configuração de Gestão da API analisam o pull request. O sistema CI/CD executa as seguintes verificações e testes:

   • Linting de especificações de API
   • Deteção de alteração disruptiva em relação ao contrato aprovado
   • Varredura de segurança das especificações e do conteúdo do repositório
   • Testes de API que verificam comportamentos esperados, autenticação, efeitos de políticas e dependências do back-end

   Estas verificações não requerem ferramentas da Microsoft. A equipa utiliza as ferramentas adequadas que cumpram os requisitos de suporte, segurança e licenciamento da sua organização.

3. Aprove a entrada de implementação imutável. Os proprietários ou revisores obrigatórios aprovam o pull request, e um mantenedor autorizado do repositório faz a fusão das alterações revistas depois de todas as verificações e revisões obrigatórias terem sido aprovadas. O commit resultante da fusão, imutável, e os seus artefactos do ramo protegido tornam-se a fonte de verdade auditável do repositório.

   A equipa protege as ramificações protegidas do repositório contra envios diretos, exige aprovações de ambiente ou de ligações de serviço para destinos sensíveis e utiliza identidades separadas com o menor nível de privilégios para extração e publicação. Registam o commit aprovado com o respetivo pedido de integração, revisões e resultados de validação para efeitos de auditoria.

4. Pré-visualize a implementação. O pipeline de CI/CD executa apiops publish --dry-run para o commit aprovado utilizando o mesmo destino e o mesmo ficheiro de substituição sem publicar. O aprovador da versão revê os recursos que a simulação cria, atualiza, elimina ou ignora. A equipa trata um ensaio bem-sucedido como uma porta de implementação, não como um substituto dos testes automáticos da API.

5. Publica e promove. Depois de a execução de teste passar na validação, o pipeline de CI/CD usa apiops publish para publicar o mesmo commit revisto. Para múltiplos ambientes, a equipa da plataforma mantém artefactos partilhados estáveis e utiliza ficheiros de configuração de override revistos para valores como URLs de back-end, IDs de recursos e referências secretas. A equipa promove o commit através da não-produção antes da produção e impede que mais do que um pipeline escreva no mesmo alvo ao mesmo tempo.

   Note

   A configuração aceita substituições dos itens subordinados do workspace, mas não as aplica ao publicar. Publicar aplica sobreposições apenas ao contentor do espaço de trabalho em si. Não recorra a substituições dos elementos subordinados do espaço de trabalho para expor APIs do espaço de trabalho específicas do ambiente, serviços de back-end, valores com nome ou outros recursos subordinados. Valide uma abordagem alternativa de promoção para esses recursos, ou adie a promoção até que as propriedades de sobreposição com âmbito de Workspace não aplicadas e o problema conhecido sejam resolvidas.

6. Valide e reconcilie após a implementação. Após a publicação, a equipa de operações executa testes automáticos de fumo e regressão, monitoriza a gestão da API e o estado do back-end, e compara o resultado implementado com o commit aprovado. A equipa investiga e resolve alterações inesperadas através de pull requests, em vez de editar diretamente a produção.

   Se um operador de API fizer uma alteração de emergência aprovada diretamente na API Management, deve executar uma extração numa verificação Git, rever e confirmar a alteração do artefacto no seu branch, empurrar o branch e abrir um pull request. Os proprietários ou revisores obrigados devem rever e aprovar o pull request, e um mantenedor autorizado do repositório deve fundi-lo para que o repositório permaneça autoritativo.

Componentes

• A Gestão de APIs é um serviço gerido que cria gateways de API consistentes para serviços de back-end. Nesta arquitetura, fornece as configurações de origem extraídas pela CLI APIOps e os ambientes-alvo onde a CLI publica definições aprovadas da API, políticas, produtos, diagnósticos, valores nomeados e outras configurações suportadas.

• APIOps CLI é um projeto open-source que fornece ferramentas para uma abordagem APIOps opinativa. Nesta arquitetura, extrai a configuração de Gestão de APIs para ficheiros de artefactos, publica artefactos para a Gestão de APIs e pode apoiar fluxos de trabalho CI/CD.

• Um repositório Git armazena artefactos de Gestão de APIs e, quando aplicável, contratos de API. Fornece o histórico de revisões e a fonte de referência aprovada para as implementações do pipeline.

• Um sistema CI/CD executa validação, extração e publicação utilizando uma identidade de carga de trabalho ou outra credencial não interativa suportada. Nesta arquitetura, os GitHub Actions ou Azure Pipelines definem os fluxos de trabalho CI/CD.

Alternativas

Pode substituir ou complementar esta arquitetura por outros serviços ou abordagens do Azure, dependendo dos requisitos funcionais e não funcionais da sua carga de trabalho. Considere as seguintes alternativas e compensações.

Bicep ou Terraform e APIOps podem servir diferentes partes da mesma solução. Uma equipa que detenha tanto a configuração como a infraestrutura de Gestão de APIs pode usar a infraestrutura como código (IaC) para provisionar o serviço de Gestão de APIs e a sua infraestrutura de suporte, e usar o mesmo pipeline IaC para gerir a configuração de Gestão de APIs. Escolha esta abordagem quando a infraestrutura e a configuração mudam e implementam em conjunto, e quando os parâmetros possam expressar as diferenças entre ambientes.

Use o padrão APIOps quando definições API, políticas e configurações relacionadas tiverem proprietários separados ou um ciclo de vida de lançamento independente da infraestrutura de serviço. O APIOps também é adequado quando precisa de extrair configuração existente, rever artefactos focados em APIs ou promover a mesma configuração aprovada em múltiplos ambientes ou instâncias de Gestão de APIs. Alterações mais frequentes na API e nas políticas, ou mais ambientes, aumentam o valor deste fluxo de trabalho dedicado.

Estes fatores não têm limiares fixos. Baseie a decisão principalmente na titularidade, nos requisitos de revisão e nos limites de implantação. Para um conjunto de API mais pequeno com baixa taxa de alteração, comece com um fluxo manual de pull request e adicione agendas de extração ou automação de implementação apenas depois de a linha base do repositório e o processo de aprovação estarem estabelecidos.

Detalhes do cenário

O APIOps utiliza controlo de versões para gerir APIs e criar um registo de auditoria das alterações às definições, políticas, produtos, diagnósticos e outras configurações de gestão de APIs. Rever as alterações mais cedo e com mais frequência ajuda as equipas a identificar desvios em relação aos padrões da API antes da implementação. À medida que mais APIs utilizam o mesmo processo, as equipas podem melhorar a consistência em todo o seu ecossistema de APIs.

Este fluxo de trabalho implementa a configuração de Gestão de APIs para uma instância de Gestão de APIs. Não implementa componentes de back-end da API, recursos de computação de aplicações ou de dados, recursos de rede nem a infraestrutura do serviço API Management. Utilize pipelines separados e governados de IaC e de aplicação para implementar essas camadas.

Esta solução ajuda as equipas:

• Mantenha uma visão geral dos ambientes e das instâncias de Gestão de APIs.
• Acompanhar alterações críticas às APIs e políticas.
• Crie um registo de auditoria para as implementações aprovadas.
• Reconciliar alterações aprovadas que tenham origem fora do repositório.

Escolha as origens dos artefactos e os proprietários

Escolha entre as seguintes formas como os artefactos entram no repositório e quem os possui antes de automatizar a implementação:

• Extrair primeiro: Extrair uma instância de Gestão de API conhecida para estabelecer a linha base inicial do artefacto. Verifique os artefactos gerados confirmados no repositório antes de considerar o repositório como fonte fidedigna.
• Código em primeiro lugar: Mantenha o contrato da API, como uma descrição OpenAPI, com o código-fonte da aplicação ou o repositório APIOps. Defina quem transforma esse contrato nos artefactos de Gestão de APIs que o pipeline publica. Valide o fluxo de trabalho de importação e artefactos pretendido com uma instância de Gestão de API não produtiva. Não parta do princípio de que uma estrutura de origem arbitrária pode ser diretamente utilizada pela CLI.
• Responsabilidade partilhada: Determinar se os desenvolvedores da API, operadores da plataforma ou ambos possuem alterações a políticas, produtos, diagnósticos, valores nomeados e definições da API. Depois de a linha de base ser aceite, faça passar todas as alterações através do mesmo repositório e do mesmo processo de revisão.

Potenciais casos de utilização

• Organizações que desenvolvem e gerem APIs, incluindo organizações com uma única API exposta através da Gestão de APIs.

• Setores altamente regulados, como seguros, banca, finanças e governo, que precisam de registos de revisão e implementação rastreáveis.

Considerações

Estas considerações implementam os pilares do Azure Well-Architected Framework, que é um conjunto de princípios orientadores que 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ê assume com seus clientes. Para obter mais informações, consulte Lista de verificação de revisão de design para confiabilidade.

Para alterações à API sem quebra de compatibilidade, use as revisões da Gestão de API para implementar e testar uma revisão que ainda não está atual antes de a tornar atual. Se a validação falhar após o lançamento, restaure a versão anterior como atual. Use versões da API para quebrar alterações contratuais, de modo a que os consumidores existentes possam continuar a usar a versão anterior.

Coordenar as alterações de configuração da Gestão da API com a estratégia de implementação para cada back-end da API. Reverter um commit APIOps restaura apenas a configuração representada por esse commit. Não restaura um backend incompatível ou indisponível. Registar o commit do APIOps, a revisão do API Management e a versão do back-end que constituem cada implementação validada. Teste o procedimento completo de reversão num ambiente não produtivo, incluindo políticas, valores nomeados, referências a segredos, dependências e compatibilidade com o 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 Lista de verificação de revisão de design para segurança.

Use o repositório e o pipeline como caminho normal para aplicar alterações de Gestão de APIs. Os programadores e operadores não precisam de acesso persistente de escrita às instâncias de Gestão de APIs de produção. Conceder acesso elevado apenas quando necessário e apenas por tempo limitado. Reconcilie qualquer alteração resultante no repositório.

Use os seguintes mecanismos para proteger o repositório Git que armazena artefactos de Gestão de APIs:

• Revisão por pull request: Proteger os ramos que implementam a configuração e que exigem revisão pelos revisores apropriados.
• Isolamento de credenciais: Prefira identidade de carga de trabalho federada, se disponível. Armazenar segredos específicos do ambiente num ambiente de armazenamento ou repositório secreto aprovado, não em artefactos ou ficheiros de pipeline.
• Integridade dos commits: Exija commits assinados para confirmar a proveniência dos commits. Configurar proteções de ramificações para impedir submissões forçadas e a eliminação de ramificações, exigir autenticação multifator para que os utilizadores possam aprovar ou intercalar alterações e preservar o histórico de confirmações e de pedidos de integração para implementações.
• Revisão de artefactos: Inspecionar a saída da extração e publicar entradas para segredos, marcadores censurados e valores não intencionais específicos do ambiente. Validar que uma alteração não alarga o acesso à API nem enfraquece uma política.

Gerir a CLI APIOps como uma dependência de repositório. Fixe @azure-tools/apiops-cli numa versão testada em package.json, submeta o ficheiro de bloqueio e use npm ci. Revise as definições de identidade geradas, variáveis, gatilhos e regras de proteção antes de ativar um pipeline de produção.

Otimização de Custos

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

O APIOps CLI é software de código aberto, mas este cenário acarreta custos para as instâncias do API Management e para a plataforma de controlo de código-fonte e CI/CD selecionada. Não é fornecida uma única estimativa fixa porque os preços da API Management variam consoante a região, nível, número de unidades, modelo de capacidade, configuração de zonas de disponibilidade ou multirregional e utilização. Os custos de CI/CD também dependem do tipo de runner, dos minutos incluídos, da simultaneidade, do armazenamento e da retenção.

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

Entrada de estimativas	Suposição para registar
Região de Gestão de APIs	A região de implantação para cada instância de desenvolvimento, teste, pré-produção e produção.
Nível e capacidade	O tier ou tier v2, o número de unidades ou gateways e as horas de funcionamento para cada ambiente.
Resiliency	Qualquer destacamento em zona de disponibilidade ou região adicional, incluindo as unidades em cada local.
Encargos baseados na utilização	Solicitações ou operações previstas e quaisquer custos aplicáveis da área de trabalho, do gateway autoalojado, de rede, de monitorização ou de transferência de dados.
Plataforma CI/CD	Agentes alojados no GitHub, autoalojados ou do Azure Pipelines. Execuções esperadas do pipeline, duração, concorrência, armazenamento e retenção de logs ou artefactos.
Controlo de código-fonte e licenças	Número de utilizadores e quaisquer funcionalidades pagas do plano GitHub ou Azure DevOps.

Utilize os detalhes atuais de preços da API Management para selecionar o modelo de faturação aplicável. Para pressupostos sobre CI/CD e controlo de versão, veja preços do Azure DevOps e preços do GitHub. Exporte ou capture a estimativa da calculadora, a sua moeda, a data de preços e todas as suposições para que os revisores possam reproduzi-la e atualizá-la. Recalcule antes da implementação e sempre que as regiões, os escalões, o número de unidades, os ambientes ou a utilização do pipeline mudarem.

Excelência Operacional

A Excelência Operacional abrange os processos operacionais que implantam um aplicativo e o mantêm em execução na produção. Para obter mais informações, consulte Lista de verificação de revisão de design para excelência operacional.

O APIOps torna as implementações repetíveis e cria um histórico de commits para análise pós-alteração. Marcar ou registar de outra forma o commit que cada ambiente recebe, manter os logs do pipeline e monitorizar a instância de Gestão de API e as APIs dependentes após a implementação.

Para múltiplos ambientes, promova o mesmo commit de artefacto revisto através do desenvolvimento, staging e produção. Use sobreposições de ambiente apenas para valores que tenham de diferir entre ambientes e reveja esses ficheiros com o mesmo cuidado que os artefactos. As substituições de filhos do workspace não são aplicadas na altura da publicação, por isso não as uses para promoção do ambiente. Teste os procedimentos de rollback antes de ocorrer um incidente. Um revert Git ainda requer validação e uma publicação controlada para restaurar a Gestão da API.

A CLI fornece init, extract, e publish comandos e pode estruturar pipelines GitHub Actions ou Azure DevOps. Consulte os detalhes dos comandos na documentação da CLI do APIOps.

Migrar em segurança a partir do Kit de Ferramentas APIOps legado

Se o seu processo APIOps usar o antigo APIOps Toolkit, planeie atualizar. Esta abordagem utiliza binários separados para o Extractor e o Publisher, bem como modelos de pipeline. A CLI APIOps utiliza uma única Node.js CLI, mas o seu formato de artefacto foi concebido para ser compatível com artefactos existentes do toolkit. Trate a migração como uma transição controlada, não como uma atualização de produção no local.

1. Marque os artefactos validados do conjunto de ferramentas e o pipeline, e preserve o publicador existente como opção de reversão. Não altere o publicador antigo nem introduza o novo publicador na mesma implementação.

2. Numa ramificação de migração, use a versão mais recente da CLI APIOps e execute apiops init sem usar --force. O comando deteta ficheiros e saídas conflitantes em vez de os sobrescrever. Compare e integre de forma deliberada os pipelines gerados, as diretrizes de identidade, os filtros e os ficheiros de substituição.

3. Use os artefactos com apiops publish --dry-run e as sobrescrições do ambiente alvo contra uma instância de Gestão de API não produtiva. Revise os recursos que a CLI criaria, atualizaria ou eliminaria. Teste uma publicação controlada e valide as APIs implementadas, as políticas, os valores com nome e as dependências.

4. Não utilize substituições filhas do workspace, que não são aplicadas na altura da publicação, como parte do design da migração ou promoção. Validar uma abordagem alternativa de promoção para recursos filhos afetados, ou adiar a sua migração até que as propriedades de sobreposição no âmbito do Workspace não aplicadas sejam resolvidas.

5. Na transição, permita que apenas um publicador escreva numa instância de gestão de APIs. Desative o gatilho do editor legado antes de ativar o editor da CLI. Faz a implementação de um commit revisto e monitoriza o resultado. Mantém o pipeline marcado do Toolkit e a linha base de artefactos até que o novo fluxo de trabalho complete um ciclo de lançamento bem-sucedido.

Para detalhes de compatibilidade e exemplos de migração comando a comando, consulte Migração a partir do APIOps Toolkit.

Implementar este cenário

Siga a Documentação da CLI APIOps no repositório GitHub da APIOps CLI. Comece com uma instância de Gestão de API não produtiva e use as orientações atuais de lançamento da CLI APIOps. Para começar com um ambiente de não-produção, veja Como gerir a configuração de Gestão de APIs com API CLI.

Contribuidores

A Microsoft mantém este artigo. Os seguintes colaboradores escreveram este artigo.

Principais autores:

• Pat Altimore | Desenvolvedor Sénior de Conteúdos
• Wael Kdouh | Arquiteto Principal Sénior de Soluções
• Rishabh Saha | Arquiteto Principal Sénior de Soluções

Para ver perfis não públicos do LinkedIn, faça login no LinkedIn.

Próximos passos

• APIOps CLI
• Como gerir a configuração de Gestão de API com APIOps CLI
• Visão geral do GitOps

Recursos relacionados

• GitOps for Azure Kubernetes Service (AKS)
• Migre uma aplicação web utilizando a Gestão de APIs
• Proteja APIs usando o Gateway de Aplicativo do Azure e o Gerenciamento de API