Automatización de la configuración de API Management mediante la CLI de APIOps

Azure API Management

Azure DevOps

Azure Pipelines

GitHub

APIOps es una metodología que aplica los conceptos de GitOps y DevOps a la implementación de API. Esta arquitectura muestra cómo usar la herramienta de línea de comandos APIOps CLI para extraer, revisar y pasar la configuración de Azure API Management mediante un flujo de trabajo basado en Git. Use este enfoque para administrar el ciclo de vida de la API, mejorar la calidad de la API y mantener un registro auditable de los cambios aprobados.

Arquitectura

El siguiente diagrama ilustra el flujo de trabajo general para la promoción de la configuración de APIOps CLI. Los equipos revisan los artefactos de API Management en Git y, a continuación, las canalizaciones de integración continua y entrega continua (CI/CD) llevan la configuración aprobada a los entornos de destino de API Management.

Descargue un archivo Visio de esta arquitectura.

Flujo de trabajo

La configuración de API Management se inicia mediante la extracción de una configuración de API Management existente o mediante la creación de artefactos de API Management compatibles con la CLI. El flujo de trabajo operativo comienza con cualquiera de estos artefactos de entrada. Ambas rutas de acceso conducen al mismo proceso de solicitud de incorporación de cambios, validación, aprobación e implementación:

(A) Extraer primero: un operador de API ejecuta apiops extract en una instancia existente de API Management para crear archivos de artefactos de API Management en su rama local extraída de Git. El operador usa estos artefactos para proponer una línea base o capturar un cambio de configuración aprobado.
(B) Code-first: Un desarrollador de API redacta o actualiza especificaciones de API compatibles con la CLI de APIOps, archivos de información, directivas y artefactos relacionados de API Management en su rama local de Git.

Use el siguiente ciclo de vida para cualquiera de las entradas:

Cree un cambio de configuración. Después de la extracción inicial o del registro en el repositorio de la creación de artefactos mediante el enfoque code-first, el repositorio de configuración de la API se convierte en la fuente autorizada para los artefactos de configuración de API Management. El repositorio mantiene el historial de versiones y el registro de auditoría de cada implementación. Para realizar un cambio, un operador de API o desarrollador crea una rama a partir de la rama protegida en el repositorio de configuración de API y realiza un cambio lógico relacionado con la API.
Revise y valide el cambio. El operador o desarrollador abre una solicitud de incorporación de cambios para combinar su rama en una rama protegida. Los propietarios y revisores designados del contrato de la API, las directivas y la configuración de API Management revisan la solicitud de incorporación de cambios. El sistema CI/CD ejecuta las siguientes comprobaciones y pruebas:
- Validación de especificaciones de API
- Detección de cambios incompatibles con respecto al contrato aprobado
- Examen de seguridad de especificaciones y contenido del repositorio
- Pruebas de API que comprueban el comportamiento esperado, la autenticación, los efectos de la directiva y las dependencias de back-end
Estas comprobaciones no requieren herramientas de Microsoft. El equipo usa las herramientas adecuadas que cumplan los requisitos de soporte técnico, seguridad y licencias de su organización.
Apruebe el parámetro de entrada inmutable de la implementación. Los propietarios o revisores necesarios aprueban la solicitud de incorporación de cambios y un mantenedor de repositorio autorizado combina los cambios revisados después de que se superen todas las comprobaciones y revisiones necesarias. El commit fusionado e inmutable y los artefactos de la rama protegida se convierten en la fuente auditable de referencia del repositorio.

El equipo protege las ramas de repositorio protegidas de inserciones directas, requiere aprobaciones de entorno o conexión de servicio para destinos confidenciales y usa identidades independientes con privilegios mínimos para la extracción y publicación. Registran el commit aprobado junto con su solicitud de extracción, las revisiones y los resultados de validación para fines de auditoría.
Obtenga una vista previa de la implementación. La canalización de CI/CD ejecuta apiops publish --dry-run para el commit aprobado usando el mismo destino y el archivo de invalidación sin publicar. El responsable de aprobar la versión revisa los recursos que la ejecución en seco crea, actualiza, elimina u omite. El equipo trata una ejecución seca correcta como una puerta de implementación, no un sustituto de las pruebas automatizadas de API.
Publicar y promover. Una vez que la simulación supera la validación, la canalización de CI/CD usa apiops publish para publicar el mismo commit revisado. En varios entornos, el equipo de plataforma mantiene estables los artefactos compartidos y utiliza archivos de configuración de sustitución revisados para valores como las URL del back-end, los identificadores de recursos y las referencias a secretos. El equipo promueve el commit por los entornos no productivos antes de llegar a producción y evita que más de un pipeline escriba en el mismo destino al mismo tiempo.

