Verwalten von APISIX deklarativ mit APISIX Declarative CLI

APISIX-Benutzer verwenden hauptsächlich die Admin API, um APISIX zu konfigurieren. Wenn jedoch die Komplexität der Konfigurationen zunimmt, wird die Verwaltung dieser Konfigurationen nur über die Admin API immer schwieriger.

Um dies zu vereinfachen, haben wir APISIX Declarative CLI, auch bekannt als ADC, entwickelt, ein Tool, mit dem Sie APISIX-Konfigurationen deklarativ definieren können.

In diesem Artikel werden wir uns ansehen, wie Sie Ihre APISIX-Konfigurationen mit ADC verwalten können.

APISIX bereitstellen

Bevor wir beginnen, sollten wir zunächst eine APISIX-Instanz ausführen, mit der wir interagieren und die wir konfigurieren können. Wir können APISIX in Docker starten, indem wir folgenden Befehl ausführen:

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

Weitere Informationen zur Verwendung von APISIX finden Sie in der APISIX-Dokumentation.

ADC installieren

Sie können ADC mit dem Befehl go install installieren:

go install github.com/api7/adc@latest

Dadurch wird die adc-Binärdatei in Ihr $GOPATH/bin-Verzeichnis installiert.

export PATH=$PATH:$GOPATH/bin

Wenn Sie Go nicht installiert haben, können Sie auch die neueste adc-Binärdatei für Ihr Betriebssystem herunterladen und sie wie folgt in Ihren /bin-Ordner verschieben:

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

Sie finden Binärdateien für andere Betriebssysteme auf der Releases-Seite. In Zukunft werden diese Binärdateien auf Paketmanagern wie Homebrew veröffentlicht.

Um zu überprüfen, ob adc installiert ist, führen Sie folgenden Befehl aus:

adc --help

Wenn alles in Ordnung ist, sehen Sie eine Liste der verfügbaren Unterbefehle und deren Verwendung.

ADC mit Ihrer APISIX-Instanz konfigurieren

Um ADC so zu konfigurieren, dass es mit Ihrer bereitgestellten APISIX-Instanz arbeitet, können Sie folgenden Befehl ausführen:

adc configure

Dadurch werden Sie aufgefordert, die APISIX-Serveradresse ('http://127.0.0.1:9180', wenn Sie den Anweisungen gefolgt sind) und das Token einzugeben.

Wenn alles korrekt ist, sollten Sie eine Nachricht wie die folgende sehen:

ADC erfolgreich konfiguriert!
Erfolgreich mit APISIX verbunden!

adc ping

APISIX-Konfigurationsdateien validieren

Lassen Sie uns eine grundlegende APISIX-Konfiguration mit einer Route erstellen, die den Datenverkehr an ein Upstream weiterleitet:

name: "Basic configuration"
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

Sobald ADC mit der laufenden APISIX-Instanz verbunden ist, können wir es verwenden, um diese Konfiguration zu validieren, bevor wir sie anwenden, indem wir folgenden Befehl ausführen:

adc validate -f config.yaml

Wenn die Konfiguration gültig ist, sollten Sie eine ähnliche Antwort erhalten:

Konfigurationsdatei erfolgreich gelesen: config name: Basic configuration, version: 1.0.0, routes: 1, services: 1.
Konfigurationsdatei erfolgreich validiert!

Konfiguration mit der APISIX-Instanz synchronisieren

Sie können nun ADC verwenden, um Ihre gültige Konfiguration mit der verbundenen APISIX-Instanz zu synchronisieren. Führen Sie dazu folgenden Befehl aus:

adc sync -f config.yaml

Dadurch wird eine Route und ein Dienst erstellt, wie wir es in unserer Konfigurationsdatei deklariert haben:

creating service: "httpbin-service"
creating route: "httpbin-route"
Summary: created 2, updated 0, deleted 0

Um zu überprüfen, ob die Routen korrekt erstellt wurden, senden wir eine Anfrage:

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

