Quoi de neuf dans ADC 0.8, 0.9 et 0.10 ?

Introduction

ADC (APISIX Declarative CLI) est un outil de configuration déclarative introduit par API7.ai, offrant un ensemble d'outils pratiques pour permettre aux utilisateurs de mettre en œuvre GitOps. Les utilisateurs peuvent facilement l'intégrer dans leurs pipelines CI/CD pour gérer le cycle de vie complet des API, en réalisant les mises à niveau et les déploiements d'API. Après la sortie de la version 0.7, ADC a publié trois nouvelles versions : 0.8, 0.9 et 0.10, avec des optimisations et des mises à jour en termes de fonctionnalités, de performances et d'expérience utilisateur.

Nouvelles fonctionnalités d'ADC

Améliorations du détecteur de changements de ressources : Differ

Ces modifications ont été introduites dans les versions 0.8 et 0.9.

Nous avons introduit une nouvelle version du détecteur de changements de ressources Differ, la v3, qui apporte des améliorations significatives en termes de fonctionnalités et de qualité de code.

1. Le nouveau Differ introduit un mécanisme de fusion des valeurs par défaut pour les ressources locales, garantissant que les valeurs par défaut du côté serveur n'interfèrent pas avec les vérifications de changements de ressources d'ADC.

   Lorsque le client envoie une requête pour créer une ressource sur l'API Admin d'API7 ou APISIX, le serveur effectue une validation de schéma sur la requête soumise. Au cours de ce processus, certains champs ayant des valeurs par défaut marquées dans le schéma mais non envoyés par le client seront automatiquement ajoutés à la ressource soumise. Par conséquent, lorsque nous relisons la ressource depuis l'API, elle sera différente de la soumission initiale.

   Les versions précédentes d'ADC listaient ces ressources comme "modifiées" et envoyaient des requêtes API de mise à jour à l'API Admin. Ce comportement introduisait une certaine incertitude pour ADC, et ce problème a été résolu grâce à Differ.

2. Le mécanisme de fusion des valeurs par défaut a été implémenté dans le backend d'API7, garantissant que les différences de ressources ne sont considérées comme des modifications que lorsque l'utilisateur a modifié la configuration YAML locale.

3. Affinement de la granularité de détection de Differ : ADC effectue actuellement les vérifications de changements de ressources séparément au niveau du corps de la ressource et des plugins, aidant à réduire les anomalies dans la vérification.

4. Optimisation de la qualité du code, simplification du code redondant pour améliorer la lisibilité, et correction de certains bugs.

Filtres de ressources

Nous avons ajouté deux mécanismes de filtrage de ressources basés sur les étiquettes de ressources et les types de ressources. Ils peuvent être utilisés pour exclure les ressources inutiles lors des opérations de récupération, de vérification des différences et de synchronisation.

Filtre par étiquette de ressource

Cette fonctionnalité a été introduite dans la version 0.8.

Ce filtre effectue le filtrage en fonction du champ labels des ressources. Les utilisateurs peuvent activer le filtre en utilisant le paramètre --label-selector key=value en ligne de commande. Il supporte la configuration de plusieurs conditions de filtrage, et seules les ressources distantes qui satisfont simultanément ces règles seront considérées comme existantes, tandis que les ressources locales seront automatiquement ajoutées avec ces étiquettes.

Cela garantit que nous effectuons les vérifications et la synchronisation des ressources dans un périmètre restreint, aidant à diviser les tâches exécutées dans le pipeline CI/CD et empêchant une synchronisation accidentelle d'endommager des ressources qui n'ont pas besoin d'être modifiées.

Filtre par type de ressource

Cette fonctionnalité a été introduite dans la version 0.9.

Nous avons ajouté deux nouveaux paramètres en ligne de commande : --include-resource-type <type> et --exclude-resource-type <type>, qui peuvent être configurés plusieurs fois, mais les paramètres include et exclude s'excluent mutuellement.

Avec ces deux paramètres, nous pouvons filtrer des types de ressources spécifiques de l'opération en cours. Par exemple, utiliser include-resource-type peut être utilisé pour définir une liste blanche et sélectionner les types de ressources à inclure dans l'opération ; tandis que exclude-resource-type déterminera les types de ressources à exclure de l'opération.

Cela nous aide à mieux gérer les ressources qui n'ont pas besoin d'être fréquemment modifiées, comme les métadonnées des plugins et les règles globales des plugins.

Améliorations de la ligne de commande

Ces améliorations ont été introduites dans la version 0.9.

Configuration des certificats TLS

Nous avons ajouté une série de paramètres liés à TLS en ligne de commande, tels que :

• --ca-cert-file pour spécifier le fichier de certificat CA du serveur
• --tls-skip-verify pour désactiver la vérification du certificat serveur TLS
• --tls-client-cert-file et --tls-client-key-file pour spécifier les fichiers de certificat client mTLS

Ces paramètres aident ADC à établir une connexion chiffrée sécurisée et à prévenir les attaques de type "man-in-the-middle".

