Управление APISIX декларативно с помощью APISIX Declarative CLI

Navendu Pottekkat

Navendu Pottekkat

September 22, 2023

Technology

APISIX пользователи в основном используют Admin API для настройки APISIX. Однако по мере увеличения сложности конфигураций управление ими только через Admin API становится более сложным.

Чтобы упростить этот процесс, мы разработали APISIX Declarative CLI, также известный как ADC, инструмент, который позволяет вам декларативно определять конфигурации APISIX.

В этой статье мы рассмотрим, как вы можете управлять конфигурациями APISIX с помощью ADC.

Развертывание APISIX

Прежде чем мы начнем, нам нужно запустить экземпляр APISIX для взаимодействия и настройки. Мы можем запустить APISIX в Docker, выполнив следующую команду:

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

Подробнее об использовании APISIX можно узнать в документации APISIX.

Установка ADC

Вы можете установить ADC с помощью команды go install:

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

Если все в порядке, вы увидите список доступных подкоманд и инструкции по их использованию.

Настройка ADC для работы с вашим экземпляром APISIX

Чтобы настроить ADC для работы с вашим развернутым экземпляром APISIX, выполните:

adc configure

Это предложит вам ввести адрес сервера APISIX ('http://127.0.0.1:9180', если вы следовали инструкциям) и токен.

Если все правильно, вы увидите сообщение, как показано ниже:

ADC configured successfully!
Connected to APISIX successfully!

Вы можете использовать подкоманду ping для проверки подключения к APISIX в любое время:

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

Теперь вы можете использовать ADC для синхронизации вашей действительной конфигурации с подключенным экземпляром APISIX. Для этого выполните:

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.

Например, если вы задокументировали ваш API в формате OpenAPI, как показано ниже:

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