Configuración de la Puerta de API APISIX

Apache APISIX es una puerta de API moderna de código abierto construida sobre Nginx y Lua, diseñada para arquitecturas cloud-native y microservicios. APISIX aprovecha etcd para la gestión de configuración, habilitando actualizaciones en tiempo real sin reinicios. Esta guía cubre instalación, configuración de rutas y upstreams, gestión de complementos, integración de etcd, acceso a panel de control, configuración de SSL y mecanismos de autenticación.

Tabla de Contenidos

1. Introducción a APISIX
2. Requisitos del Sistema
3. Métodos de Instalación
4. Implementación con Docker Compose
5. Configuración de etcd
6. Configuración de Rutas
7. Configuración de Upstreams
8. Gestión de Complementos
9. Acceso al Panel de Control
10. Gestión de Certificados SSL
11. Complementos de Autenticación
12. API de Administración
13. Solución de Problemas

Introducción a APISIX

Apache APISIX proporciona una puerta de API de próxima generación con:

• Enrutamiento dinámico sin reinicios
• Configuración centralizada basada en etcd
• 100+ complementos para autenticación, limitación de velocidad y transformación
• Soporte para gRPC y HTTP/3
• Recarga en caliente en tiempo real
• Secuencias de comandos Lua de alto rendimiento
• Opciones de implementación nativas de Kubernetes

La arquitectura de APISIX separa el plano de datos (puerta de enlace) del plano de control (configuración), habilitando implementaciones escalables y flexibles.

Requisitos del Sistema

Asegúrese de que su sistema cumpla con:

• Kernel de Linux 3.10 o superior
• 1 GB de RAM mínimo (2 GB recomendado)
• etcd 3.4+ para configuración distribuida
• 100 MB de espacio en disco
• Acceso de red a servicios backend

Métodos de Instalación

APISIX puede implementarse mediante Docker Compose, gestores de paquetes o compilación de fuentes.

Implementación con Docker Compose

Cree un docker-compose.yml completo para APISIX con etcd:

version: '3.8'

services:
  etcd:
    image: quay.io/coreos/etcd:v3.5.13
    restart: always
    ports:
      - "2379:2379"
      - "2380:2380"
    environment:
      ETCD_LISTEN_CLIENT_URLS: http://0.0.0.0:2379
      ETCD_ADVERTISE_CLIENT_URLS: http://etcd:2379
      ETCD_LISTEN_PEER_URLS: http://0.0.0.0:2380
      ETCD_INITIAL_ADVERTISE_PEER_URLS: http://etcd:2380
      ETCD_INITIAL_CLUSTER: default=http://etcd:2380
      ETCD_INITIAL_CLUSTER_STATE: new
      ETCD_INITIAL_CLUSTER_TOKEN: etcd-cluster
    volumes:
      - etcd_data:/etcd-data

  apisix:
    image: apache/apisix:3.7-alpine
    restart: always
    ports:
      - "80:9080"
      - "443:9443"
      - "9180:9180"
    depends_on:
      - etcd
    volumes:
      - ./apisix_config.yaml:/usr/local/apisix/conf/config.yaml:ro
      - ./certs:/usr/local/apisix/conf/ssl:ro
    environment:
      APISIX_ADMIN_ALLOW_ADMIN: "true"
    command: apisix start

  apisix-dashboard:
    image: apache/apisix-dashboard:3.7-alpine
    restart: always
    ports:
      - "9000:9000"
    depends_on:
      - etcd
    environment:
      ETCD_ENDPOINTS: http://etcd:2379

volumes:
  etcd_data:

networks:
  default:
    name: apisix_network

Implemente la pila:

docker-compose up -d

Verifique que APISIX está ejecutándose:

curl http://localhost:9180/apisix/admin/version

Configuración de etcd

APISIX utiliza etcd como almacén de configuración. Configure el endpoint de etcd en la configuración de APISIX:

Cree apisix_config.yaml:

apisix:
  node_listen: 9080
  admin_listen: 9180
  admin_api_version: v3
  enable_admin: true
  admin_key: "edd1c9f034335f136f87ad84b625c8f1"
  
  ssl:
    listen_port: 9443
    enable_http2: true

etcd:
  host:
    - "http://etcd:2379"
  prefix: /apisix
  timeout: 30
  resync_delay: 5

