Como gerir a configuração de Gestão de API com APIOps CLI

APLICA-SE A: Todas as camadas de gerenciamento de API

A APIOps CLI é uma ferramenta de configuração como código para o API Management do Azure. Neste artigo, utiliza-o para extrair a configuração da API Management em artefactos locais, rever os artefactos no Git, pré-visualizar alterações e publicar artefactos aprovados numa instância de API Management. A CLI também pode andamiar ficheiros GitHub Actions ou Azure Pipelines para um fluxo de trabalho APIOps.

Os passos fornecem um fluxo de trabalho mínimo que pode validar com uma instância de Gestão de API não produtiva. Para orientações de arquitetura e design, consulte Implementações automatizadas de APIs com APIOps.

Use este fluxo de trabalho para:

  • Revise definições de APIs, políticas e outras configurações de Gestão de APIs através de pull requests.
  • Mantém um histórico auditável das alterações de configuração aprovadas.
  • Promover artefactos revistos entre ambientes de gestão de APIs.
  • Comece com uma configuração extraída de uma instância existente ou crie artefactos compatíveis com CLI em 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 do artefacto pretendido num ambiente não de produção antes de o usar para implementações em produção.

Pré-requisitos

  • Node.js versão 22 ou posterior.
  • CLI do Azure, para os passos de autenticação local neste artigo.
  • Uma subscrição do Azure e uma instância existente de Gestão de API não produtiva.
  • Um repositório Git para artefactos de gestão de APIs.
  • Uma identidade com acesso à instância de Gestão de APIs. O guia de introdução da APIOps CLI lista as funções Contribuidor do Serviço API Management e Leitor no âmbito do recurso API Management para o respetivo 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 necessita apenas das permissões necessárias para atualizar a instância de destino.

Instalar APIOps CLI

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

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

Verifique a versão instalada:

apiops --version

Grava e fixa a versão que aprovas para os teus pipelines CI/CD. Revise o changelog da CLI do APIOps antes de atualizar.

Autenticar no Azure

Para uso local, inicie sessão com CLI do Azure e selecione a subscrição que contém a sua instância de Gestão de API não produtiva:

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

A CLI APIOps utiliza DefaultAzureCredential. Para além das credenciais CLI do Azure, suporta credenciais de ambiente, identidade de workload, identidade gerida, Azure PowerShell e credenciais de CLI para desenvolvedores Azure.

Para CI/CD, prefira a federação de identidades de carga de trabalho ou a identidade gerida em vez de um segredo de cliente. Nunca coloque credenciais, tokens de acesso, chaves de subscrição ou valores nomeados secretos no controlo de código-fonte. Para opções de autenticação suportadas, consulte o guia de autenticação da CLI APIOps.

Preparar um repositório de artefactos

Execute os comandos da CLI do APIOps na raiz do repositório Git que contém os artefactos de gestão de API.

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

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

Para os Azure Pipelines, utilize:

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 do ambiente, orientações para configuração de identidade e um apim-artifacts diretório. Revê todos os ficheiros gerados antes de confirmares ou ativares um pipeline. Não uses --force num repositório com ficheiros existentes a menos que revejas os ficheiros que o comando sobreescreve.

Se já tiver um repositório e design de pipeline, pode criar ou selecionar um diretório de artefactos e usar diretamente os comandos de extração e publicação.

Crie os artefactos iniciais

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

Extrair configuração existente

Para criar uma linha de base a partir de uma instância existente de Gestão de APIs, extraia a 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 ficheiros de informação JSON, ficheiros de políticas XML e ficheiros de especificação API numa hierarquia sob apim-artifacts. Para uma instância grande, configure um filtro de extração para que o repositório gere apenas os recursos pretendidos.

Comece com artefactos de código em primeiro lugar

Para um fluxo de trabalho centrado no código, adicione uma especificação OpenAPI e as informações e ficheiros de políticas necessários de Gestão de APIs utilizando o formato de artefacto CI APIOps. Não presuma que um layout de repositório de aplicações existente ou um ficheiro OpenAPI por si só está pronto para apiops publish.

Se és novo no formato de artefactos, extrai primeiro uma pequena API de referência de uma instância não produtiva. Use os ficheiros resultantes como modelos e reveja as orientações de fluxo de trabalho baseadas no código.

Revise os artefactos

Antes de publicar:

  1. Inspecione os ficheiros gerados ou criados e confirme que o repositório contém apenas os recursos que pretende gerir.
  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 devam ser movidos para outro ambiente. Utilize ficheiros de substituição do ambiente revistos ou referências do Azure Key Vault, quando adequado.
  4. Procure credenciais e valores secretos. A extração oculta os campos confidenciais suportados e os padrões de política reconhecidos, mas poderá não detetar todos os segredos incorporados. Não incluas segredos nem valores *** REDACTED *** por resolver.
  5. Compromete os artefactos numa branch e usa um pull request para validação e aprovação.

Pré-visualizar uma publicação

Execute uma simulação na instância de destino de não produção. Uma simulação indica as criações, atualizações e eliminações previstas sem as executar:

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

Verifique a saída e resolva alterações inesperadas ou dependências em falta. Uma execução experimental bem-sucedida não substitui os testes do comportamento da API, das políticas, das permissões nem da conectividade ao sistema de backend.

Caution

Não adiciones --delete-unmatched ao teu primeiro fluxo de trabalho. Essa opção elimina recursos na instância de destino que não estão representados nos artefactos de origem.

Publique os artefactos revistos

Depois de o pull request ser aprovado e a execução de teste ser bem-sucedida, publique os mesmos artefactos revistos no destino 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. Quando automatizar este fluxo de trabalho, configure o pipeline para publicar um commit aprovado e proteja os ambientes de implementação com as verificações e aprovações exigidas pela sua organização.

Passos seguintes

  • Last updated on