Como gerenciar a configuração de gerenciamento de API com APIOps CLI

APLICA-SE A: Todos os níveis do Gerenciamento de API

APIOps CLI é uma ferramenta de configuração como código para Gerenciamento de API do Azure. Neste artigo, você o usa para extrair a configuração de Gerenciamento de API em artefatos locais, revisar os artefatos no Git, pré-visualizar mudanças e publicar artefatos aprovados em uma instância de Gerenciamento de API. A CLI também pode gerar arquivos-base do GitHub Actions ou do Azure Pipelines para um fluxo de trabalho de APIOps.

As etapas fornecem um fluxo de trabalho mínimo que você pode validar com uma instância de gerenciamento de API não produtiva. Para orientações de arquitetura e design, veja Implantações automatizadas de APIs com APIOps.

Use esse fluxo de trabalho para:

  • Revise definições de API, políticas e outras configurações de gerenciamento de APIs por meio de pull requests.
  • Mantenha um histórico auditável das mudanças de configuração aprovadas.
  • Promover artefatos revisados entre ambientes de gerenciamento de APIs.
  • Comece com a configuração extraída de uma instância existente ou crie artefatos compatíveis com CLI no código.

A CLI APIOps complementa as abordagens DevOps da API descritas em Use DevOps e CI/CD para publicar APIs. Avalie a CLI e o fluxo de trabalho de artefatos pretendido em um ambiente não produtivo antes de usá-lo para implantações em produção.

Pré-requisitos

  • Node.js versão 22 ou posterior.
  • CLI do Azure, para as etapas de autenticação local neste artigo.
  • Uma assinatura do Azure e uma instância de gerenciamento de API não produtiva existente.
  • Um repositório Git para seus artefatos de gerenciamento de API.
  • Uma identidade com acesso à instância de gerenciamento de API. A orientação de introdução à CLI do APIOps lista as funções Colaborador do Serviço de Gerenciamento de API e Leitor no escopo do recurso API Management para o fluxo de trabalho de extração e publicação.

Para automação de produção, use identidades separadas e de menor privilégio sempre que possível. Uma identidade de extração precisa de acesso de leitura à instância de origem. Uma identidade de publicação precisa apenas das permissões necessárias para atualizar a instância de destino.

Instalar a CLI do APIOps

Instale o pacote npm @azure-tools/apiops-cli:

npm install -g @azure-tools/apiops-cli

Verifique a versão instalada:

apiops --version

Registre e fixe a versão que você aprova nos seus pipelines de CI/CD. Revise o changelog da CLI do APIOps antes de atualizar.

Autenticar no Azure

Para uso local, faça login com CLI do Azure e selecione a assinatura que contém sua instância de gerenciamento de API não produtiva:

az login
az account set --subscription <subscription-id>

A CLI do APIOps usa DefaultAzureCredential. Além das credenciais CLI do Azure, ele suporta credenciais de ambiente, identidade de workload, identidade gerenciada, Azure PowerShell e credenciais de CLI para desenvolvedores do Azure.

Para CI/CD, prefira federação de identidade de carga de trabalho ou identidade gerenciada em vez de um segredo de cliente. Nunca coloque credenciais, tokens de acesso, chaves de assinatura ou valores secretos nomeados no controle de versão. Para opções de autenticação compatíveis, consulte o guia de autenticação do APIOps CLI.

Prepare um repositório de artefatos

Execute comandos de CLI APIOps a partir da raiz do repositório Git que contém seus artefatos de gerenciamento de API.

Para gerar pipelines e modelos de configuração para GitHub Actions, execute:

apiops init --ci github-actions --environments dev,prod --non-interactive

For Azure Pipelines, use:

apiops init --ci azure-devops --environments dev,prod --non-interactive

O comando cria definições de pipeline, um modelo de filtro de extração, modelos de substituição de ambiente, orientações para configurar a identidade e um diretório apim-artifacts. Revise cada arquivo gerado antes de fazer commit ou ativar um pipeline. Não use --force em um repositório com arquivos existentes a menos que revise os arquivos que o comando sobrescreve.

Se você já tem um repositório e um projeto de pipeline, pode criar ou selecionar um diretório de artefato e usar os comandos de extração e publicação diretamente.

Crie os artefatos iniciais

Escolha uma das seguintes abordagens para estabelecer os artefatos que seu repositório possui.

Extrair configuração existente

Para criar uma linha de base a partir de uma instância existente de Gerenciamento de API, extraia sua configuração:

apiops extract \
  --subscription-id <source-subscription-id> \
  --resource-group <source-resource-group> \
  --service-name <source-apim-name> \
  --output ./apim-artifacts

O comando cria arquivos de informação JSON, arquivos de políticas XML e arquivos de especificação de API em uma hierarquia sob apim-artifacts. Para uma instância grande, configure um filtro de extração para que o repositório gerencie apenas os recursos pretendidos.

Comece com artefatos baseados em código

Para um fluxo de trabalho centrado no código, adicione uma especificação OpenAPI e as informações e arquivos de políticas de gerenciamento de API necessários usando o formato de artefato da CLI APIOps. Não presuma que um layout de repositório de aplicações existente ou um arquivo OpenAPI isolado está pronto para apiops publish.

Se você ainda não conhece o formato de artefato, extraia primeiro uma pequena API de referência de uma instância de não produção. Use os arquivos resultantes como modelos e revise as orientações de fluxo de trabalho baseadas no código.

Revise os artefatos

Antes de publicar:

  1. Inspecione os arquivos gerados ou criados e confirme que o repositório contém apenas os recursos que você pretende gerenciar.
  2. Revise especificações da API, políticas, backends, valores nomeados, produtos e suas dependências.
  3. Remova valores específicos do ambiente que não deveriam se mover para outro ambiente. Use arquivos de substituição de ambiente revisados ou referências ao Azure Key Vault quando apropriado.
  4. Pesquise por credenciais e valores secretos. A extração oculta campos secretos suportados e padrões de política reconhecidos, mas pode não detectar todos os segredos incorporados. Não cometa segredos ou valores não resolvidos *** REDACTED *** .
  5. Comprometa os artefatos em um branch e use um pull request para validação e aprovação.

Visualizar uma publicação

Faça um teste geral contra a instância alvo não produtiva. Uma execução de teste informa as criações, atualizações e exclusões planejadas sem aplicá-las:

apiops publish \
  --subscription-id <target-subscription-id> \
  --resource-group <target-resource-group> \
  --service-name <target-apim-name> \
  --source ./apim-artifacts \
  --dry-run

Revise a saída e resolva mudanças inesperadas ou dependências ausentes. Uma simulação bem-sucedida não substitui os testes do comportamento da API, das políticas, das permissões nem da conectividade com o backend.

Caution

Não adicione --delete-unmatched ao seu primeiro fluxo de trabalho. Essa opção exclui recursos na instância de destino que não estão representados nos artefatos de origem.

Publique os artefatos revisados

Após a aprovação do pull request e o sucesso da execução de teste, publique os mesmos artefatos revisados no ambiente de não produção:

apiops publish \
  --subscription-id <target-subscription-id> \
  --resource-group <target-resource-group> \
  --service-name <target-apim-name> \
  --source ./apim-artifacts

Valide as APIs e políticas na instância de destino após a publicação. Ao automatizar esse fluxo de trabalho, configure o pipeline para publicar um commit aprovado e proteja os ambientes de implantação com as verificações e aprovações exigidas pela sua organização.

Próximas Etapas 

  • Última atualização em