APISIX (Bus de Griaule)
Introducción
Apache APISIX proporciona funciones avanzadas de gestión de tráfico, como balanceo de carga, upstream dinámico, interrupción de circuito, autenticación, observabilidad, etc.
Instalación Manual
Instalación
Este método de instalación solo es necesario si se necesita instalar APISIX manualmente y usar los comandos de la API a través de la línea de comandos. De lo contrario, use la instalación mediante Docker, detallada en la sección APISIX Dashboard.
Instalando etcd
APISIX usa etcd para guardar y sincronizar la configuración. Antes de instalar APISIX, debe instalar etcd en su máquina. Se instalará automáticamente si elige el método de instalación Docker o Helm durante la instalación de APISIX.
Si elige un método diferente o necesita instalarlo manualmente, siga los pasos mostrados a continuación:
<Tabs groupId="os" defaultValue="linux" values={[
{
label: 'Linux',
value: 'linux'
},
{
label: 'macOS',
value: 'mac'
}]}>ETCD_VERSION='3.5.4'
wget https://github.com/etcd-io/etcd/releases/download/v${ETCD_VERSION}/etcd-v${ETCD_VERSION}-linux-amd64.tar.gz
tar -xvf etcd-v${ETCD_VERSION}-linux-amd64.tar.gz && \
cd etcd-v${ETCD_VERSION}-linux-amd64 && \
sudo cp -a etcd etcdctl /usr/bin/
nohup etcd >/tmp/etcd.log 2>&1 &Instalación mediante paquete RPM
Si el OpenResty no está instalado, puede ejecutar el siguiente comando para instalar los repositorios OpenResty y APISIX:
sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpmCon el OpenResty instalado, el siguiente comando instalará los repositorios APISIX:
sudo yum-config-manager --add-repo https://repos.apiseven.com/packages/centos/apache-apisix.repoEntonces, para instalar APISIX, use:
sudo yum install apisixTambién puede instalar una versión específica de APISIX, especificándola explícitamente:
sudo yum install apisix-2.13.1Instalación mediante paquete RPM offline
Primero, descargue el paquete RPM offline para un repositorio APISIX:
sudo mkdir -p apisix
sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm
sudo yum clean all && yum makecache
sudo yum install -y --downloadonly --downloaddir=./apisix apisixLuego, copie el repositorio APISIX al host deseado y ejecute:
sudo yum install ./apisix/*.rpmAdministrando el servidor APISIX
Una vez que APISIX haya sido instalado, puede inicializar el archivo de configuración y el etcd ejecutando el comando:
apisix initPara iniciar el servidor APISIX, use:
apisix startEl comando apisix help devuelve una lista de operaciones disponibles y puede ser útil en varias ocasiones.
Si desea compilar APISIX desde el código fuente, consulte Building APISIX from source.
Configurando APISIX
Es posible configurar APISIX de dos maneras:
Modificando directamente el archivo de configuración
conf/config.yaml.Usando la opción
--configo la bandera-cpara especificar la ruta de su archivo de configuración mientras APISIX se inicia:apisix start -c <path to config file>
APISIX usará las configuraciones añadidas en ese archivo de configuración y volverá a la configuración predeterminada si algo no está configurado.
Por ejemplo, para configurar el puerto de escucha predeterminado a 8000 sin cambiar otras configuraciones, su archivo de configuración debe modificarse de la siguiente manera:
apisix:
node_listen: 8000Ahora, si decide que desea cambiar la dirección etcd a http://foo:2379, puede agregarla a su archivo de configuración. Esto no cambiará otras configuraciones.
apisix:
node_listen: 8000
etcd:
host: "http://foo:2379"La configuración solo debe modificarse por los métodos mencionados anteriormente. La configuración predeterminada de APISIX se puede encontrar en el archivo conf/config-default.yaml y no debe ser modificada. La configuración predeterminada está vinculada al código fuente.
El archivo conf/nginx.conf se genera automáticamente y no debe ser modificado.
Actualizando la clave Admin de la API
Se recomienda cambiar la clave Admin de la API para garantizar la seguridad de la aplicación. Para cambiar esta configuración, simplemente modifique el archivo de configuración como se muestra a continuación:
apisix:
admin_key
-
name: "admin"
key: newsupersecurekey
role: adminCon esto, para acceder a la API Admin, use la nueva clave configurada:
curl http://127.0.0.1:9080/apisix/admin/routes?api_key=newsupersecurekey -iAgregando el archivo de unidad systemd de APISIX
Si instaló APISIX vía RPM, el archivo de unidad APISIX ya estará configurado y podrá iniciar APISIX con:
systemctl start apisix
systemctl stop apisixSi instaló APISIX mediante otros métodos, puede crear /usr/lib/systemd/system/apisix.service y agregar la plantilla de configuración.
La página Getting Started de APISIX ofrece una guía con instrucciones para usar correctamente la API.
Paquetes instalados
+----------------------------------------------------------------+
| Package Arch Version Repository Size |
+================================================================+
| Installing: |
| apisix x86_64 2.14.1-0.el7 release 2.2 M |
+----------------------------------------------------------------+
| Installing for dependencies: |
| apisix-base x86_64 1.21.4.1.0-0.el7 release 34 M |
+----------------------------------------------------------------+
| Updating for dependencies: |
| cyrus-sasl-lib x86_64 2.1.26-24.el7_9 updates 156 k |
| openldap x86_64 2.4.44-25.el7_9 updates 356 k |
+----------------------------------------------------------------+
+-------------------------------------------+
| Transaction Summary |
+===========================================+
| Install 1 Package (+7 Dependent packages) |
| Upgrade (2 Dependent packages) |
+-------------------------------------------+
| Total download size: 40 M |
+-------------------------------------------+APISIX Dashboard (Recomendado)
Docker
Se recomienda usar Docker para ejecutar el Dashboard, usando los comandos:
docker pull apache/apisix-dashboard
docker run -d --name dashboard \
-p 9000:9000 \
-v <CONFIG_FILE>:/usr/local/apisix-dashboard/conf/conf.yaml \
apache/apisix-dashboardRPM
Es necesario solo en caso de NO uso de Docker.
Instalación
Instale el paquete RPM con el siguiente comando:
sudo yum install -y https://github.com/apache/apisix-dashboard/releases/download/v2.13/apisix-dashboard-2.13-0.el7.x86_64.rpmEjecución
Ejecute el Dashboard en el shell:
sudo manager-api -p /usr/local/apisix/dashboard/o como un servicio:
systemctl start apisix-dashboardSi se utilizó la configuración predeterminada, visite http://127.0.0.1:9000 para usar el Dashboard.
Acceso
Por defecto, la API de APISIX se ejecutará en el puerto 9080 de la máquina.
Por ejemplo, en la máquina 172.16.0.66:
http://172.16.0.66:9080/apisix/admin/routes?api_key=newsupersecurekey
En resumen, los servicios ejecutados por APISIX pueden ser accedidos en los siguientes puertos predeterminados: 9080, 9082, 2379, 9000, 3000, 9090 y 9081.
El APISIX Dashboard, que permite configurar el bus a través de una interfaz gráfica, se ejecuta en el puerto 9000, por ejemplo.
Configurando una API
Las APIs de las aplicaciones web implementan una variedad de endpoints responsables de procesar y devolver información referente a las bases de datos de las aplicaciones, del GBDS y de las operaciones realizadas. La mayoría de los endpoints son específicos de la aplicación, pero algunos de ellos son comunes entre ellas y se implementan en lo que se llama Common Server.
Todas las llamadas de API usadas por la aplicación deben configurarse en APISIX. Existen 2 alternativas para configurar una API, expuestas a continuación.
Configurando la API mediante el APISIX Dashboard (Recomendado)
La configuración de la API a través del APISIX Dashboard es recomendable porque la interfaz gráfica del Dashboard permite la importación de la API mediante archivos OpenAPI en los formatos .json o .yaml. Para posibilitar la importación de la API mediante el Dashboard, es necesario obtener el archivo OpenAPI de la aplicación que se está configurando.
Generando el archivo OpenAPI desde el servidor
Los servidores de las aplicaciones web implementan Swagger para la documentación de sus endpoints. Para generar el archivo de documentación de la API, basta acceder al servidor y hacer un GET en la ruta /service/swagger.yaml.
En el ETR, por ejemplo, basta acceder a:
http://172.16.0.70:8089/gbs-etr-server/service/swagger.yaml
Al acceder a este endpoint desde el navegador, por ejemplo, se descargará el archivo .yaml.
Para ser importado en APISIX, este archivo debe convertirse al formato OpenAPI 3.0. Para ello, la forma más simple es acceder al Swagger Editor y seguir los siguientes pasos:
Importar el archivo generado en el sitio haciendo clic en File > Import file.
Convertir a OpenAPI 3.0 haciendo clic en Edit > Convert to OpenAPI 3.0.
Guardar el archivo en formato OpenAPI (como
.yamlo.json) haciendo clic en File > Save as YAML o Convert and save as JSON.
Importando la API mediante el Dashboard
Con APISIX en ejecución, acceda a http://localhost:9000 y será redirigido al Dashboard. En caso de que se solicite inicio de sesión, por defecto el acceso se realiza con el usuario y contraseña admin/admin.
Antes de importar las rutas de la API, se recomienda crear un Upstream - que es básicamente el servidor Backend de la API que se está configurando. Este paso se realiza en la pestaña Upstream del Dashboard. Para ello, es necesario definir un nombre para el servidor, la IP y el puerto en el que está ejecutándose.
A continuación se muestra un ejemplo de la configuración del Upstream de ETR que se está ejecutando en la máquina 172.16.0.66:
Una vez configurado el Upstream, es posible importar las rutas de la API mediante el archivo OpenAPI 3.0 generado:
Acceda a la pestaña Route.
Haga clic en el menú desplegable Advanced?.
Haga clic en Import OpenAPI.
Seleccione el archivo y haga clic en el botón Confirmar.
Si todo está correcto, las rutas de la API se importarán en el dashboard y quedarán listadas como en este ejemplo:
En caso de problemas al importar el archivo OpenAPI, consulte el FAQ.
Configurando las rutas importadas
Una vez que las rutas hayan sido importadas por el Dashboard, aún es necesario hacer algunos ajustes para que los endpoints puedan ser accedidos por las aplicaciones.
Mapeando las rutas
El primer punto a ajustar es el path de la ruta, es decir, la dirección que se accederá para que APISIX identifique correctamente la llamada al endpoint.
En el ETR, por ejemplo, se generan los endpoints /etr/list o /commons/version. Sin embargo, para acceder a este endpoint mediante la aplicación web o directamente vía línea de comandos, es necesario acceder a la ruta /gbs-etr-server/service/<caminho_do_endpoint>.
Por lo tanto, es necesario cambiar el atributo path de las rutas importadas y agregar la ruta base de la API que se está configurando, incluyendo, por ejemplo, el camino gbs-API-server/service (predeterminado de las aplicaciones web) antes de las rutas mapeadas.
Agregando el método HTTP OPTIONS
Al importar las rutas, se mapearán solo con el método HTTP predeterminado que ejecutan. Sin embargo, la mayoría de las llamadas realizadas por las aplicaciones web, por defecto de React, también ejecutan un método OPTIONS - usado para que un cliente pueda descubrir qué opciones de petición están permitidas para un determinado recurso - y, si este no está mapeado en APISIX, puede ocurrir un error de CORS cuando la aplicación ejecute la llamada.
Por lo tanto, es importante que se agregue el método OPTIONS en las rutas para evitar problemas de comunicación entre la API y APISIX.
Definiendo el Upstream (Backend API Server)
Además de configurar la ruta y los métodos esperados, es necesario definir la dirección del servidor al que las llamadas serán redirigidas por APISIX. Es en esta etapa donde se utiliza el Upstream definido anteriormente.
En la segunda pestaña de configuración de la ruta, es posible definir el Backend API Server y, una vez que el Upstream ya haya sido configurado previamente, es posible seleccionarlo mediante el menú desplegable al inicio de la página.
Simplemente seleccione la opción correcta y las llamadas ya estarán correctamente configuradas, como muestra la imagen a continuación:
Configurando Plugins
A continuación, es posible configurar los plugins de APISIX que serán utilizados por la ruta.
Por defecto, toda ruta importada ya tiene el plugin request-validation activado, que realiza una validación de los parámetros que se están enviando junto con la petición, antes de reenviar al servidor. Se recomienda eliminar este plugin para todas las rutas, ya que la validación ya la realizan los servidores.
Existen varios tipos de plugins que pueden configurarse para las rutas, con el objetivo de controlar/gestionar Autenticación, Seguridad, Control de Tráfico, entre otros aspectos de la ruta, como se puede ver en la pantalla de configuración:
Para el uso de las aplicaciones de Griaule, algunos plugins interesantes son: limit-conn, limit-count, limit-req, traffic-split, entre otros.
Acceda a la página de plugins para más detalles sobre cada uno de los plugins disponibles en APISIX.
APISIX ofrece la posibilidad de desarrollar plugins propios. Haga clic aquí para más información.
Services y Consumers (No utilizados en las pruebas)
A través del Dashboard también es posible definir Services y Consumers, que buscan facilitar la configuración de plugins para determinadas rutas.
En lugar de configurar los plugins individualmente para cada ruta, es posible configurar una serie de plugins en un Consumer, por ejemplo. Luego, una vez que APISIX identifica ese Consumer específico (mediante un plugin de autenticación), los plugins configurados para ese Consumer pasan a funcionar en la ruta solicitada.
Otra alternativa es definir un Upstream + Plugins mediante un Service.
Para ello, se usan las pestañas Service y Consumer del Dashboard.
Para más detalles, acceda a la documentación de Services y a la documentación de Consumers.
Siguiendo estos pasos, es posible configurar una API para APISIX.
En caso de dudas o problemas con el Dashboard, consulte el Guía del Usuario en la documentación oficial de APISIX o los canales de ayuda especificados en la documentación.
Configurando la API por línea de comandos/configuración
APISIX permite la configuración de la aplicación y sus rutas mediante la línea de comandos y archivo de configuración, como se detalla aquí. Para ello, es necesario especificar el servidor (Upstream) y cada una de sus rutas, y seguir el paso a paso a continuación:
Acceso al Admin de APISIX
curl "http://127.0.0.1:9080/apisix/admin/services/" -H 'X-API-KEY:edd1c9f034335f136f87ad84b625c8f1'Respuesta esperada (indica que APISIX se está ejecutando correctamente):
{
"count": 0,
"action": "get",
"node": {
"key": "/apisix/services",
"nodes": [],
"Dir": true
}
}Creando una Ruta
curl "http://127.0.0.1:9080/apisix/admin/routes/1" \
-H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \
-X PUT \
-d '{
"methods": ["GET"],
"host": "example.com",
"uri": "/anything/*",
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'Esta configuración indica que todas las solicitudes entrantes que correspondan al servicio Upstream (httpbin.org:80) serán reenviadas si cumplen con estos criterios especificados:
El método HTTP de la solicitud es
GET.El encabezado de la solicitud contiene el campo host y su valor es
example.com.La ruta de la solicitud coincide con
/anything/*, donde*significa cualquier subruta. Por ejemplo,/anything/foo?arg=10.
Con la Ruta creada, se puede acceder al servicio Upstream desde la dirección expuesta por APISIX:
curl -i -X GET "http://127.0.0.1:9080/anything/foo?arg=10" -H "Host: example.com"Esta solicitud será reenviada a http://httpbin.org:80/anything/foo?arg=10 por APISIX.
En lugar de configurar el Upstream directamente para la Ruta, puede crear un objeto Upstream y usarlo en la Ruta.
Creando un Upstream
curl "http://127.0.0.1:9080/apisix/admin/upstreams/1" \
-H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \
-X PUT \
-d '{
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}'Vincular este Upstream a la Ruta
Se puede usar el upstream_id como 1:
curl "http://127.0.0.1:9080/apisix/admin/routes/1" \
-H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \
-X PUT \
-d '{
"methods": ["GET"],
"host": "example.com",
"uri": "/anything/*",
"upstream_id": "1"
}'Con la Ruta creada, se puede acceder al servicio Upstream desde la dirección expuesta por APISIX:
curl -i -X GET "http://127.0.0.1:9080/anything/foo?arg=10" -H "Host: example.com"Esta solicitud será reenviada a http://httpbin.org:80/anything/foo?arg=10 por APISIX.
Importando una API exportada por APISIX
Con el fin de facilitar la configuración de las APIs, junto con las releases de los productos, se pone a disposición un archivo .yaml generado a través de APISIX con las rutas utilizadas por cada una de las aplicaciones web.
Con esto, es posible importar las rutas directamente a través del Dashboard, agilizando su proceso de configuración en el bus.
Sin embargo, la funcionalidad de importación/exportación de APISIX presenta algunas limitaciones y, por ello, son necesarios pasos adicionales después de la importación para que el bus funcione como se espera.
Crear un Upstream
Al exportar las rutas de la aplicación mediante APISIX, el Upstream de cada ruta (Servidor Backend API) se exporta como si hubiera sido especificado para cada una de las rutas. Este comportamiento dificulta la configuración de la API en caso de cambios en la dirección del servidor de la aplicación, cambios de máquina, etc.
Por ello, se recomienda crear un Upstream referente al servidor de la aplicación que se está configurando en el bus, para centralizar el servidor y facilitar posibles cambios.
Configurando las Rutas
Como se mencionó anteriormente, la funcionalidad de exportar las configuraciones de una API mediante APISIX presenta algunas fallas y, por ello, para configurar completamente la API en el bus, es necesario realizar algunos cambios en todas las rutas que se importaron a partir del archivo .yaml generado.
Aunque estén especificadas en el archivo generado por APISIX, las llamadas con el tipo de petición HTTP OPTIONS no se convierten para las rutas importadas en APISIX.
Por este motivo, para que las aplicaciones web puedan acceder a las rutas, es necesario modificar ruta por ruta y añadir el método OPTIONS como uno de los métodos posibles, de modo que las peticiones funcionen como se espera, evitando errores de CORS.
A continuación, en la pestaña Define API Backend Server, es necesario cambiar el servidor (usando el menú desplegable) y seleccionar el Upstream relacionado con el servidor de la aplicación que se está configurando - que debe haberse creado previamente.
En la pestaña Plugins, solo deben añadirse plugins que sean específicos a la ruta que se está configurando. De lo contrario, es posible activar los plugins en la pestaña Plugin del Dashboard. Los plugins habilitados en la pestaña Plugin se habilitan globalmente y funcionarán para todas las rutas configuradas en APISIX.
Por lo tanto, para cada una de las rutas importadas es necesario:
Añadir el método OPTIONS
Seleccionar el Upstream
Configurar plugin (solo si es específico a la ruta que se está configurando)
Publicar
Siguiendo estos pasos, es posible importar la API exportada mediante APISIX y utilizar las funcionalidades del bus para acceder a la aplicación.
Accediendo a las Rutas
Después de configurar todas las rutas de la aplicación y publicarlas, para acceder a ellas desde la aplicación web, es necesario configurar la aplicación para realizar las llamadas mediante el bus.
Si está ejecutando APISIX en su máquina, basta con configurar la ruta:
http://127.0.0.1:9080/<nombre_da_aplicación>/service
O bien al puerto 9080 de la máquina que esté ejecutando APISIX.
FAQ
Para más especificaciones, paso a paso o dudas, puede consultar la Documentación Oficial o acceder a los canales de soporte de APISIX.
Error al importar archivo OpenAPI
APISIX detecta un error de formato en el archivo
Al intentar importar el archivo OpenAPI mediante el APISIX Dashboard, si el archivo generado no está correctamente formateado, se mostrará un toast de error en la pantalla. Para validar si el archivo es un OpenAPI válido, utilice el Swagger Editor (que detecta el error o parámetros no utilizados) u otra herramienta de validación.
APISIX Dashboard se bloquea y cierra la sesión del usuario después de importar el archivo
Durante las pruebas de importación mediante el Dashboard, se constataron 2 situaciones que llevaron a este error. Ambas estaban relacionadas con un problema no identificado en schemas declarados en el archivo swagger.yaml.
Un ejemplo práctico, detectado en la importación del ETR, se identificó en el endpoint /commons/version en el schema SystemConfiguration declarado como parámetro del bodyRequest del endpoint:
# ...
post:
summary: Set system configuration
operationId: set
parameters:
- name: session-guid
in: header
schema:
type: string
requestBody:
content:
'*/*':
schema:
$ref: '#/components/schemas/SystemConfiguration'
required: false
# ...En esa ocasión, ese schema fue eliminado del archivo OpenAPI y la importación se realizó sin problemas. Tras la investigación, se constató que el schema exportado estaba desactualizado respecto a lo que el servidor esperaba pero, incluso después de la corrección, el error persistió.
En ese caso, la alternativa es eliminar el schema problemático y realizar la importación nuevamente.
Al hacer esto, el schema no será mapeado para el plugin request-validation y una petición con un parámetro incorrecto pasará por APISIX. Sin embargo, esto no resulta un problema porque un parámetro incorrecto provocará un error en el propio servidor, que se devolverá al usuario, mitigando la falta del schema en el archivo importado.
En el caso de la configuración de BEST, por ejemplo, la alternativa adoptada fue sustituir todos los atributos requestBody por un objeto vacío ({}) y añadir algún parámetro para validación en el header - esto solo es válido si la validación de parámetros está desactivada para las rutas. De lo contrario, causará un error Bad request por parte de APISIX al recibir la petición.
Otra alternativa para intentar solucionar el problema es revisar los canales de dudas de APISIX (Slack, GitHub y blogs) en busca de soluciones definitivas a este problema. Aunque se constató que este problema está relacionado con los schemas de datos declarados en nuestros servidores, no se encontró una solución definitiva.
Plugin configurado en la ruta no está funcionando
Por defecto, al añadir un plugin a la Ruta o al Consumer, el plugin se marca como deshabilitado. Por ello, preste atención a la bandera Habilitado y asegúrate de que esté activa, para que el complemento funcione correctamente en la ruta.
No es posible acceder al bus de APISIX después de ejecutarlo
Durante las pruebas del bus usando APISIX, se constató que las rutas no eran reconocidas/redirigidas correctamente por APISIX, incluso ejecutándose correctamente vía Docker.
Después de investigar el problema, se constató que había una aplicación ejecutándose en el puerto 9080 de la máquina, que es el puerto utilizado por la API de APISIX. Esto provoca que la API de APISIX quede inaccesible y las rutas no se encuentren al hacer una solicitud. La solución es finalizar el proceso que esté usando el puerto objetivo, o bien cambiar el puerto predeterminado de APISIX a través del archivo de configuración.
Última actualización
¿Te fue útil?