Note

La configuración acepta invalidaciones secundarias del área de trabajo, pero no las aplica al publicar. La publicación solo aplica invalidaciones al propio contenedor del área de trabajo. No confíe en las invalidaciones secundarias del área de trabajo para promover API del área de trabajo específicas del entorno, backends, valores con nombre u otros recursos secundarios. Valida un método alternativo de promoción para esos recursos, o pospón la promoción hasta que se resuelva el problema conocido de propiedades de reemplazo con ámbito de espacio de trabajo no aplicadas.
Valide y concilie después de la implementación. Después de la publicación, el equipo de operaciones ejecuta pruebas automatizadas de humo y regresión, supervisa API Management y el estado del back-end y compara el resultado implementado con la confirmación aprobada. El equipo investiga y resuelve cambios inesperados a través de solicitudes de incorporación de cambios en lugar de editar la producción directamente.

Si un operador de API realiza un cambio de emergencia aprobado directamente en API Management, debe ejecutar una extracción en una copia de trabajo de Git, revisar y hacer commit del cambio del artefacto en su rama, enviar la rama y abrir una solicitud de incorporación de cambios. Los propietarios o revisores necesarios deben revisar y aprobar la solicitud de extracción, y un mantenedor autorizado del repositorio debe fusionarla para que el repositorio siga siendo la fuente autorizada.

Componentes

API Management es un servicio administrado que crea puertas de enlace de API coherentes para los servicios back-end. En esta arquitectura, proporciona las configuraciones de origen que extrae la CLI de APIOps y los entornos de destino donde la CLI publica definiciones de API aprobadas, directivas, productos, diagnósticos, valores con nombre y otra configuración admitida.
APIOps CLI es un proyecto de código abierto que proporciona herramientas para un enfoque de APIOps predefinido. En esta arquitectura, extrae la configuración de API Management a archivos de artefacto, publica artefactos en API Management y puede generar la estructura base de flujos de trabajo de CI/CD.
Un repositorio de Git almacena artefactos de API Management y, si procede, contratos de API. Proporciona el historial de revisión y el origen de verdad aprobado para las implementaciones de canalización.
Un sistema de CI/CD ejecuta la validación, extracción y publicación mediante una identidad de carga de trabajo u otras credenciales no interactivas admitidas. En esta arquitectura, Acciones de GitHub o Azure Pipelines definen los flujos de trabajo de CI/CD.

Alternativas

Puede sustituir o aumentar esta arquitectura con otros servicios o enfoques de Azure, en función de los requisitos funcionales y no funcionales de la carga de trabajo. Tenga en cuenta las siguientes alternativas y desventajas.

Bicep o Terraform y APIOps pueden servir diferentes partes de la misma solución. Un equipo propietario de la configuración y la infraestructura de API Management puede usar la infraestructura como código (IaC) para aprovisionar el servicio API Management y su infraestructura auxiliar, y usar la misma canalización de IaC para administrar la configuración de API Management. Elija este enfoque cuando la infraestructura y la configuración cambien e implementen juntas, y cuando los parámetros pueden expresar las diferencias entre entornos.

Use el patrón APIOps cuando las definiciones de API, las directivas y la configuración relacionada tengan propietarios independientes o un ciclo de vida de versión independiente de la infraestructura de servicio. APIOps también es adecuado cuando necesita extraer la configuración existente, revisar los artefactos centrados en la API o promover la misma configuración aprobada en varios entornos o instancias de API Management. Los cambios de API y directivas más frecuentes o más entornos aumentan el valor de este flujo de trabajo dedicado.

