Gérer APISIX de manière déclarative avec APISIX Declarative CLI

APISIX les utilisateurs utilisent principalement l'API Admin pour configurer APISIX. Mais à mesure que vos configurations deviennent plus complexes, la gestion de celles-ci uniquement via l'API Admin devient plus difficile.

Pour simplifier les choses, nous avons développé APISIX Declarative CLI, alias ADC, un outil qui vous permet de définir les configurations d'APISIX de manière déclarative.

Dans cet article, nous verrons comment vous pouvez gérer vos configurations APISIX avec ADC.

Déployer APISIX

Avant de commencer, nous devons d'abord exécuter une instance d'APISIX pour interagir et configurer. Nous pouvons démarrer APISIX dans Docker en exécutant :

curl -sL https://run.api7.ai/apisix/quickstart | sh

Consultez la documentation d'APISIX pour en savoir plus sur l'utilisation d'APISIX.

Installer ADC

Vous pouvez installer ADC avec la commande go install :

go install github.com/api7/adc@latest

Cela installera le binaire adc dans votre répertoire $GOPATH/bin.

export PATH=$PATH:$GOPATH/bin

Si vous n'avez pas Go installé, vous pouvez également télécharger le dernier binaire adc pour votre système d'exploitation et l'ajouter à votre dossier /bin comme indiqué ci-dessous :

wget https://github.com/api7/adc/releases/download/v0.2.0/adc_0.2.0_linux_amd64.tar.gz
tar -zxvf adc_0.2.0_linux_amd64.tar.gz
mv adc /usr/local/bin/adc

Vous pouvez trouver les binaires pour d'autres systèmes d'exploitation sur la page des versions. À l'avenir, ces binaires seront publiés sur des gestionnaires de paquets comme Homebrew.

Pour vérifier si adc est installé, exécutez :

adc --help

Si tout est correct, vous verrez une liste de sous-commandes disponibles et comment les utiliser.

Configurer ADC avec votre instance APISIX

Pour configurer ADC pour qu'il fonctionne avec votre instance APISIX déployée, vous pouvez exécuter :

adc configure

Cela vous demandera de saisir l'adresse du serveur APISIX ('http://127.0.0.1:9180' si vous avez suivi les étapes) et le jeton.

Si tout est correct, vous devriez voir un message comme ci-dessous :

ADC configuré avec succès !
Connecté à APISIX avec succès !

adc ping

Valider les fichiers de configuration APISIX

Créons une configuration de base d'APISIX avec une route qui redirige le trafic vers un upstream :

name: "Configuration de base"
version: "1.0.0"
services:
  - name: httpbin-service
    hosts:
      - api7.ai
    upstream:
      name: httpbin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1
routes:
  - name: httpbin-route
    service_id: httpbin-service
    uri: "/anything"
    methods:
      - GET

Une fois qu'ADC est connecté à l'instance APISIX en cours d'exécution, nous pouvons l'utiliser pour valider cette configuration avant de l'appliquer en exécutant :

adc validate -f config.yaml

Si la configuration est valide, vous devriez recevoir une réponse similaire :

Fichier de configuration lu avec succès : nom de la configuration : Configuration de base, version : 1.0.0, routes : 1, services : 1.
Fichier de configuration validé avec succès !

Synchroniser la configuration avec l'instance APISIX

Vous pouvez maintenant utiliser ADC pour synchroniser votre configuration valide avec l'instance APISIX connectée. Pour ce faire, exécutez :

adc sync -f config.yaml

Cela créera une route et un service comme nous l'avons déclaré dans notre fichier de configuration :

création du service : "httpbin-service"
création de la route : "httpbin-route"
Résumé : créé 2, mis à jour 0, supprimé 0

Pour vérifier si les routes ont été correctement créées, essayons d'envoyer une requête :

curl localhost:9080/anything -H "host:api7.ai"

