Gestión declarativa de APISIX con APISIX Declarative CLI

APISIX los usuarios utilizan principalmente la API de administración para configurar APISIX. Pero a medida que tus configuraciones aumentan en complejidad, gestionarlas únicamente a través de la API de administración se vuelve más desafiante.

Para facilitar las cosas, desarrollamos APISIX Declarative CLI, también conocido como ADC, una herramienta que te permite definir configuraciones de APISIX de manera declarativa.

En este artículo, veremos cómo puedes gestionar tus configuraciones de APISIX con ADC.

Desplegando APISIX

Antes de comenzar, primero debemos ejecutar una instancia de APISIX para interactuar y configurar. Podemos iniciar APISIX en Docker ejecutando:

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

Consulta la documentación de APISIX para obtener más información sobre cómo usar APISIX.

Instalando ADC

Puedes instalar ADC con el comando go install:

go install github.com/api7/adc@latest

Esto instalará el binario adc en tu directorio $GOPATH/bin.

export PATH=$PATH:$GOPATH/bin

Si no tienes Go instalado, también puedes descargar el último binario adc para tu sistema operativo y agregarlo a tu carpeta /bin como se muestra a continuación:

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

Puedes encontrar binarios para otros sistemas operativos en la página de lanzamientos. En el futuro, estos binarios se publicarán en gestores de paquetes como Homebrew.

Para verificar si adc está instalado, ejecuta:

adc --help

Si todo está bien, verás una lista de subcomandos disponibles y cómo usarlos.

Configurando ADC con tu Instancia de APISIX

Para configurar ADC para que funcione con tu instancia de APISIX desplegada, puedes ejecutar:

adc configure

Esto te pedirá que ingreses la dirección del servidor de APISIX ('http://127.0.0.1:9180' si seguiste los pasos anteriores) y el token.

Si todo es correcto, deberías ver un mensaje como el siguiente:

ADC configurado exitosamente!
Conectado a APISIX exitosamente!

adc ping

Validando Archivos de Configuración de APISIX

Creemos una configuración básica de APISIX con una ruta que redirija el tráfico a un upstream:

name: "Configuración 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

Una vez que ADC esté conectado a la instancia de APISIX en ejecución, podemos usarlo para validar esta configuración antes de aplicarla ejecutando:

adc validate -f config.yaml

Si la configuración es válida, deberías recibir una respuesta similar:

Archivo de configuración leído exitosamente: nombre de la configuración: Configuración básica, versión: 1.0.0, rutas: 1, servicios: 1.
¡Archivo de configuración validado exitosamente!

Sincronizando la Configuración con la Instancia de APISIX

Ahora puedes usar ADC para sincronizar tu configuración válida con la instancia de APISIX conectada. Para hacer esto, ejecuta:

adc sync -f config.yaml

Esto creará una ruta y un servicio como declaramos en nuestro archivo de configuración:

creando servicio: "httpbin-service"
creando ruta: "httpbin-route"
Resumen: creados 2, actualizados 0, eliminados 0

Para verificar si las rutas se crearon correctamente, intentemos enviar una solicitud:

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

Si todo es correcto, recibirás una respuesta de httpbin.org.

Comparando la Configuración Local y la en Ejecución

Ahora actualicemos nuestra configuración local en el archivo config.yaml agregando otra ruta:

name: "Configuración 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 esta configuración con APISIX, ADC te permite verificar las diferencias entre ella y la configuración existente de APISIX. Puedes hacer esto ejecutando:

adc diff -f config.yaml

Podrás ver las adiciones y eliminaciones en la configuración y entender qué cambió antes de aplicarla.

Convirtiendo Definiciones OpenAPI a Configuración de APISIX

ADC también tiene soporte básico para trabajar con definiciones OpenAPI. ADC te permite convertir definiciones en formato OpenAPI a configuración de APISIX.

Por ejemplo, si has documentado tu API en formato OpenAPI como se muestra a continuación:

openapi: 3.0.0
info:
  title: httpbin API
  description: Rutas para la API de httpbin
  version: 1.0.0
servers:
  - url: http://httpbin.org
paths:
  /anything:
    get:
      tags:
        - default
      summary: Devuelve cualquier cosa que se pase en los datos de la solicitud
      operationId: getAnything
      parameters:
        - name: host
          in: header
          schema:
            type: string
          example: "{{host}}"
      responses:
        "200":
          description: Devuelve cualquier cosa exitosamente
          content:
            application/json: {}
  /ip:
    get:
      tags:
        - default
      summary: Devuelve la dirección IP del solicitante
      operationId: getIP
      responses:
        "200":
          description: Devuelve la IP exitosamente
          content:
            application/json: {}

Puedes usar el subcomando openapi2apisix para convertir esto a configuración de APISIX como se muestra a continuación:

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

Esto creará un archivo de configuración como este:

name: ""
routes:
- desc: Devuelve cualquier cosa que se pase en los datos de la solicitud
  id: ""
  methods:
  - GET
  name: getAnything
  uris:
  - /anything
- desc: Devuelve la dirección IP del solicitante
  id: ""
  methods:
  - GET
  name: getIP
  uris:
  - /ip
services:
- desc: Rutas para la API de httpbin
  id: ""
  name: httpbin API
  upstream:
    id: ""
    name: ""
    nodes: null
version: ""

Como puedes ver, la configuración está incompleta y aún necesitarías agregar muchas configuraciones manualmente. Estamos mejorando ADC para cerrar esta brecha entre las definiciones OpenAPI y lo que se puede mapear directamente a la configuración de APISIX.

Consejo: Usa Autocompletado

Puedes hacer mucho con ADC, y la lista de características está destinada a aumentar. Para aprender cómo usar cualquier subcomando, puedes usar la bandera --help o -h, que mostrará la documentación para el subcomando.

Para hacer las cosas aún más fáciles, puedes generar un script de autocompletado para tu entorno de shell usando el subcomando completion. Por ejemplo, si estás usando un shell zsh, puedes ejecutar:

adc completion zsh

Luego puedes copiar y pegar la salida en tu archivo .zshrc, y comenzará a mostrar sugerencias cuando uses adc.

ADC todavía está en su infancia y se está mejorando continuamente. Para obtener más información sobre el proyecto, reportar errores o sugerir características, visita github.com/api7/adc.