Cómo gestionar la configuración de gestión de API con APIOps CLI

SE APLICA A: Todos los niveles de API Management

APIOps CLI es una herramienta de configuración como código para Azure API Management. En este artículo, lo usas para extraer la configuración de Gestión de APIs en artefactos locales, revisar los artefactos en Git, previsualizar cambios y publicar artefactos aprobados en una instancia de Gestión de API. La CLI también puede andamiar archivos de Acciones de GitHub o Azure Pipelines para un flujo de trabajo APIOps.

Los pasos proporcionan un flujo de trabajo mínimo que puedes validar con una instancia de gestión de API no productiva. Para orientación sobre arquitectura y diseño, véase Despliegues automatizados de API con APIOps.

Utiliza este flujo de trabajo para:

  • Revisa las definiciones de API, políticas y otras configuraciones de gestión de APIs mediante pull requests.
  • Lleva un historial auditable de los cambios de configuración aprobados.
  • Promueva artefactos revisados entre entornos de API Management.
  • Empieza con una configuración extraída de una instancia existente o crea artefactos compatibles con CLI en el código.

La CLI APIOps complementa los enfoques API DevOps descritos en Use DevOps y CI/CD para publicar APIs. Evalúa la CLI y el flujo de trabajo de artefactos que pretendes en un entorno no productivo antes de usarlo para despliegues en producción.

Prerequisites

  • Node.js versión 22 o posterior.
  • CLI de Azure, para los pasos de autenticación local en este artículo.
  • Una suscripción a Azure y una instancia existente de gestión de API no productiva.
  • Un repositorio Git para tus artefactos de gestión de API.
  • Una identidad con acceso a la instancia de Gestión de APIs. La guía de inicio de la CLI APIOps enumera los roles de Contribuidor y Lector del Servicio de Gestión de APIs en el ámbito de recursos de Gestión de APIs para su flujo de trabajo de extracción y publicación.

Para la automatización de la producción, utiliza identidades separadas y de menor privilegio cuando sea posible. Una identidad de extracción necesita acceso de lectura a la instancia de origen. Una identidad de publicación solo necesita los permisos necesarios para actualizar la instancia de destino.

Instalar APIOps CLI

Instale el @azure-tools/apiops-cli paquete npm:

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

Compruebe la versión instalada:

apiops --version

Registra y fija la versión que hayas aprobado para tus canalizaciones de CI/CD. Revisa el registro de cambios de la CLI de APIOps antes de actualizar.

Autenticación en Azure

Para uso local, inicia sesión con CLI de Azure y selecciona la suscripción que contiene tu instancia de gestión de API no productiva:

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

La CLI APIOps utiliza DefaultAzureCredential. Además de las credenciales de CLI de Azure, soporta credenciales de entorno, identidad de carga de trabajo, identidad gestionada, Azure PowerShell y credenciales de CLI de desarrollo de Azure.

Para CI/CD, se recomienda usar la federación de identidad de carga de trabajo o una identidad gestionada en lugar de un secreto de cliente. No incluyas credenciales, tokens de acceso, claves de suscripción ni valores con nombre secretos en el control de versiones. Para las opciones de autenticación compatibles, consulte la guía de autenticación de la CLI de APIOps.

Prepara un repositorio de artefactos

Ejecuta comandos de la CLI de APIOps desde la raíz del repositorio Git que contiene tus artefactos de gestión de API.

Para estructurar pipelines y plantillas de configuración para Acciones de GitHub, ejecuta:

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

Para Azure Pipelines, utilice:

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

El comando crea definiciones de canalización, una plantilla de filtro de extracción, plantillas de sobrescritura del entorno, una guía para configurar la identidad y un directorio apim-artifacts. Revisa cada archivo generado antes de hacer commit o habilitar un pipeline. No uses --force en un repositorio con archivos existentes a menos que revises los archivos que el comando sobrescribe.

Si ya tienes un repositorio y un diseño de pipeline, puedes crear o seleccionar un directorio de artefactos y usar directamente los comandos de extraer y publicar.

Crea los artefactos iniciales

Elige uno de los siguientes métodos para establecer los artefactos que posee tu repositorio.

Extraer la configuración existente

Para crear una línea base a partir de una instancia existente de Gestión de APIs, extrae su configuración:

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

El comando crea archivos de información JSON, archivos de políticas XML y archivos de especificaciones de API en una jerarquía bajo apim-artifacts. Para una instancia grande, configura un filtro de extracción para que el repositorio gestione solo los recursos previstos.

Comienza con artefactos de tipo code-first

Para un flujo de trabajo centrado en el código, añade una especificación OpenAPI y la información y los archivos de políticas necesarios de gestión de APIs utilizando el formato de artefacto de la CLI APIOps. No asumas que un diseño de repositorio de aplicaciones existente o un archivo OpenAPI por sí solo está listo para apiops publish.

Si eres nuevo en el formato de artefactos, extrae primero una pequeña API de referencia de una instancia que no esté en producción. Utiliza los archivos resultantes como plantillas y revisa la guía sobre el flujo de trabajo con enfoque code-first.

Revisa los artefactos

Antes de publicar:

  1. Inspecciona los archivos generados o creados y confirma que el repositorio contiene solo los recursos que pretendes gestionar.
  2. Revisa especificaciones de la API, políticas, backends, valores nombrados, productos y sus dependencias.
  3. Elimina valores específicos del entorno que no deberían moverse a otro entorno. Utiliza archivos revisados de sobrescritura del entorno o referencias a Azure Key Vault cuando corresponda.
  4. Busca credenciales y valores secretos. La extracción censura los campos secretos compatibles y los patrones de directiva reconocidos, pero es posible que no detecte todos los secretos incrustados. No subas secretos ni valores *** REDACTED *** sin resolver.
  5. Confirme los artefactos en una rama y utilice una solicitud de extracción para su validación y aprobación.

Vista previa de una publicación

Realiza una simulación en la instancia de destino de no producción. Una ejecución de prueba informa de las creaciones, actualizaciones y eliminaciones previstas sin aplicarlas:

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

Revisa la salida y resuelve cambios inesperados o dependencias ausentes. Una simulación satisfactoria no sustituye las pruebas del comportamiento de la API, las políticas, los permisos o la conectividad del backend.

Caution

No añadas --delete-unmatched a tu primer flujo de trabajo. Esa opción elimina recursos en la instancia de destino que no están representados en los artefactos fuente.

Publicar los artefactos revisados

Una vez aprobada la pull request y completada correctamente la ejecución de prueba, publica los mismos artefactos revisados en el destino de no producción:

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

Valida las APIs y políticas en la instancia objetivo después de publicar. Cuando automatizes este flujo de trabajo, configura la canalización para publicar un commit aprobado y protege los entornos de despliegue con las comprobaciones y aprobaciones requeridas por tu organización.

Pasos siguientes

  • Last updated on