Wenn alles korrekt ist, erhalten Sie eine Antwort von httpbin.org.

Lokale und laufende Konfiguration vergleichen

Lassen Sie uns nun unsere lokale Konfiguration in der Datei config.yaml aktualisieren, indem wir eine weitere Route hinzufügen:

name: "Basic configuration"
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

Bevor Sie diese Konfiguration mit APISIX synchronisieren, können Sie mit ADC die Unterschiede zwischen dieser und der bestehenden APISIX-Konfiguration überprüfen. Führen Sie dazu folgenden Befehl aus:

adc diff -f config.yaml

Sie können die Hinzufügungen und Löschungen in der Konfiguration sehen und verstehen, was sich geändert hat, bevor Sie sie anwenden.

OpenAPI-Definitionen in APISIX-Konfiguration umwandeln

ADC bietet auch grundlegende Unterstützung für die Arbeit mit OpenAPI-Definitionen. ADC ermöglicht es Ihnen, Definitionen im OpenAPI-Format in APISIX-Konfigurationen umzuwandeln.

Wenn Sie beispielsweise Ihre API im OpenAPI-Format dokumentiert haben, wie unten gezeigt:

openapi: 3.0.0
info:
  title: httpbin API
  description: Routes for httpbin API
  version: 1.0.0
servers:
  - url: http://httpbin.org
paths:
  /anything:
    get:
      tags:
        - default
      summary: Returns anything that is passed in the request data
      operationId: getAnything
      parameters:
        - name: host
          in: header
          schema:
            type: string
          example: "{{host}}"
      responses:
        "200":
          description: Successfully return anything
          content:
            application/json: {}
  /ip:
    get:
      tags:
        - default
      summary: Returns the IP address of the requester
      operationId: getIP
      responses:
        "200":
          description: Successfully return IP
          content:
            application/json: {}

Sie können den Unterbefehl openapi2apisix verwenden, um dies in eine APISIX-Konfiguration umzuwandeln, wie unten gezeigt:

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

Dadurch wird eine Konfigurationsdatei wie diese erstellt:

name: ""
routes:
- desc: Returns anything that is passed in the request data
  id: ""
  methods:
  - GET
  name: getAnything
  uris:
  - /anything
- desc: Returns the IP address of the requester
  id: ""
  methods:
  - GET
  name: getIP
  uris:
  - /ip
services:
- desc: Routes for httpbin API
  id: ""
  name: httpbin API
  upstream:
    id: ""
    name: ""
    nodes: null
version: ""

Wie Sie sehen können, ist die Konfiguration unvollständig, und Sie müssten noch viele Konfigurationen manuell hinzufügen. Wir arbeiten daran, ADC zu verbessern, um diese Lücke zwischen OpenAPI-Definitionen und dem, was direkt auf APISIX-Konfigurationen abgebildet werden kann, zu schließen.

Tipp: Autovervollständigung verwenden

Mit ADC können Sie viel erreichen, und die Liste der Funktionen wird sicherlich noch wachsen. Um zu erfahren, wie Sie einen Unterbefehl verwenden können, können Sie das Flag --help oder -h verwenden, das die Dokumentation für den Unterbefehl anzeigt.

Um es noch einfacher zu machen, können Sie mit dem Unterbefehl completion ein Autovervollständigungsskript für Ihre Shell-Umgebung generieren. Wenn Sie beispielsweise eine zsh-Shell verwenden, können Sie folgenden Befehl ausführen:

adc completion zsh

Sie können dann die Ausgabe in Ihre .zshrc-Datei kopieren, und es werden Hinweise angezeigt, wenn Sie adc verwenden.

ADC befindet sich noch in den Kinderschuhen und wird kontinuierlich verbessert. Um mehr über das Projekt zu erfahren, Fehler zu melden oder Funktionen vorzuschlagen, besuchen Sie github.com/api7/adc.