Mengelola APISIX Secara Deklaratif dengan APISIX Declarative CLI

Navendu Pottekkat

Navendu Pottekkat

September 22, 2023

Technology

APISIX pengguna terutama menggunakan Admin API untuk mengonfigurasi APISIX. Namun, seiring dengan meningkatnya kompleksitas konfigurasi Anda, mengelola ini hanya melalui Admin API menjadi lebih menantang.

Untuk mempermudah, kami mengembangkan APISIX Declarative CLI, alias ADC, sebuah alat yang memungkinkan Anda mendefinisikan konfigurasi APISIX secara deklaratif.

Dalam artikel ini, kita akan melihat bagaimana Anda dapat mengelola konfigurasi APISIX Anda dengan ADC.

Menjalankan APISIX

Sebelum kita memulai, kita harus terlebih dahulu menjalankan instance APISIX untuk berinteraksi dan mengonfigurasinya. Kita dapat menjalankan APISIX di Docker dengan perintah berikut:

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

Lihat dokumentasi APISIX untuk mempelajari lebih lanjut tentang penggunaan APISIX.

Menginstal ADC

Anda dapat menginstal ADC dengan perintah go install:

go install github.com/api7/adc@latest

Ini akan menginstal biner adc ke direktori $GOPATH/bin Anda.

Pastikan Anda menambahkan ini ke variabel lingkungan $PATH Anda:

export PATH=$PATH:$GOPATH/bin

Jika Anda tidak memiliki Go terinstal, Anda juga dapat mengunduh biner adc terbaru untuk sistem operasi Anda dan menambahkannya ke folder /bin seperti yang ditunjukkan di bawah ini:

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

Anda dapat menemukan biner untuk sistem operasi lain di halaman rilis. Di masa depan, biner ini akan dipublikasikan di manajer paket seperti Homebrew.

Untuk memeriksa apakah adc terinstal, jalankan:

adc --help

Jika semuanya beres, Anda akan melihat daftar subcommand yang tersedia dan cara menggunakannya.

Mengonfigurasi ADC dengan Instance APISIX Anda

Untuk mengonfigurasi ADC agar bekerja dengan instance APISIX yang telah Anda jalankan, Anda dapat menjalankan:

adc configure

Ini akan meminta Anda untuk memasukkan alamat server APISIX ('http://127.0.0.1:9180' jika Anda mengikuti langkah-langkah sebelumnya) dan token.

Jika semuanya benar, Anda akan melihat pesan seperti di bawah ini:

ADC configured successfully!
Connected to APISIX successfully!

Anda dapat menggunakan subcommand ping untuk memeriksa konektivitas dengan APISIX kapan saja:

adc ping

Memvalidasi File Konfigurasi APISIX

Mari buat konfigurasi APISIX dasar dengan rute yang meneruskan lalu lintas ke upstream:

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

Setelah ADC terhubung ke instance APISIX yang sedang berjalan, kita dapat menggunakannya untuk memvalidasi konfigurasi ini sebelum menerapkannya dengan menjalankan:

adc validate -f config.yaml

Jika konfigurasi valid, Anda akan menerima respons serupa:

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

Menyinkronkan Konfigurasi ke Instance APISIX

Anda sekarang dapat menggunakan ADC untuk menyinkronkan konfigurasi yang valid dengan instance APISIX yang terhubung. Untuk melakukan ini, jalankan:

adc sync -f config.yaml

Ini akan membuat rute dan layanan seperti yang kita deklarasikan dalam file konfigurasi kita:

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

Untuk memverifikasi apakah rute telah dibuat dengan benar, mari coba mengirim permintaan:

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

Jika semuanya benar, Anda akan menerima respons kembali dari httpbin.org.

Membandingkan Konfigurasi Lokal dan yang Sedang Berjalan

Sekarang mari perbarui konfigurasi lokal kita di file config.yaml dengan menambahkan rute lain:

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

Sebelum menyinkronkan konfigurasi ini dengan APISIX, ADC memungkinkan Anda memeriksa perbedaan antara konfigurasi ini dan konfigurasi APISIX yang ada. Anda dapat melakukan ini dengan menjalankan:

adc diff -f config.yaml

Anda akan dapat melihat penambahan dan penghapusan dalam konfigurasi dan memahami apa yang berubah sebelum menerapkannya.

Mengonversi Definisi OpenAPI ke Konfigurasi APISIX

ADC juga memiliki dukungan dasar untuk bekerja dengan definisi OpenAPI. ADC memungkinkan Anda mengonversi definisi dalam format OpenAPI ke konfigurasi APISIX.

Misalnya, jika Anda telah mendokumentasikan API Anda dalam format OpenAPI seperti yang ditunjukkan di bawah ini:

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

Anda dapat menggunakan subcommand openapi2apisix untuk mengonversi ini ke konfigurasi APISIX seperti yang ditunjukkan di bawah ini:

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

Ini akan membuat file konfigurasi seperti ini:

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

Seperti yang Anda lihat, konfigurasi ini belum lengkap, dan Anda masih perlu menambahkan banyak konfigurasi secara manual. Kami sedang meningkatkan ADC untuk menjembatani kesenjangan antara definisi OpenAPI dan apa yang dapat langsung dipetakan ke konfigurasi APISIX.

Tip: Gunakan Autocomplete

Anda dapat melakukan banyak hal dengan ADC, dan daftar fitur pasti akan bertambah. Untuk mempelajari cara menggunakan subcommand apa pun, Anda dapat menggunakan flag --help atau -h, yang akan menampilkan dokumentasi untuk subcommand tersebut.

Untuk membuat segalanya lebih mudah, Anda dapat menghasilkan skrip autocomplete untuk lingkungan shell Anda menggunakan subcommand completion. Misalnya, jika Anda menggunakan shell zsh, Anda dapat menjalankan:

adc completion zsh

Anda kemudian dapat menyalin-tempel output ke file .zshrc Anda, dan itu akan mulai menampilkan petunjuk saat Anda menggunakan adc.

ADC masih dalam tahap awal dan terus ditingkatkan. Untuk mempelajari lebih lanjut tentang proyek ini, melaporkan bug, atau menyarankan fitur, kunjungi github.com/api7/adc.

Tags:
APISIX configuration
Declarative configuration
CLI