Contrôle du délai d'attente

Nous avons ajouté le paramètre --timeout <duration> pour contrôler la durée d'attente des appels API, supportant une syntaxe comme 1m30s. Lorsqu'un appel API Admin prend trop de temps ou se bloque, le mécanisme de délai d'attente prend effet pour éviter une attente infinie.

Mode Debug

Cette fonctionnalité a été introduite dans la version 0.9.

Lorsqu'ADC effectue des opérations sur les ressources en interne, il doit appeler un grand nombre d'API. Parfois, nous pouvons avoir besoin de vérifier ces appels API pour analyser s'ils sont envoyés correctement ou pour vérifier que les réponses du serveur répondent aux attentes. Bien que la capture de paquets puisse être utilisée pour cela, l'opération n'est pas pratique, et il y a des difficultés importantes lorsque TLS est activé.

Par conséquent, nous avons ajouté un mode debug intégré à ADC, qui peut être activé en utilisant le paramètre --verbose <integer>. Lorsque ce paramètre est défini à 2, ADC imprimera les parties requête et réponse de chaque appel API interne pour aider au débogage.

Ce paramètre peut également être utilisé pour masquer les logs. Lorsque ce paramètre est défini à 0, ADC masquera tous les logs généraux sauf les erreurs.

Renforcement du traitement des ressources distantes

Cette fonctionnalité a été introduite dans la version 0.9.

Puisqu'ADC n'est pas le seul moyen de configurer les services, routes, etc., les utilisateurs peuvent également utiliser le tableau de bord d'API7 Enterprise pour y parvenir via des opérations simples. Cela a conduit à un problème : les opérations sur le tableau de bord utiliseront des ID de ressources générés aléatoirement, tandis qu'ADC utilise le nom de la ressource dans la configuration YAML pour générer un ID de ressource fixe pour localiser précisément la ressource.

Cela signifie que si l'utilisateur crée une ressource sur le tableau de bord, ADC ne pourra pas la localiser par l'ID de ressource. ADC ne peut pas modifier ou supprimer les ressources créées sur le tableau de bord, mais ces ressources apparaîtront toujours dans la détection des changements, sans pouvoir être correctement opérées.

Par conséquent, nous avons optimisé la logique pertinente du backend API7 d'ADC. Si les ressources distantes et locales contiennent toutes deux des ressources avec le même nom, mais que les ID ne correspondent pas, ADC peut correctement supprimer la ressource distante et en créer une nouvelle basée sur la configuration locale, auquel cas l'ID sera généré par ADC en fonction du nom de la ressource et pourra être utilisé pour les recherches ultérieures de ressources. Les utilisateurs du tableau de bord API7 ne seront pas affectés, et les ressources créées par ADC peuvent toujours être visualisées sur le tableau de bord.

Support des champs d'extension ADC dans le convertisseur OpenAPI

Cette fonctionnalité a été introduite dans la version 0.10.

Pour construire un pipeline cohérent d'OpenAPI à ADC à API7, le convertisseur OpenAPI doit injecter les champs requis dans le fichier de configuration YAML d'ADC en fonction de nos besoins.

Par exemple, pour modifier le champ pass_host dans l'upstream du service, auparavant nous ne pouvions que manuellement utiliser le convertisseur pour convertir l'OpenAPI en fichier de configuration ADC, modifier manuellement le champ pass_host, puis soumettre le fichier modifié au dépôt Git pour que le pipeline CI/CD exécute la synchronisation ADC. Ce processus n'est pas cohérent et nécessite beaucoup d'intervention manuelle.

Maintenant, grâce aux extensions x-adc introduites, les utilisateurs n'ont qu'à écrire les champs d'extension à des emplacements spécifiques dans le document OpenAPI, et ADC écrira correctement ces champs dans le fichier de configuration généré. Avec ces extensions, les utilisateurs peuvent directement modifier tout contenu dans la configuration ADC sur l'OpenAPI, comme ajouter des étiquettes, ajouter des plugins, et remplacer la configuration par défaut des services/upstreams/routes.

En conséquence, en ne maintenant qu'un seul fichier OpenAPI, le pipeline OpenAPI-ADC-API7 peut être implémenté de manière intégrée, simplifiant grandement le workflow GitOps pour la configuration de la passerelle API.

Conclusion

L'outil de configuration déclarative ADC lancé par API7.ai peut aider les entreprises à réaliser la gestion GitOps des passerelles API. Dans les nouvelles versions 0.8, 0.9 et 0.10, l'outil a été optimisé et amélioré fonctionnellement, ajoutant des fonctionnalités telles que la surveillance et le filtrage des changements de ressources. Ces nouvelles fonctionnalités injectent une nouvelle dynamique dans la gestion complète du cycle de vie des API.

Ces nouvelles capacités permettent à ADC de mieux répondre aux besoins des entreprises en matière de gestion GitOps des passerelles API, améliorant l'efficacité et la flexibilité de la gestion des API.