Estos factores no tienen umbrales fijos. Base la decisión principalmente sobre la propiedad, revise los requisitos y los límites de implementación. Para un entorno de API más pequeño y con un bajo ritmo de cambios, comience con un flujo de trabajo manual de pull requests y añada extracciones programadas o automatización del despliegue solo después de que se hayan establecido la línea base del repositorio y el proceso de aprobación.

Detalles del escenario

APIOps usa el control de versiones para administrar las API y crear una pista de auditoría de cambios en definiciones de API, directivas, productos, diagnósticos y otra configuración de API Management. Revisar los cambios anteriormente y con más frecuencia ayuda a los equipos a identificar las desviaciones de los estándares de API antes de la implementación. A medida que más API usan el mismo proceso, los equipos pueden mejorar la coherencia en su patrimonio de API.

Este flujo de trabajo implementa la configuración de API Management en una instancia de API Management. No implementa back-ends de API, recursos de proceso de aplicaciones o datos, redes ni la infraestructura del servicio API Management. Utilice procesos independientes y gobernados de IaC y de aplicación para desplegar esas capas.

Esta solución ayuda a los equipos a:

Mantenga una visión general de los entornos y de las instancias de API Management.
Realice un seguimiento de los cambios críticos en las API y las directivas.
Cree una pista de auditoría para las implementaciones aprobadas.
Conciliar los cambios aprobados que se originan fuera del repositorio.

Elección de orígenes de artefactos y propiedad

Elija entre las siguientes formas en que los artefactos entran en el repositorio y quién los posee antes de automatizar la implementación:

Extraer primero: Extraiga una instancia válida de API Management para establecer la línea base inicial de artefactos. Revise los artefactos generados incorporados al repositorio antes de considerar el repositorio como el origen de referencia.
Code-first: Mantenga el contrato de API, como una descripción de OpenAPI, con el origen de la aplicación o el repositorio de APIOps. Defina quién transforma ese contrato en los artefactos de API Management que la canalización publica. Valide el flujo de trabajo de importación y artefacto previsto con una instancia de API Management que no sea de producción. No suponga que una estructura de origen arbitraria pueda ser procesada directamente por la CLI.
Responsabilidad compartida: Establezca si los desarrolladores de API, los operadores de la plataforma o ambos son responsables de los cambios en las directivas, los productos, el diagnóstico, los valores con nombre y las definiciones de API. Una vez aceptada la línea base, enrute cada cambio a través del mismo repositorio y revise el proceso.

Posibles casos de uso

Organizaciones que desarrollan y administran API, incluidas las organizaciones con una sola API expuesta a través de API Management.
Sectores altamente regulados, como seguros, banca, finanzas y gobierno que necesitan registros de revisión y implementación rastreables.

Consideraciones

Estas consideraciones implementan los pilares del marco de Azure Well-Architected, que es un conjunto de principios rectores que puede usar para mejorar la calidad de una carga de trabajo. Para obtener más información, consulte Well-Architected Framework.

Reliability

La confiabilidad ayuda a garantizar que la aplicación pueda cumplir los compromisos que realice para sus clientes. Para obtener más información, vea Lista de verificación para la revisión del diseño en términos de confiabilidad.

Para los cambios no disruptivos en la API, use las revisiones de API Management para implementar y probar una revisión que no es la actual antes de convertirla en la actual. Si se produce un error en la validación después de la versión, restaure la revisión anterior como actual. Use versiones de API para interrumpir los cambios de contrato para que los consumidores existentes puedan seguir usando la versión anterior.

Coordinar los cambios de configuración de API Management con la estrategia de implementación para cada back-end de API. La reversión de una confirmación de APIOps solo restaura la configuración representada por esa confirmación. No restaura un backend incompatible o no disponible. Registre la confirmación de APIOps, la revisión de API Management y la versión de back-end que forman cada implementación correcta conocida. Pruebe el procedimiento de reversión completo en un entorno que no sea de producción, incluidas las directivas, los valores con nombre, las referencias secretas, las dependencias y la compatibilidad de back-end.

Seguridad

