APISIX Declarative CLIを使用した宣言的なAPISIX管理

Navendu Pottekkat

Navendu Pottekkat

September 22, 2023

Technology

APISIXのユーザーは、主にAdmin APIを使用してAPISIXを設定します。しかし、設定が複雑になるにつれて、Admin APIのみでこれらを管理することはより困難になります。

これを簡単にするために、APISIXの設定を宣言的に定義できるツールであるAPISIX Declarative CLI、通称ADCを開発しました。

この記事では、ADCを使用してAPISIXの設定を管理する方法を見ていきます。

APISIXのデプロイ

始める前に、まずAPISIXインスタンスを実行して、それと対話し設定する必要があります。DockerでAPISIXを起動するには、次のコマンドを実行します：

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

APISIXの使用方法について詳しくは、APISIXドキュメントを参照してください。

ADCのインストール

go installコマンドを使用してADCをインストールできます：

go install github.com/api7/adc@latest

これにより、adcバイナリが$GOPATH/binディレクトリにインストールされます。

これを$PATH環境変数に追加することを確認してください：

export PATH=$PATH:$GOPATH/bin

Goがインストールされていない場合、最新のadcバイナリをダウンロードして、以下のように/binフォルダに追加することもできます：

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

他のオペレーティングシステム用のバイナリは、リリースページで見つけることができます。将来的には、これらのバイナリはHomebrewなどのパッケージマネージャーで公開される予定です。

adcがインストールされているか確認するには、次のコマンドを実行します：

adc --help

すべてが正常であれば、利用可能なサブコマンドとその使用方法のリストが表示されます。

APISIXインスタンスでのADCの設定

デプロイされたAPISIXインスタンスでADCを動作させるために、次のコマンドを実行します：

adc configure

これにより、APISIXサーバーのアドレス（'http://127.0.0.1:9180'）とトークンを入力するように促されます。

すべてが正しければ、以下のようなメッセージが表示されます：

ADC configured successfully!
Connected to APISIX successfully!

APISIXとの接続を確認するために、いつでもpingサブコマンドを使用できます：

adc ping

APISIX設定ファイルの検証

トラフィックをアップストリームに転送するルートを含む基本的なAPISIX設定を作成しましょう：

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

ADCが実行中のAPISIXインスタンスに接続されたら、設定を適用する前にこれを検証するために次のコマンドを実行できます：

adc validate -f config.yaml

設定が有効であれば、次のような応答が返されます：

Read configuration file successfully: config name: Basic configuration, version: 1.0.0, routes: 1, services: 1.
Successfully validated configuration file!

APISIXインスタンスへの設定の同期

有効な設定を接続されたAPISIXインスタンスと同期するために、ADCを使用できます。これを行うには、次のコマンドを実行します：

adc sync -f config.yaml

これにより、設定ファイルで宣言した通りにルートとサービスが作成されます：

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

ルートが正しく作成されたか確認するために、リクエストを送信してみましょう：

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

すべてが正しければ、httpbin.orgからの応答が返されます。

ローカルと実行中の設定の比較

次に、config.yamlファイルのローカル設定を更新して、別のルートを追加します：

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

この設定をAPISIXと同期する前に、ADCを使用して既存のAPISIX設定との違いを確認できます。これを行うには、次のコマンドを実行します：

adc diff -f config.yaml

設定の追加や削除を確認し、適用する前に何が変更されたかを理解できます。

OpenAPI定義からAPISIX設定への変換

ADCは、OpenAPI定義を扱う基本的なサポートも提供しています。ADCを使用して、OpenAPI形式の定義をAPISIX設定に変換できます。

例えば、以下のようにOpenAPI形式でAPIをドキュメント化している場合：

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: {}

openapi2apisixサブコマンドを使用して、これをAPISIX設定に変換できます：

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

これにより、以下のような設定ファイルが作成されます：

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: ""

ご覧の通り、設定は不完全で、まだ多くの設定を手動で追加する必要があります。ADCを改善して、OpenAPI定義とAPISIX設定に直接マッピングできるものとの間のギャップを埋めることを目指しています。

ヒント：オートコンプリートの使用

ADCでは多くのことができ、機能のリストは増え続けています。サブコマンドの使用方法を学ぶには、--helpまたは-hフラグを使用できます。これにより、サブコマンドのドキュメントが表示されます。

さらに簡単にするために、completionサブコマンドを使用してシェル環境のオートコンプリートスクリプトを生成できます。例えば、zshシェルを使用している場合、次のコマンドを実行します：

adc completion zsh

その後、出力を.zshrcファイルにコピー＆ペーストすると、adcを使用する際にヒントが表示されるようになります。

ADCはまだ初期段階にあり、継続的に改善されています。プロジェクトについて詳しく知りたい、バグを報告したい、または機能を提案したい場合は、github.com/api7/adcを訪れてください。

Tags:
APISIX configuration
Declarative configuration
CLI