# APISIX (Bus 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 {% hint style="warning" %} 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](#apisix-dashboard-recomendado). {% endhint %} #### 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: ```tsx ``` ```sh 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: ```sh sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm ``` Con el *OpenResty* instalado, el siguiente comando instalará los repositorios APISIX: ```sh sudo yum-config-manager --add-repo https://repos.apiseven.com/packages/centos/apache-apisix.repo ``` Entonces, para instalar *APISIX*, use: ```sh sudo yum install apisix ``` {% hint style="success" %} También puede instalar una versión específica de APISIX, especificándola explícitamente: ```sh sudo yum install apisix-2.13.1 ``` {% endhint %} #### Instalación mediante paquete RPM offline Primero, descargue el paquete RPM offline para un repositorio APISIX: ```sh 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 apisix ``` Luego, copie el repositorio APISIX al host deseado y ejecute: ```sh sudo yum install ./apisix/*.rpm ``` ### Administrando el servidor APISIX Una vez que APISIX haya sido instalado, puede inicializar el archivo de configuración y el *etcd* ejecutando el comando: ```sh apisix init ``` Para iniciar el servidor APISIX, use: ```sh apisix start ``` {% hint style="success" %} El comando `apisix help` devuelve una lista de operaciones disponibles y puede ser útil en varias ocasiones. {% endhint %} Si desea compilar APISIX desde el código fuente, consulte [Building APISIX from source](https://github.com/apache/apisix/blob/master/docs/en/latest/building-apisix.md). ### Configurando APISIX Es posible configurar APISIX de dos maneras: 1. Modificando directamente el archivo de configuración `conf/config.yaml`. 2. Usando la opción `--config` o la bandera `-c` para especificar la ruta de su archivo de configuración mientras APISIX se inicia: ```sh apisix start -c ``` 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: ```yml apisix: node_listen: 8000 ``` Ahora, 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. ```yml apisix: node_listen: 8000 etcd: host: "http://foo:2379" ``` {% hint style="warning" %} 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. {% endhint %} {% hint style="warning" %} El archivo `conf/nginx.conf` se genera automáticamente y no debe ser modificado. {% endhint %} #### 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: ```sh apisix: admin_key - name: "admin" key: newsupersecurekey role: admin ``` Con esto, para acceder a la API Admin, use la nueva clave configurada: ```sh curl http://127.0.0.1:9080/apisix/admin/routes?api_key=newsupersecurekey -i ``` ### Agregando 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: ```sh systemctl start apisix systemctl stop apisix ``` Si 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](https://github.com/apache/apisix) 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: ```sh docker pull apache/apisix-dashboard docker run -d --name dashboard \ -p 9000:9000 \ -v :/usr/local/apisix-dashboard/conf/conf.yaml \ apache/apisix-dashboard ``` {% hint style="info" %} Reemplace `` con la ruta de su archivo de configuración. {% endhint %} ### RPM Es necesario solo en caso de **NO** uso de Docker. {% hint style="info" %} Solo CentOS 7 es compatible actualmente. {% endhint %} #### Instalación Instale el paquete RPM con el siguiente comando: ```sh sudo yum install -y https://github.com/apache/apisix-dashboard/releases/download/v2.13/apisix-dashboard-2.13-0.el7.x86_64.rpm ``` #### Ejecución Ejecute el Dashboard en el shell: ```sh sudo manager-api -p /usr/local/apisix/dashboard/ ``` o como un servicio: ```sh systemctl start apisix-dashboard ``` Si se utilizó la configuración predeterminada, visite `http://127.0.0.1:9000` para usar el Dashboard. {% hint style="info" %} El usuario y contraseña predeterminados son `admin`. {% endhint %} ## 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`. ![apisix standard ports](https://974439850-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7Bx0xNdsdGHpCZ20yxbn%2Fuploads%2Fgit-blob-c5b45302917122329dabb3809c52b3e35cb84865%2FapisixStandardPorts.png?alt=media) 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) ![apisix dashboard home screen](https://974439850-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7Bx0xNdsdGHpCZ20yxbn%2Fuploads%2Fgit-blob-daad070977dd73c56ba554e9885df4b8ce01bcd5%2FapisixDashboardHomeScreen.png?alt=media) 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](https://editor.swagger.io) y seguir los siguientes pasos: 1. Importar el archivo generado en el sitio haciendo clic en File > Import file. 2. Convertir a OpenAPI 3.0 haciendo clic en Edit > Convert to OpenAPI 3.0. 3. Guardar el archivo en formato OpenAPI (como `.yaml` o `.json`) haciendo clic en File > Save as YAML o Convert and save as JSON. {% hint style="info" %} En prácticamente todas las aplicaciones existen endpoints que terminan no siendo utilizados/llamados por el frontend y *contaminan* el archivo. Se recomienda entonces que esos endpoints sean eliminados del archivo, junto con sus respectivos *schemas* y componentes. {% endhint %} #### 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`: ![apisix upstream configuration example](https://974439850-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7Bx0xNdsdGHpCZ20yxbn%2Fuploads%2Fgit-blob-1b4eb491b5e7aad451cff307ba213c8aa225726c%2FapisixConfigureUpstreamExample.png?alt=media) Una vez configurado el Upstream, es posible importar las rutas de la API mediante el archivo OpenAPI 3.0 generado: 1. Acceda a la pestaña Route. 2. Haga clic en el menú desplegable Advanced?. 3. Haga clic en Import OpenAPI. 4. 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: ![apisix dashboard route list](https://974439850-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7Bx0xNdsdGHpCZ20yxbn%2Fuploads%2Fgit-blob-ac4c98b3475f66361b67a38d2cb54f001944ab86%2FapisixDashboardRouteList.png?alt=media) {% hint style="success" %} En caso de problemas al importar el archivo OpenAPI, consulte el [FAQ](#faq). {% endhint %} #### 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. {% stepper %} {% step %} #### 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. {% hint style="info" %} Por defecto, al generar la documentación Swagger de una aplicación, las rutas mapeadas serán relativas al default del servidor. {% endhint %} 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/`. 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. ![apisix map imported routes](https://974439850-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7Bx0xNdsdGHpCZ20yxbn%2Fuploads%2Fgit-blob-1856b8900fb40c264e665273a5aaa7ab4a065ae6%2FapisixMapImportedRoutes.png?alt=media) {% endstep %} {% step %} #### 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. {% hint style="info" %} Esta etapa es necesaria solo para acceder al bus desde otras aplicaciones (Frontend/React, por ejemplo) - no es necesaria para acceso directo - y busca resolver problemas de CORS (Cross-Origin Resource Sharing), sin embargo no es la única alternativa posible. {% endhint %} ![apisix add http options](https://974439850-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7Bx0xNdsdGHpCZ20yxbn%2Fuploads%2Fgit-blob-d9bb273d33b58d8ea9956a2eea3162a9bcf1a03c%2FapisixAddHttpOptions.png?alt=media) {% endstep %} {% step %} #### 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: ![apisix route configuration](https://974439850-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7Bx0xNdsdGHpCZ20yxbn%2Fuploads%2Fgit-blob-21348a271cc8be301034e3c763fa52e4ec917409%2FapisixConfigureRoute.png?alt=media) {% endstep %} {% step %} #### 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: ![apisix plugins configuration](https://974439850-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7Bx0xNdsdGHpCZ20yxbn%2Fuploads%2Fgit-blob-736fc710c98e856e817ba0686d7549e499790399%2FapisixRoutesPluginsConfig.png?alt=media) 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](https://apisix.apache.org/plugins/) para más detalles sobre cada uno de los plugins disponibles en APISIX. {% hint style="success" %} APISIX ofrece la posibilidad de desarrollar plugins propios. [Haga clic aquí](https://apisix.apache.org/docs/apisix/plugin-develop/) para más información. {% endhint %} {% hint style="info" %} En la pestaña Plugin del Dashboard es posible habilitar una serie de plugins para la API que se está configurando. {% endhint %} {% hint style="info" %} Los plugins habilitados en la pestaña Plugin del Dashboard se habilitan globalmente para la API que se está configurando. En las pruebas, los plugins globales solo funcionaron cuando ninguna de las rutas tenía un plugin asociado a ellas. {% endhint %} {% endstep %} {% endstepper %} #### 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. {% hint style="success" %} Para más detalles, acceda a la [documentación de Services](https://apisix.apache.org/docs/apisix/terminology/service/) y a la [documentación de Consumers](https://apisix.apache.org/docs/apisix/terminology/consumer/). {% endhint %} 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](https://apisix.apache.org/docs/dashboard/USER_GUIDE/) o los canales de ayuda especificados en la documentación. {% hint style="info" %} Después de configurar las rutas, es necesario publicarlas a través del dashboard para que puedan ser accedidas correctamente. {% endhint %} ### 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í](https://apisix.apache.org/docs/apisix/getting-started/). 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 ```sh curl "http://127.0.0.1:9080/apisix/admin/services/" -H 'X-API-KEY:edd1c9f034335f136f87ad84b625c8f1' ``` Respuesta esperada (indica que APISIX se está ejecutando correctamente): ```json { "count": 0, "action": "get", "node": { "key": "/apisix/services", "nodes": [], "Dir": true } } ``` #### Creando una Ruta ```sh 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: ```sh 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. {% hint style="success" %} En lugar de configurar el Upstream directamente para la Ruta, puede crear un objeto Upstream y usarlo en la Ruta. {% endhint %} #### Creando un Upstream ```sh 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 } }' ``` {% hint style="info" %} Este es el mismo que el servicio Upstream que se configuró directamente en la Ruta en la sección anterior. {% endhint %} #### Vincular este Upstream a la Ruta Se puede usar el `upstream_id` como `1`: ```sh 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: ```sh 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. {% hint style="info" %} Para facilitar la exportación de los archivos, el plugin de validación de parámetros fue eliminado de las rutas antes de su exportación. La validación la realizan los servidores. {% endhint %} ### 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. {% hint style="info" %} Al crear el Upstream, preste atención a los timeouts especificados para el servidor (es posible configurar timeout de conexión, envío y recepción). En servidores lentos, si la petición tarda más que el timeout especificado en responder, se devolverá un *Error 504* por el propio APISIX. {% endhint %} {% hint style="info" %} Por defecto, las rutas exportadas apuntarán a su servidor correspondiente que se está ejecutando en la IP `172.16.0.66` (máquina de desarrollo). {% endhint %} ### 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. {% hint style="info" %} La adición del método OPTIONS es la única modificación necesaria en la pestaña Define API Request. {% endhint %} 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: 1. Añadir el método OPTIONS 2. Seleccionar el Upstream 3. Configurar plugin (solo si es específico a la ruta que se está configurando) 4. 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//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](https://apisix.apache.org/docs/apisix/getting-started/) 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](https://editor.swagger.io) (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: ```yml # ... 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. ![pantalla del editor de plugins de apisix](https://974439850-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7Bx0xNdsdGHpCZ20yxbn%2Fuploads%2Fgit-blob-f8f826bfd1c59152e011517d2ed05cfee72b33c5%2FapisixPluginEditor.png?alt=media) ### 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.