Si tout est correct, vous recevrez une réponse de httpbin.org.

Comparer la configuration locale et en cours d'exécution

Maintenant, mettons à jour notre configuration locale dans le fichier config.yaml en ajoutant une autre route :

name: "Configuration de base"
version: "1.0.0"
services:
  - name: httpbin-service
    hosts:
      - api7.ai
    upstream:
      name: httpbin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1
routes:
  - name: httpbin-route-anything
    service_id: httpbin-service
    uri: "/anything"
    methods:
      - GET
  - name: httpbin-route-ip
    service_id: httpbin-service
    uri: "/ip"
    methods:
      - GET

Avant de synchroniser cette configuration avec APISIX, ADC vous permet de vérifier les différences entre celle-ci et la configuration APISIX existante. Vous pouvez le faire en exécutant :

adc diff -f config.yaml

Vous pourrez voir les ajouts et les suppressions dans la configuration et comprendre ce qui a changé avant de l'appliquer.

Convertir les définitions OpenAPI en configuration APISIX

ADC prend également en charge de manière basique les définitions OpenAPI. ADC vous permet de convertir les définitions au format OpenAPI en configuration APISIX.

Par exemple, si vous avez documenté votre API au format OpenAPI comme ci-dessous :

openapi: 3.0.0
info:
  title: API httpbin
  description: Routes pour l'API httpbin
  version: 1.0.0
servers:
  - url: http://httpbin.org
paths:
  /anything:
    get:
      tags:
        - default
      summary: Renvoie tout ce qui est passé dans les données de la requête
      operationId: getAnything
      parameters:
        - name: host
          in: header
          schema:
            type: string
          example: "{{host}}"
      responses:
        "200":
          description: Renvoie avec succès tout ce qui est passé
          content:
            application/json: {}
  /ip:
    get:
      tags:
        - default
      summary: Renvoie l'adresse IP du demandeur
      operationId: getIP
      responses:
        "200":
          description: Renvoie avec succès l'IP
          content:
            application/json: {}

Vous pouvez utiliser la sous-commande openapi2apisix pour convertir cela en configuration APISIX comme ci-dessous :

adc openapi2apisix -o config.yaml -f openAPI.yaml

Cela créera un fichier de configuration comme celui-ci :

name: ""
routes:
- desc: Renvoie tout ce qui est passé dans les données de la requête
  id: ""
  methods:
  - GET
  name: getAnything
  uris:
  - /anything
- desc: Renvoie l'adresse IP du demandeur
  id: ""
  methods:
  - GET
  name: getIP
  uris:
  - /ip
services:
- desc: Routes pour l'API httpbin
  id: ""
  name: API httpbin
  upstream:
    id: ""
    name: ""
    nodes: null
version: ""

Comme vous pouvez le voir, la configuration est incomplète, et vous devrez encore ajouter beaucoup de configurations manuellement. Nous améliorons ADC pour combler cet écart entre les définitions OpenAPI et ce qui peut être directement mappé à la configuration APISIX.

Astuce : Utiliser l'autocomplétion

Vous pouvez faire beaucoup de choses avec ADC, et la liste des fonctionnalités est appelée à augmenter. Pour apprendre à utiliser une sous-commande, vous pouvez utiliser le drapeau --help ou -h, qui affichera la documentation pour la sous-commande.

Pour rendre les choses encore plus faciles, vous pouvez générer un script d'autocomplétion pour votre environnement shell en utilisant la sous-commande completion. Par exemple, si vous utilisez un shell zsh, vous pouvez exécuter :

adc completion zsh

Vous pouvez ensuite copier-coller la sortie dans votre fichier .zshrc, et il commencera à afficher des suggestions lorsque vous utiliserez adc.

ADC est encore à ses débuts et est continuellement amélioré. Pour en savoir plus sur le projet, signaler des bugs ou suggérer des fonctionnalités, visitez github.com/api7/adc.