La seguridad proporciona garantías contra ataques deliberados y el uso indebido de datos y sistemas valiosos. Para obtener más información, consulte Lista de comprobación de revisión de diseño para seguridad.

Use el repositorio y la canalización como ruta de acceso normal para aplicar los cambios de API Management. Los desarrolladores y operadores no necesitan acceso de escritura persistente a las instancias de API Management de producción. Conceda acceso elevado solo cuando sea necesario y solo durante un tiempo limitado. Concilie cualquier cambio resultante en el repositorio.

Use los siguientes mecanismos para proteger el repositorio de Git que almacena artefactos de API Management:

Revisión de la solicitud de incorporación de cambios: proteja las ramas que implementan la configuración y requieran la revisión de los revisores adecuados.
Aislamiento de credenciales: Use preferentemente la identidad federada de carga de trabajo si está disponible. Almacene secretos específicos del entorno en un entorno de repositorio o almacén de secretos aprobado, no en artefactos ni archivos de canalización.
Integridad de los commits: Exigir commits firmados para verificar la procedencia del commit. Configure protecciones de ramas para evitar los envíos forzados y la eliminación de ramas, exija autenticación multifactor para que los usuarios aprueben o fusionen cambios y preserve el historial de commit y solicitudes de incorporación de cambios para las implementaciones.
Revisión de artefactos: Inspeccione la salida de extracción y publique entradas para secretos, marcadores censurados y valores específicos del entorno no deseados. Compruebe que un cambio no amplía el acceso a la API ni debilita una directiva.

Administre la CLI de APIOps como una dependencia de repositorio. Fije @azure-tools/apiops-cli en package.json a una versión probada, registre el archivo de bloqueo y use npm ci. Revise la configuración de identidad generada, las variables, los desencadenadores y las reglas de protección antes de habilitar una canalización de producción.

Optimización de costos

La optimización de costos se centra en formas de reducir los gastos innecesarios y mejorar las eficiencias operativas. Para obtener más información, consulte Lista de comprobación de revisión de diseño para la optimización de costos.

La CLI de APIOps es software de código abierto, pero este escenario conlleva costos para las instancias de API Management y la plataforma de CI/CD y el control de código fuente seleccionado. No se proporciona una única estimación fija porque los precios de API Management varían según la región, el nivel, el recuento de unidades, el modelo de capacidad, la configuración de la zona de disponibilidad o la configuración de varias regiones y el uso. Los costes de CI/CD también dependen del tipo de ejecutor, los minutos incluidos, la simultaneidad, el almacenamiento y la retención.

Cree una estimación específica del escenario en la calculadora de precios de Azure y registre las siguientes suposiciones con la decisión de arquitectura:

Estimación de la entrada	Suposición de registro
Región de API Management	Región de implementación para cada instancia de desarrollo, prueba, ensayo y producción.
Nivel y capacidad	El nivel o el nivel v2, el número de unidades o puertas de enlace y las horas de funcionamiento de cada entorno.
Resiliency	Cualquier implementación de zona de disponibilidad o región adicional, incluidas las unidades de cada ubicación.
Cargos basados en uso	Solicitudes o operaciones esperadas y cualquier área de trabajo aplicable, puerta de enlace autohospedada, redes, supervisión o cargos de transferencia de datos.
Plataforma de CI/CD	Agentes hospedados en GitHub, autohospedados o de Azure Pipelines. Ejecuciones de canalización esperadas, duración, simultaneidad, almacenamiento y retención de registros o artefactos.
Control de código fuente y licencias	Número de usuarios y las características de plan de GitHub o Azure DevOps de pago.

Use los detalles de precios actuales de API Management para seleccionar el modelo de facturación aplicable. Para conocer las suposiciones de CI/CD y de control de código fuente, consulte Azure DevOps precios y precios de GitHub. Exporte o capture la estimación de la calculadora, su moneda, la fecha de precios y todas las suposiciones para que los revisores puedan reproducirla y actualizarla. Volver a calcular antes del despliegue y cuando cambien las regiones, los niveles, el número de unidades, los entornos o el uso de la canalización.

Excelencia operativa

