¿Qué hay de nuevo en ADC 0.8, 0.9 y 0.10?

Introducción

ADC (APISIX Declarative CLI) es una herramienta de configuración declarativa introducida por API7.ai, que proporciona un conjunto de herramientas conveniente para que los usuarios implementen GitOps. Los usuarios pueden integrarlo fácilmente en sus pipelines de CI/CD para gestionar el ciclo de vida completo de las API, completando las actualizaciones y lanzamientos de las API. Después del lanzamiento de la versión 0.7, ADC ha lanzado tres nuevas versiones: 0.8, 0.9 y 0.10, con optimizaciones y actualizaciones en términos de funcionalidad, rendimiento y experiencia de usuario.

Nuevas Funcionalidades de ADC

Mejoras en el Detector de Cambios de Recursos: Differ

Estas modificaciones se introdujeron en las versiones 0.8 y 0.9.

Hemos introducido una nueva versión del detector de cambios de recursos Differ, v3, que tiene mejoras significativas en funcionalidad y calidad de código.

El nuevo Differ introduce un mecanismo de fusión de valores predeterminados para los recursos locales, asegurando que los valores predeterminados del lado del servidor no interfieran con las comprobaciones de cambios de recursos de ADC.

Cuando el cliente envía una solicitud para crear un recurso en la API de API7 o APISIX Admin, el servidor realiza una validación de Schema en la solicitud enviada. Durante este proceso, algunos campos que tienen valores predeterminados marcados en el Schema pero que no son enviados por el cliente se añaden automáticamente al recurso enviado. Como resultado, cuando leemos el recurso desde la API nuevamente, será diferente de la presentación inicial.

Las versiones anteriores de ADC listarían estos recursos como "modificados" y enviarían solicitudes de actualización de API a la API de Admin. Este comportamiento introdujo cierta incertidumbre para ADC, y este problema se ha resuelto mediante Differ.
El mecanismo de fusión de valores predeterminados se ha implementado en el backend de API7, asegurando que las diferencias de recursos solo se consideren como modificaciones cuando el usuario ha cambiado la configuración local en YAML.
Se ha refinado la granularidad de detección de Differ: ADC actualmente realiza comprobaciones de cambios de recursos por separado en las dimensiones del cuerpo del recurso y los plugins, ayudando a reducir anomalías en la comprobación.
Se ha optimizado la calidad del código, simplificando código redundante para mejorar la legibilidad y corrigiendo algunos errores.

Filtros de Recursos

Hemos añadido dos mecanismos de filtrado de recursos basados en etiquetas de recursos y tipos de recursos. Pueden usarse para excluir recursos innecesarios durante las operaciones de obtención, comprobación de diferencias y sincronización.

Filtro de Etiquetas de Recursos

Esta funcionalidad se introdujo en la versión 0.8.

Este filtro realiza el filtrado basado en el campo labels de los recursos. Los usuarios pueden habilitar el filtro usando el parámetro --label-selector key=value en la línea de comandos. Soporta la configuración de múltiples condiciones de filtrado, y solo los recursos remotos que cumplan simultáneamente estas reglas serán considerados como existentes, mientras que los recursos locales se añadirán automáticamente con estas etiquetas.

Esto asegura que realizamos comprobaciones y sincronización de recursos dentro de un ámbito reducido, ayudando a dividir las tareas ejecutadas en el pipeline de CI/CD y previniendo que una sincronización accidental dañe recursos que no necesitan ser modificados.

Filtro de Tipo de Recurso

Esta funcionalidad se introdujo en la versión 0.9.

Añadimos dos nuevos parámetros de línea de comandos: --include-resource-type <type> y --exclude-resource-type <type>, que pueden configurarse múltiples veces, pero los parámetros de inclusión y exclusión son mutuamente excluyentes.

Con estos dos parámetros, podemos filtrar tipos de recursos específicos de la operación actual. Por ejemplo, usar include-resource-type puede usarse para establecer una lista blanca y seleccionar los tipos de recursos a incluir en la operación; mientras que exclude-resource-type determinará los tipos de recursos a excluir de la operación.

Esto nos ayuda a manejar mejor recursos que no necesitan ser cambiados frecuentemente, como los metadatos de plugins y las reglas globales de plugins.

Mejoras en la Línea de Comandos

Estas mejoras se introdujeron en la versión 0.9.

Configuración de Certificados TLS

Hemos añadido una serie de parámetros relacionados con TLS en la línea de comandos, como:

--ca-cert-file para especificar el archivo de certificado CA del servidor
--tls-skip-verify para deshabilitar la verificación del certificado del servidor TLS
--tls-client-cert-file y --tls-client-key-file para especificar los archivos de certificado de cliente mTLS