plugins:
  - basic-auth
  - key-auth
  - jwt-auth
  - rate-limiting
  - request-id
  - cors
  - proxy-rewrite
  - log-rotate

log_level: notice
log_format: json

Verifique la conectividad de etcd:

curl http://localhost:2379/version

Configuración de Rutas

Cree rutas a través de la API de Administración de APISIX. Una ruta asigna solicitudes a upstreams:

curl -X POST http://localhost:9180/apisix/admin/routes \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "web-route",
    "uri": "/",
    "methods": ["GET", "POST", "PUT", "DELETE"],
    "upstream_id": "web-upstream",
    "plugins": {
      "cors": {
        "allow_origins": "*",
        "allow_methods": "*",
        "allow_headers": "*",
        "expose_headers": "*",
        "max_age": 5
      }
    }
  }'

Cree rutas basadas en host:

curl -X POST http://localhost:9180/apisix/admin/routes \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "api-route",
    "host": "api.example.com",
    "uri": "/api/*",
    "upstream_id": "api-upstream",
    "strip_uri": true
  }'

Cree enrutamiento basado en ruta con múltiples rutas:

curl -X POST http://localhost:9180/apisix/admin/routes \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "blog-route",
    "host": "blog.example.com",
    "uri": "/",
    "upstream_id": "blog-upstream"
  }'

curl -X POST http://localhost:9180/apisix/admin/routes \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "static-route",
    "uri": "/static/*",
    "upstream_id": "static-upstream",
    "strip_uri": true
  }'

Liste todas las rutas:

curl http://localhost:9180/apisix/admin/routes \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1"

Actualice una ruta:

curl -X PATCH http://localhost:9180/apisix/admin/routes/web-route \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{"plugins": {"request-id": {"header_name": "X-Request-ID"}}}'

Elimine una ruta:

curl -X DELETE http://localhost:9180/apisix/admin/routes/web-route \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1"

Configuración de Upstreams

Los upstreams definen grupos de servicios backend. Cree un upstream:

curl -X POST http://localhost:9180/apisix/admin/upstreams \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "web-upstream",
    "type": "roundrobin",
    "nodes": {
      "192.168.1.100:8000": 1,
      "192.168.1.101:8000": 1,
      "192.168.1.102:8000": 1
    },
    "timeout": {
      "connect": 5,
      "send": 10,
      "read": 10
    },
    "checks": {
      "active": {
        "http_path": "/health",
        "healthy": {
          "interval": 2,
          "successes": 1
        },
        "unhealthy": {
          "interval": 1,
          "http_failures": 5
        }
      }
    }
  }'

Cree upstream con equilibrio de carga ponderado:

curl -X POST http://localhost:9180/apisix/admin/upstreams \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "api-upstream",
    "type": "roundrobin",
    "nodes": {
      "192.168.1.110:8080": 3,
      "192.168.1.111:8080": 1
    }
  }'

Cree upstream con algoritmo de conexión mínima:

curl -X POST http://localhost:9180/apisix/admin/upstreams \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "blog-upstream",
    "type": "least_conn",
    "nodes": {
      "192.168.1.120:3000": 1,
      "192.168.1.121:3000": 1
    }
  }'

Gestión de Complementos

Habilite complementos globalmente o por ruta. Habilite el complemento de limitación de velocidad:

curl -X POST http://localhost:9180/apisix/admin/routes/api-route \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "/api/*",
    "upstream_id": "api-upstream",
    "plugins": {
      "limit-count": {
        "count": 100,
        "time_window": 60,
        "policy": "local",
        "key_type": "var",
        "key": "remote_addr"
      }
    }
  }'

Habilite el complemento CORS:

curl -X PATCH http://localhost:9180/apisix/admin/routes/api-route \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "plugins": {
      "cors": {
        "allow_origins": "https://example.com",
        "allow_methods": "GET,POST,PUT,DELETE",
        "allow_headers": "Content-Type,Authorization",
        "expose_headers": "X-Total-Count"
      }
    }
  }'

Habilite la transformación de solicitudes:

curl -X PATCH http://localhost:9180/apisix/admin/routes/api-route \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "plugins": {
      "proxy-rewrite": {
        "uri": "/v1",
        "headers": {
          "add": {
            "X-Custom-Header": "custom-value",
            "X-Forwarded-Proto": "https"
          }
        }
      }
    }
  }'