La excelencia operativa abarca los procesos de las operaciones que implementan una aplicación y la mantienen en ejecución en producción. Para obtener más información, consulte Lista de comprobación de revisión de diseño para la excelencia operativa.

APIOps hace repetibles las implementaciones y crea un historial de confirmaciones para el análisis posterior al cambio. Etiquete o registre de otro modo el commit que recibe cada entorno, conserve los registros de la canalización y supervise la instancia de API Management y las API de las que depende después de la implementación.

En el caso de varios entornos, promueva el mismo commit de artefacto revisado a través del desarrollo, el almacenamiento provisional y la producción. Utilice anulaciones por entorno solo para los valores que deben diferir entre entornos, y revise esos archivos con el mismo cuidado que los artefactos. Las invalidaciones secundarias del área de trabajo no se aplican al publicar, así que no las utilice para promocionar entornos. Pruebe los procedimientos de reversión antes de que se produzca un incidente. Una reversión de Git todavía requiere validación y una publicación controlada para restaurar API Management.

La CLI proporciona los comandos init, extract y publish y puede generar canalizaciones de Acciones de GitHub o de Azure DevOps. Revise los detalles del comando en la documentación de la CLI de APIOps.

Migración segura desde el kit de herramientas de APIOps heredado

Si el proceso de APIOps usa el kit de herramientas de APIOps heredado, planee la actualización. Ese enfoque usa binarios independientes de Extractor y Publisher y plantillas de canalización. La CLI de APIOps usa una sola CLI de Node.js, pero su formato de artefacto está diseñado para ser compatible con los artefactos del kit de herramientas existentes. Trate la migración como una migración controlada, no como una actualización de producción local.

Etiquete los artefactos validados del kit de herramientas y la canalización, y conserve el publicador existente como opción de reversión. No cambie el publicador heredado ni introduzca el nuevo publicador en el mismo despliegue.
En una rama de migración, use la versión más reciente de la CLI de APIOps y ejecute apiops init sin usar --force. El comando detecta archivos en conflicto y sale en lugar de sobrescribirlos. Compare e integre deliberadamente las canalizaciones generadas, las directrices de identidad, los filtros y los archivos de invalidación.
Use los artefactos con apiops publish --dry-run y las invalidaciones del entorno de destino en una instancia de API Management que no sea de producción. Revise los recursos que la CLI crearía, actualizaría o eliminaría. Pruebe una publicación controlada y valide las API implementadas, las directivas, los valores con nombre y las dependencias.
No utilice invalidaciones secundarias del área de trabajo, que no se aplican en el momento de la publicación, como parte del diseño de la migración o promoción. Validar un método alternativo de promoción para los recursos secundarios afectados, o posponer su migración hasta que se resuelva el problema conocido Propiedades de sobrescritura con ámbito de área de trabajo no aplicadas.
Durante la transición, permita que solo un editor escriba en una instancia de API Management. Deshabilite el desencadenador del publicador heredado antes de habilitar el publicador de la CLI. Despliegue un commit revisado y monitorice el resultado. Mantenga el pipeline de Toolkit etiquetado y la línea base del artefacto hasta que el nuevo flujo de trabajo complete con éxito un ciclo de lanzamiento.

Para obtener detalles de compatibilidad y ejemplos de migración de comandos por comando, consulte Migración desde APIOps Toolkit.

Implementación de este escenario

Siga la documentación de la CLI de APIOps en el repositorio de GitHub de la CLI de APIOps. Comience con una instancia de API Management que no sea de producción y use la guía de versión de la CLI de APIOps actual. Para empezar a trabajar con un entorno que no es de producción, consulte Administración de la configuración de API Management con la CLI de APIOps.

Colaboradores

Microsoft mantiene este artículo. Los siguientes colaboradores escribieron este artículo.

Autores principales:

Pat Altimore | Desarrollador de contenido sénior
Wael Kdouh | Arquitecto de soluciones principal sénior
Rishabh Saha | Arquitecto de soluciones principal sénior

Para ver los perfiles no públicos de LinkedIn, inicie sesión en LinkedIn.

Pasos siguientes

Comentaris

Us ha resultat útil aquesta pàgina?