Estos parámetros ayudan a ADC a establecer una conexión cifrada segura y prevenir ataques de intermediario.

Control de Tiempo de Espera

Hemos añadido el parámetro --timeout <duration> para controlar la duración del tiempo de espera de las llamadas API, soportando sintaxis como 1m30s. Cuando una llamada a la API de Admin tarda demasiado o se atasca, el mecanismo de tiempo de espera entrará en efecto para evitar que espere indefinidamente.

Modo de Depuración

Esta funcionalidad se introdujo en la versión 0.9.

Cuando ADC realiza operaciones de recursos internamente, necesita llamar a un gran número de APIs. A veces podemos necesitar revisar estas llamadas API para analizar si se están enviando correctamente o para verificar que las respuestas del servidor cumplen con las expectativas. Aunque se puede usar captura de paquetes para lograr esto, la operación no es conveniente, y hay dificultades significativas cuando TLS está habilitado.

Por lo tanto, hemos añadido un modo de depuración integrado en ADC, que puede habilitarse usando el parámetro --verbose <integer>. Cuando este parámetro se establece en 2, ADC imprimirá las partes de solicitud y respuesta de cada llamada API interna para ayudar en la depuración.

Este parámetro también puede usarse para ocultar registros. Cuando este parámetro se establece en 0, ADC ocultará todos los registros generales excepto los errores.

Fortalecimiento del Procesamiento de Recursos Remotos

Esta funcionalidad se introdujo en la versión 0.9.

Dado que ADC no es la única forma de configurar servicios, rutas, etc., los usuarios también pueden usar el panel de control de API7 Enterprise para lograrlo mediante operaciones simples. Esto ha llevado a un problema: las operaciones en el panel de control usarán IDs de recursos generados aleatoriamente, mientras que ADC usa el nombre del recurso en la configuración YAML para generar un ID de recurso fijo para la ubicación precisa del recurso.

Esto significa que si el usuario crea un recurso en el panel de control, ADC no podrá ubicarlo por el ID del recurso. ADC no puede modificar o eliminar los recursos creados en el panel de control, pero estos recursos aún aparecerán en la detección de cambios, pero no se podrán operar correctamente.

Por lo tanto, hemos optimizado la lógica relevante del backend de API7 ADC. Si tanto el remoto como el local contienen recursos con el mismo nombre, pero los IDs no coinciden, ADC puede eliminar correctamente el recurso remoto y crear uno nuevo basado en la configuración local, en cuyo caso el ID será generado por ADC basado en el nombre del recurso y puede usarse para la búsqueda posterior de recursos. Los usuarios del panel de control de API7 no se verán afectados, y los recursos creados por ADC aún pueden verse en el panel de control.

Soporte de Campos de Extensión ADC en el Convertidor OpenAPI

Esta funcionalidad se introdujo en la versión 0.10.

Para construir un pipeline coherente desde OpenAPI a ADC a API7, el convertidor OpenAPI necesita inyectar los campos requeridos en el archivo de configuración YAML de ADC basado en nuestras necesidades.

Por ejemplo, para modificar el campo pass_host en el upstream del servicio, anteriormente solo podíamos usar manualmente el convertidor para convertir el OpenAPI al archivo de configuración de ADC, modificar manualmente el campo pass_host, y luego enviar el archivo modificado al repositorio Git para que el pipeline de CI/CD ejecute la sincronización de ADC. Este proceso no es coherente y requiere mucha intervención manual.

Ahora, a través de las extensiones x-adc introducidas, los usuarios solo necesitan escribir los campos de extensión en ubicaciones específicas del documento OpenAPI, y ADC escribirá correctamente estos campos en el archivo de configuración generado. Con estas extensiones, los usuarios pueden modificar directamente cualquier contenido en la configuración de ADC en el OpenAPI, como añadir etiquetas, añadir plugins, y anular la configuración predeterminada de servicios/upstreams/rutas.

Como resultado, al mantener solo un archivo OpenAPI, el pipeline OpenAPI-ADC-API7 puede implementarse de manera integral, simplificando enormemente el flujo de trabajo de GitOps para la configuración de la puerta de enlace de API.

Conclusión

La herramienta de configuración declarativa ADC lanzada por API7.ai puede ayudar a las empresas a realizar la gestión GitOps de puertas de enlace de API. En las nuevas versiones 0.8, 0.9 y 0.10, la herramienta ha sido optimizada y actualizada funcionalmente, añadiendo características como la monitorización y filtrado de cambios de recursos. Estas nuevas funcionalidades inyectan un nuevo impulso a la gestión del ciclo de vida completo de las API.

Estas nuevas capacidades permiten a ADC satisfacer mejor las necesidades de las empresas para la gestión GitOps de puertas de enlace de API, mejorando la eficiencia y flexibilidad de la gestión de API.