APISIX (Griaule Bus)
Introduction
Apache APISIX provides advanced traffic management features such as load balancing, dynamic upstream, circuit breaking, authentication, observability, etc.
Manual Installation
Installation
This installation method is only necessary if you need to install APISIX manually and use the API commands via the command line. Otherwise, use the Docker installation detailed in the APISIX Dashboard.
Installing etcd
APISIX uses etcd to save and synchronize configuration. Before installing APISIX, you need to install etcd on your machine. It will be installed automatically if you choose the Docker or Helm installation method during APISIX installation.
If you choose a different method or need to install it manually, follow the steps shown below:
<Tabs groupId="os" defaultValue="linux" values={[
{
label: 'Linux',
value: 'linux'
},
{
label: 'macOS',
value: 'mac'
}]}>Installation via RPM package
If the OpenResty is not installed, you can run the command below to install the OpenResty and APISIX repositories:
With OpenResty installed, the command below will install the APISIX repositories:
Then, to install APISIX, use:
You can also install a specific version of the APISIX package by specifying it explicitly:
Offline RPM package installation
First, download the offline RPM package for an APISIX repository:
Then, copy the APISIX repository to the desired host and run:
Managing the APISIX server
Once APISIX has been installed, you can initialize the configuration file and the etcd by running the command:
To start the APISIX server, use:
The command apisix help returns a list of available operations and can be useful on various occasions.
If you want to build APISIX from source, see Building APISIX from source.
Configuring APISIX
APISIX can be configured in two ways:
Directly changing the configuration file
conf/config.yaml.Using the command
--configor the flag-cto specify the path to your configuration file while APISIX is being started:
APISIX will use the configurations added in that configuration file and will fall back to the default configuration if something is not configured.
For example, to configure the default listening port to be 8000 without changing other settings, your configuration file should be modified as follows:
Now, if you decide you want to change the etcd address to http://foo:2379, you can add it to your configuration file. This will not change other settings.
Configuration should only be changed by the methods mentioned above. The default APISIX configuration can be found in the file conf/config-default.yaml and should not be modified. The default configuration is tied to the source code.
The file conf/nginx.conf is generated automatically and should not be modified.
Updating the Admin API key
It is recommended to change the Admin API key to ensure the application's security. To change this setting, simply modify the configuration file as shown below:
With this, to access the Admin API, use the newly configured key:
Adding the APISIX systemd unit file
If you installed APISIX via RPM, the APISIX unit file will already be configured and you can start APISIX by:
If you installed APISIX by other methods, you can create /usr/lib/systemd/system/apisix.service and add the configuration template.
The Getting Started page of APISIX provides a guide with instructions for properly using the API.
Installed packages
APISIX Dashboard (Recommended)
Docker
It is recommended to use Docker to run the Dashboard, using the commands:
Replace <CONFIG_FILE> with the path to your configuration file.
RPM
Only necessary in the case of NOT using Docker.
Only CentOS 7 is supported currently.
Installation
Install the RPM package with the following command:
Running
Run the Dashboard in the shell:
or as a service:
If the default configuration was used, visit http://127.0.0.1:9000 to use the Dashboard.
The default username and password are admin.
Access
By default, the APISIX API will run on port 9080 of the machine.
For example, on the machine 172.16.0.66:
http://172.16.0.66:9080/apisix/admin/routes?api_key=newsupersecurekey
In summary, the services run by APISIX can be accessed on the following default ports: 9080, 9082, 2379, 9000, 3000, 9090 and 9081.
The APISIX Dashboard, which allows configuring the bus through a graphical interface, runs on port 9000, for example.
Configuring an API
Web application APIs implement a variety of endpoints responsible for processing and returning information related to the applications' databases, the GBDS and performed operations. Most endpoints are application-specific, but some are common among them and are implemented in what is called the Common Server.
All API calls used by the application must be configured in APISIX. There are 2 alternatives to configure an API, described below.
Configuring the API via the APISIX Dashboard (Recommended)
Configuring the API through the APISIX Dashboard is recommended because the Dashboard's graphical interface allows importing the API via OpenAPI files in the .json or .yaml. To enable importing the API through the Dashboard, you must obtain the OpenAPI file of the application being configured.
Generating the OpenAPI file from the server
The web application servers implement Swagger for documenting their endpoints. To generate the API documentation file, just access the server and make a GET to the route /service/swagger.yaml.
On the ETR, for example, just access:
http://172.16.0.70:8089/gbs-etr-server/service/swagger.yaml
When accessing this endpoint in the browser, for example, the file will be downloaded .yaml.
To be imported into APISIX, this file must be converted to the OpenAPI 3.0 format. The simplest way to do this is to access the Swagger Editor and follow these steps:
Import the generated file on the site by clicking File > Import file.
Convert to OpenAPI 3.0 by clicking Edit > Convert to OpenAPI 3.0.
Save the file in OpenAPI format (as
.yamlor.json) by clicking File > Save as YAML or Convert and save as JSON.
In practically all applications there are endpoints that end up not being used/called by the frontend and pollute the file. It is recommended that these endpoints be removed from the file, along with their respective schemas and components.
Importing the API via the Dashboard
With APISIX running, go to http://localhost:9000 and you will be redirected to the Dashboard. If login is required, by default access is done using the username and password admin/admin.
Before importing the API routes, it is recommended to create an Upstream - which is basically the Backend Server of the API being configured. This step is done in the Upstream tab of the Dashboard. For this, you need to define a name for the server, the IP and the port at which it is running.
Below is an example of the Upstream configuration for the ETR that is running on the machine 172.16.0.66:
Once the Upstream is configured, you can import the API routes using the generated OpenAPI 3.0 file:
Go to the Route tab.
Click the Advanced? dropdown menu.
Click Import OpenAPI.
Select the file and click the Confirm button.
If everything is correct, the API routes will be imported into the dashboard and will be listed as in this example:
If there are problems importing the OpenAPI file, consult the FAQ.
Configuring the imported routes
Once the routes have been imported by the Dashboard, some adjustments are still required so that the endpoints can be accessed by the applications.
Mapping the routes
The first point to be adjusted is the path of the route, that is, the address that will be accessed so that APISIX correctly identifies the endpoint call.
By default, when generating the Swagger documentation for an application, the mapped routes will be relative to the server default.
On the ETR, for example, the endpoints generated are /etr/list or /commons/version. However, to access that endpoint through the web application or directly via command line, it is necessary to access the path /gbs-etr-server/service/<endpoint_path>.
Therefore, it is necessary to change the attribute path of the imported routes and add the default route of the API being configured, including, for example, the path gbs-API-server/service (web applications' default) before the mapped routes.
Adding the HTTP OPTIONS method
When importing the routes, they will be mapped only with the default HTTP method they execute. However, most calls made through web applications, by React's default, also perform an OPTIONS method - used so a client can discover which request options are allowed for a given resource - and if this is not mapped in APISIX, a CORS error may occur when the application makes the call.
Therefore, it is important that the OPTIONS method be added to the routes to avoid API communication problems with APISIX.
This step is necessary only to access the bus through other applications (Frontend/React, for example) - not necessary for direct access - and aims to resolve CORS (Cross-Origin Resource Sharing) issues, but it is not the only possible alternative.
Defining the Upstream (Backend API Server)
In addition to configuring the route and the expected methods, it is necessary to define the address of the server to which requests will be redirected by APISIX. This is the step where the previously defined Upstream is used.
In the second configuration tab of the route, you can define the Backend API Server and, once the Upstream has been previously configured, you can select it via the dropdown menu at the top of the page.
Just select the correct option and the calls will already be correctly configured, as shown in the image below:
Configuring Plugins
Next, you can configure the APISIX plugins that will be used by the route.
By default, every imported route already has the request-validation plugin enabled, which validates the parameters sent with the request before forwarding it to the server. It is recommended to remove this plugin for all routes, since validation is already performed by the servers.
There are several types of plugins that can be configured for routes to control/manage Authentication, Security, Traffic Control, among other aspects of the route, as can be seen on the configuration screen:
For use by Griaule applications, some interesting plugins are: limit-conn, limit-count, limit-req, traffic-split, among others.
Go to the plugins page for more details about each of the plugins available in APISIX.
APISIX offers the possibility of developing custom plugins. Click here for more information.
In the Plugin tab of the Dashboard it is possible to enable a number of plugins for the API being configured.
Plugins enabled in the Plugin tab of the Dashboard are enabled globally for the API being configured. In tests, global plugins only worked when none of the routes had a plugin associated with them.
Services and Consumers (Not used in tests)
Through the Dashboard it is also possible to define Services and Consumers, which aim to simplify the configuration of plugins for certain routes.
Instead of configuring plugins individually for each route, it is possible to configure a set of plugins in a Consumer, for example. Then, once APISIX identifies that specific Consumer (through an authentication plugin), the plugins configured for that Consumer begin to work on the requested route.
Another alternative is to define an Upstream + Plugins through a Service.
For this, use the Service and Consumer tabs of the Dashboard.
For more details, visit the Services documentation and the Consumers documentation.
By following these steps, it is possible to configure an API for APISIX.
If you have any questions or problems with the Dashboard, check the User Guide in the official APISIX Documentation or the help channels specified in the documentation.
After configuring the routes, you need to publish them through the dashboard so they can be accessed correctly.
Configuring the API via command line/configuration
APISIX allows configuring the application and its routes via the command line and configuration file, as detailed here. For this, you need to specify the server (Upstream) and each of its routes, and follow the step-by-step below:
Accessing the APISIX Admin
Expected response (indicates that APISIX is running correctly):
Creating a Route
This configuration indicates that all incoming requests matching the Upstream service (httpbin.org:80) will be forwarded if they meet these specified criteria:
The HTTP method of the request is
GET.The request header contains the host field and its value is
example.com.The request path matches
/anything/*, where*means any subpath. For example,/anything/foo?arg=10.
With the Route created, you can access the Upstream service from the address exposed by APISIX:
This request will be forwarded to http://httpbin.org:80/anything/foo?arg=10 by APISIX.
Instead of configuring the Upstream directly for the Route, you can create an Upstream object and use it in the Route.
Creating an Upstream
This is the same as the Upstream service that was configured directly in the Route in the previous section.
Binding this Upstream to the Route
You can use the upstream_id as 1:
With the Route created, you can access the Upstream service from the address exposed by APISIX:
This request will be forwarded to http://httpbin.org:80/anything/foo?arg=10 by APISIX.
Importing an API exported by APISIX
To facilitate API configuration, along with product releases, a file is made available .yaml generated by APISIX with the routes used by each of the web applications.
With this, it is possible to import the routes directly through the Dashboard, speeding up the configuration process on the bus.
However, APISIX's import/export functionality has some limitations and, therefore, additional steps are required after import so that the bus works as expected.
To facilitate exporting the files, the parameter validation plugin was removed from the routes before their export. Validation is performed by the servers.
Create an Upstream
When exporting the application's routes through APISIX, the Upstream of each route (Backend API Server) is exported as if it had been specified for each of the routes. This behavior makes API configuration difficult if there are changes in the application's server address, machine changes, etc.
Therefore, it is recommended to create an Upstream related to the application server being configured on the bus to centralize the server and facilitate possible changes.
When creating the Upstream, pay attention to the timeouts specified for the server (it is possible to configure connection, send and receive timeout). On slow servers, if the request takes longer than the specified timeout to return, a 504 Error will be returned by APISIX itself.
By default, the exported routes will point to their respective server running at IP 172.16.0.66 (development machine).
Configuring the Routes
As mentioned earlier, the functionality to export an API's configurations through APISIX has some flaws and, therefore, to fully configure the API on the bus, some changes must be made to all routes that were imported from the generated .yaml file.
Although they are specified in the file generated by APISIX, calls with the HTTP request type OPTIONS are not converted for the routes imported into APISIX.
For this reason, to allow web applications to access the routes, it is necessary to modify route by route and add the OPTIONS method as one of the possible methods so that requests work as expected, avoiding CORS errors.
Adding the OPTIONS method is the only modification necessary in the Define API Request tab.
Next, in the Define API Backend Server tab, you must change the server (using the dropdown menu) and select the Upstream related to the application server being configured - which should have been created previously.
In the Plugins tab, only plugins that are specific to the route being configured should be added. Otherwise, you can enable plugins in the Plugin tab of the Dashboard. Plugins enabled in the Plugin tab are enabled globally and will work for all routes configured in APISIX.
Thus, for each of the imported routes it is necessary to:
Add OPTIONS method
Select the Upstream
Configure plugin (only if it is specific to the route being configured)
Publish
By following these steps, it is possible to import the API exported through APISIX and use the bus features to access the application.
Accessing the Routes
After configuring all application routes and publishing them, to access them through the web application, you need to configure the application to make calls through the bus.
If you are running APISIX on your machine, just configure the route to:
http://127.0.0.1:9080/<application_name>/service
Or to the port 9080 of the machine running APISIX.
FAQ
For more specifications, step-by-step or questions, you can consult the Official Documentation or access APISIX support channels.
Error importing OpenAPI file
APISIX reports a formatting error in the file
When trying to import the OpenAPI file through the APISIX Dashboard, if the generated file is not correctly formatted, an error toast will be shown on the screen. To validate whether the file is a valid OpenAPI, use the Swagger Editor (which reports the error or unused parameters) or another validation tool.
APISIX Dashboard crashes and logs out the user after importing file
During import tests through the Dashboard, 2 situations were found that led to this error. Both were related to an unidentified problem in schemas declared in the swagger.yaml.
A practical example, found when importing the ETR, was identified in the endpoint /commons/version in the schema SystemConfiguration declared as a bodyRequest parameter of the endpoint:
On that occasion, this schema was removed from the OpenAPI file and the import occurred without issues. After investigation, it was found that the exported schema was out of date compared to what the server expected but, even after the fix, the error persisted.
In this case, the alternative is to remove the problematic schema and perform the import again.
By doing this, the schema will not be mapped to the request-validation plugin and a request with an incorrect parameter will pass through APISIX. However, this ends up not being a problem because an incorrect parameter will cause an error on the server itself, which will be returned to the user, mitigating the absence of the schema in the imported file.
In the case of the BEST, for example, the adopted alternative was replace all requestBody attributes with an empty object ({}) and add some parameter for validation in the header - this is only valid if parameter validation is disabled for the routes. Otherwise, it will cause a Bad request error from APISIX when receiving the request.
Another alternative to try to solve the problem is to check APISIX's question channels (Slack, GitHub and blogs) for definitive solutions to this problem. Although it was found that this problem is related to the schemas data.
declared in our servers, a definitive solution was not found
Plugin configured on the route is not working By default, when adding a plugin to the Route or to the Consumer, the plugin is marked asdisabled Enabled and ensure it is active so that the plugin works correctly on the route.
Unable to access the APISIX bus after running it
During tests of the bus using APISIX, it was found that routes were not being correctly recognized/redirected by APISIX, even though it was running correctly via Docker.
After investigating the problem, it was found that there was an application running on port 9080 of the machine, which is the port used by the APISIX API. This causes the APISIX API to be inaccessible and the routes are not found when making a request. The solution is to stop the process running on the target port, or change APISIX's default port through the configuration file.
Last updated
Was this helpful?