Acceso al Panel de Control

Acceda al panel de control de APISIX en http://localhost:9000

Credenciales predeterminadas:

• Usuario: admin
• Contraseña: admin

Configure la contraseña de administrador del panel estableciendo variables de entorno o actualizando la configuración.

Gestión de Certificados SSL

Cargue el certificado SSL a través de la API de Administración:

curl -X POST http://localhost:9180/apisix/admin/ssl \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "example-ssl",
    "cert": "'"$(cat /path/to/certificate.crt)"'",
    "key": "'"$(cat /path/to/private.key)"'",
    "sni": "example.com"
  }'

O use curl con contenido de archivo:

CERT_CONTENT=$(cat /etc/ssl/certs/example.com.crt | base64 | tr -d '\n')
KEY_CONTENT=$(cat /etc/ssl/private/example.com.key | base64 | tr -d '\n')

curl -X POST http://localhost:9180/apisix/admin/ssl \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{"id": "cert-id", "sni": "example.com", "cert": "'${CERT_CONTENT}'", "key": "'${KEY_CONTENT}'"}'

Liste certificados SSL:

curl http://localhost:9180/apisix/admin/ssl \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1"

Complementos de Autenticación

Habilite la autenticación básica en una ruta:

curl -X PATCH http://localhost:9180/apisix/admin/routes/api-route \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "plugins": {
      "basic-auth": {}
    }
  }'

Cree un consumidor con credenciales de autenticación básica:

curl -X POST http://localhost:9180/apisix/admin/consumers \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "app-client",
    "plugins": {
      "basic-auth": {
        "username": "api_user",
        "password": "secure_password"
      }
    }
  }'

Habilite la autenticación por clave:

curl -X PATCH http://localhost:9180/apisix/admin/routes/api-route \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "plugins": {
      "key-auth": {
        "header": "X-API-Key"
      }
    }
  }'

Cree credenciales de clave de API:

curl -X POST http://localhost:9180/apisix/admin/consumers/app-client/credentials \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "key-auth",
    "key": "super-secret-api-key-12345"
  }'

Habilite la autenticación JWT:

curl -X PATCH http://localhost:9180/apisix/admin/routes/api-route \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1" \
  -H "Content-Type: application/json" \
  -d '{
    "plugins": {
      "jwt-auth": {
        "secret": "your-jwt-secret-key"
      }
    }
  }'

API de Administración

APISIX proporciona una API de administración completa para todas las tareas de configuración:

Obtenga la versión de APISIX:

curl http://localhost:9180/apisix/admin/version \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1"

Obtenga información del nodo:

curl http://localhost:9180/apisix/admin/nodes \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1"

Obtenga todos los complementos:

curl http://localhost:9180/apisix/admin/plugins/list \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1"

Obtenga detalles de la ruta:

curl http://localhost:9180/apisix/admin/routes/api-route \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1"

Solución de Problemas

Compruebe los registros del contenedor de APISIX:

docker-compose logs -f apisix

Verifique que etcd está ejecutándose:

curl http://localhost:2379/version

Pruebe la conectividad de la puerta de enlace API:

curl -v http://localhost:80/

Compruebe la configuración de ruta a través de etcd:

curl http://localhost:2379/v3/kv/range \
  -d '{"key": "L2FwaXN4L3JvdXRlcw=="}'

Verifique la salud del upstream:

curl http://localhost:9180/apisix/admin/upstreams/web-upstream \
  -H "X-API-Key: edd1c9f034335f136f87ad84b625c8f1"

Compruebe si hay errores de configuración en los registros:

docker-compose logs apisix | grep -i error

Pruebe la ruta con autenticación:

curl -H "X-API-Key: super-secret-api-key-12345" http://localhost:80/api/test

Conclusión

Apache APISIX proporciona una puerta de API moderna y cloud-native con gestión de configuración dinámica a través de etcd. Su extenso ecosistema de complementos, compatibilidad con mecanismos de autenticación avanzados y actualizaciones en tiempo real sin reinicios la hacen ideal para arquitecturas de microservicios. La combinación de una potente API de administración y panel web permite la gestión flexible de requisitos complejos de enrutamiento y transformación de tráfico de API.