Gerenciando o APISIX de Forma Declarativa com o APISIX Declarative CLI

APISIX os usuários utilizam principalmente a API Admin para configurar o APISIX. Mas à medida que suas configurações aumentam em complexidade, gerenciá-las apenas por meio da API Admin se torna mais desafiador.

Para facilitar as coisas, desenvolvemos o APISIX Declarative CLI, também conhecido como ADC, uma ferramenta que permite definir as configurações do APISIX de forma declarativa.

Neste artigo, veremos como você pode gerenciar suas configurações do APISIX com o ADC.

Implantando o APISIX

Antes de começarmos, devemos primeiro executar uma instância do APISIX para interagir e configurar. Podemos iniciar o APISIX no Docker executando:

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

Consulte a documentação do APISIX para saber mais sobre como usar o APISIX.

Instalando o ADC

Você pode instalar o ADC com o comando go install:

go install github.com/api7/adc@latest

Isso instalará o binário adc no diretório $GOPATH/bin.

export PATH=$PATH:$GOPATH/bin

Se você não tiver o Go instalado, também pode baixar o binário mais recente do adc para o seu sistema operacional e adicioná-lo à pasta /bin conforme mostrado abaixo:

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

Você pode encontrar binários para outros sistemas operacionais na página de lançamentos. No futuro, esses binários serão publicados em gerenciadores de pacotes como o Homebrew.

Para verificar se o adc está instalado, execute:

adc --help

Se tudo estiver certo, você verá uma lista de subcomandos disponíveis e como usá-los.

Configurando o ADC com Sua Instância do APISIX

Para configurar o ADC para trabalhar com sua instância do APISIX implantada, você pode executar:

adc configure

Isso solicitará que você insira o endereço do servidor APISIX ('http://127.0.0.1:9180' se você seguiu o exemplo) e o token.

Se tudo estiver correto, você verá uma mensagem como mostrado abaixo:

ADC configurado com sucesso!
Conectado ao APISIX com sucesso!

adc ping

Validando Arquivos de Configuração do APISIX

Vamos criar uma configuração básica do APISIX com uma rota que encaminha o tráfego para um upstream:

name: "Configuração básica"
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

Uma vez que o ADC está conectado à instância do APISIX em execução, podemos usá-lo para validar essa configuração antes de aplicá-la, executando:

adc validate -f config.yaml

Se a configuração for válida, você receberá uma resposta semelhante:

Arquivo de configuração lido com sucesso: nome da configuração: Configuração básica, versão: 1.0.0, rotas: 1, serviços: 1.
Arquivo de configuração validado com sucesso!

Sincronizando a Configuração com a Instância do APISIX

Agora você pode usar o ADC para sincronizar sua configuração válida com a instância do APISIX conectada. Para fazer isso, execute:

adc sync -f config.yaml

Isso criará uma rota e um serviço conforme declarado em nosso arquivo de configuração:

criando serviço: "httpbin-service"
criando rota: "httpbin-route"
Resumo: criados 2, atualizados 0, excluídos 0

Para verificar se as rotas foram criadas corretamente, vamos tentar enviar uma solicitação:

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

Se tudo estiver correto, você receberá uma resposta de httpbin.org.

Comparando a Configuração Local e em Execução

Agora vamos atualizar nossa configuração local no arquivo config.yaml adicionando outra rota:

name: "Configuração básica"
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

Antes de sincronizar essa configuração com o APISIX, o ADC permite que você verifique as diferenças entre ela e a configuração existente do APISIX. Você pode fazer isso executando:

adc diff -f config.yaml

Você poderá ver as adições e exclusões na configuração e entender o que mudou antes de aplicá-la.

Convertendo Definições OpenAPI para Configuração do APISIX

O ADC também tem suporte básico para trabalhar com definições OpenAPI. O ADC permite que você converta definições no formato OpenAPI para configuração do APISIX.

Por exemplo, se você documentou sua API no formato OpenAPI conforme mostrado abaixo:

openapi: 3.0.0
info:
  title: API httpbin
  description: Rotas para a API httpbin
  version: 1.0.0
servers:
  - url: http://httpbin.org
paths:
  /anything:
    get:
      tags:
        - default
      summary: Retorna qualquer coisa que for passada nos dados da solicitação
      operationId: getAnything
      parameters:
        - name: host
          in: header
          schema:
            type: string
          example: "{{host}}"
      responses:
        "200":
          description: Retorna qualquer coisa com sucesso
          content:
            application/json: {}
  /ip:
    get:
      tags:
        - default
      summary: Retorna o endereço IP do solicitante
      operationId: getIP
      responses:
        "200":
          description: Retorna o IP com sucesso
          content:
            application/json: {}

Você pode usar o subcomando openapi2apisix para converter isso em configuração do APISIX conforme mostrado abaixo:

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

Isso criará um arquivo de configuração como este:

name: ""
routes:
- desc: Retorna qualquer coisa que for passada nos dados da solicitação
  id: ""
  methods:
  - GET
  name: getAnything
  uris:
  - /anything
- desc: Retorna o endereço IP do solicitante
  id: ""
  methods:
  - GET
  name: getIP
  uris:
  - /ip
services:
- desc: Rotas para a API httpbin
  id: ""
  name: API httpbin
  upstream:
    id: ""
    name: ""
    nodes: null
version: ""

Como você pode ver, a configuração está incompleta, e você ainda precisaria adicionar muitas configurações manualmente. Estamos melhorando o ADC para preencher essa lacuna entre as definições OpenAPI e o que pode ser mapeado diretamente para a configuração do APISIX.

Dica: Use Autocompletar

Você pode fazer muito com o ADC, e a lista de recursos certamente aumentará. Para aprender como usar qualquer subcomando, você pode usar a flag --help ou -h, que mostrará a documentação do subcomando.

Para facilitar ainda mais, você pode gerar um script de autocompletar para o seu ambiente de shell usando o subcomando completion. Por exemplo, se você estiver usando um shell zsh, pode executar:

adc completion zsh

Você pode então copiar e colar a saída no seu arquivo .zshrc, e ele começará a mostrar dicas quando você usar o adc.

O ADC ainda está em sua infância e está sendo continuamente aprimorado. Para saber mais sobre o projeto, relatar bugs ou sugerir recursos, visite github.com/api7/adc.