Hands-on lab Apache APISIX

Apache APISIX is based on a couple of primitives:

We can create a Route and configure the underlying Upstream. When Apache APISIX receives a request matching the Route, it forwards it to the underlying Upstream.

The following command creates a sample Route:

Once we have created the Route, we can check whether it works. Apache APISIX should forward the request to http://httpbin.org:80/anything/foo?arg=10.

At this point, we have created a Route and an Upstream and bound them together. Now is time to test our configuration.

It should return the expected data from the configured Upstream.

We created a new Route, Upstream, and mapped the former to the latter in the above steps.

You can also try to create an Upstream, a Route and map them using the dashboard.

The Route we have created is public. Thus, anyone can access the underlying Upstream as long as they know the endpoint Apache APISIX exposes to the outside world. It’s not safe as a malicious actor could use this endpoint. For this reason, we are going to add authentication to the Route.

Apache APISIX dashboard is running on the address http://localhost:9000/. You can navigate to this address and see the Dashboard running.

The default credentials are admin/admin.

After logging, go to Route in the navigation bar on the left side.

In the Route list, we can see the Route we created previously with curl.

Next, navigate to Upstream. Likewise, the Dashboard displays our sample Upstream.

First, we will enable key-auth plugin for the route. To do that:

Navigate to Route, click Configure and skip Define API Backend Server section and open Plugin Config

In this section, you can find key-auth plugin and click Enable. Request raw data you can keep as empty and push the toggle switch on.

Then press Submit to save changes, click Next and after Submit to update route configs.

Second, go to Consumer page from the navigation bar and click on Create, then give the Consumer a name, e.g., Example Consumer. Click Next.

For this Consumer, we will apply a key authentication. Among the many plugins available, let’s choose key auth.

Click Enable and push the toggle switch on. Then, provide a key for the Consumer, e.g., john. Submit, click Next and Submit again.

Raw JSON data for Plugin editor config:

At this point, we should have a ready-to-use Consumer.

We control the data allowed to transit via the gateway by adding authentication. We can identify unique Consumers accessing our API. Any request that does not include a valid API key will be rejected with an HTTP 401 status.

To prove it, let’s move back to the terminal and run below curl command.

Because we didn’t set the authentication key, Apache APISIX will return an unauthorized error.

Response:

We can retry the same request with the authentication key.

We can now successfully access the endpoint!

Above section showed how to use Apache APISIX to deploy, configure, and securely publish APIs from the Dashboard.

Apache APISIX API Gateway acts as a single entry point and offers many authentication plugins, including:

The JWT (JSON Web Token) plugin is another solid option for API gateway authentication. JWT simplifies authentication setup, taking care of the nitty-gritty details. Please refer to JWT for more information.

Let’s apply the JWT plugin to our existing API. We update the existing Consumer plugin config with JWT-related configuration:

The response will look something like this:

We can now add the jwt-auth plugin to the Route we have created previously:

Response:

In our modern era, API security has become increasingly important. Many hardening techniques are available:

An API Gateway can handle all those cross-cutting concerns.

Assume that we have two consumers of our APIs (jack2019 and jack2020). We want to give an access only to one of them. To do so, let’s create two consumers and enable consumer-restriction plugin for our existing Example route.

To create the first consumer, run the following command:

To create the second consumer, run the following command:

Then, enable consumer-restriction plugin:

Output:

Now we can test if the consumer jack1 can request the API resource with the provided credentials.

Output:

Now we can try to request the same path with different consumer:

However, our the second consumer has no access.

Output:

It is also possible to disable a plugin, we can delete the corresponding JSON configuration from the plugin configuration. Apache APISIX supports hot reloading; there’s no need to restart the service!

API traffic management can improve the overall visibility of one’s system and better understand the state of the traffic throughout one’s organization. A better understanding of the undergoing activities provides many opportunities to solve problems.

With the help of an API Gateway, one can set automatic retries, timeouts, circuit breakers, or rate-limiting. Rate limiting is a strategy for limiting network traffic. It puts a cap on how often someone can repeat an action within a specific timeframe – for instance, trying to log into an account.

Let’s enable the limit-count plugin on our existing Route. To do so, run the following command:

Output:

The above configuration limits the number of requests to two in 60 seconds. Apache APISIX will handle the first two requests as usual:

A third request in the same period will return a 503 HTTP code:

You can configure the failure HTTP Status 403 Forbidden by configuring rejected_code and message with the rejected_msg attributes. For example, we can set it with Requests are too frequent, please try again later. After reaching the threshold, the response is similar to the following:

Result:

API observability is the ability to understand system behavior and investigate the interactions between an application’s components. It provides for your API tracers, metrics and loggers.

The core of API observability breaks down into three key areas: structured logs, metrics, and traces. Let’s break down each pillar and learn how with Apache APISIX Plugins we can simplify these tasks.

Logs are also easy to instrument and trivial step of API observability. An API event is logged each time an API operation is invoked. You can gain analytic insights into your API activities or debug your APIs through the logged data

The following is an example of how to enable the http-logger for our specific route. You could generate a mock HTTP server at mockbin to view the logs.

To http-logger settings, we can just put our mock server uri address like below:

You will get the following response:

We can send a request to this get endpoint to generate logs.

Next, access your mock server logs and check logs

As you can see, some recent logs are sent to our mock server:

API monitoring is the process of collecting and analyzing data about the performance of an API to identify problems that impact users. If an application is running slowly, you must first understand the cause before you can correct it.

Metrics are a numeric representation of data measured over intervals of time. You can also aggregate this data into daily or weekly frequency and run queries against a distributed system like Elasticsearch. Or sometimes based on metrics you trigger alerts to take any action later. Once API metrics are collected, you can track them with metrics tracking tools such as Prometheus.

Let’s enable prometheus plugin for our route:

Response:

We fetch the metric data from the specified url /apisix/prometheus/metrics.

You will get response with Prometheus metrics something like below:

And we can also check the status of our endpoint at Prometheus dashboard by pointing to this URL http://localhost:9090/targets

As you can see, Apache APISIX exposed metrics endpoint is upon and running.

Now you can query metrics for apisix_http_status to see what http requests are handled by API Gateway and what was outcome.

In addition to this, you can view Grafana dashboard running in your local instance. Go to http://localhost:3000/

Behind the scene, Apache APISIX downloads Grafana dashboard meta, imports it to Grafana and fetches real time metrics from Prometheus plugin.

The third observability pillar is a tracing or distributed tracing allows you to understand the life of a request as it traverses your service network allows you to answer questions like what service has this request touched and how much latency was introduced.

Traces enable you to further explore which logs to look at for a particular session or related set of API calls.

Here’s an example to enable the zipkin plugin on the specified route:

Successful response looks like below:

We can test our example by simple running the following command:

Response:

As you can see, there are some additional trace identifiers (like traceId, spanId, parentId) were appended to the headers:

Then you can use a browser to access http://127.0.0.1:9411/zipkin, see traces on the Web UI of Zipkin

Serverless is a cloud-native development model that allows developers to build and run applications without having to manage servers. It provides all the continually updated infrastructure and resources needed to run your applications.

Apache APISIX provides support for serverless frameworks for popular cloud vendors such as Azure Functions

We are assuming your HTTP Trigger Function is deployed in Azure and ready to be served. Please, follow the tutorial to create your first function in the Azure portal

For the purpose of demo, the Function app is running on this address https://apisix-gateway.azurewebsites.net/

Let’s run the following cmd to enable azure-functions plugin for the route:

Response:

Now any requests (HTTP/1.1, HTTPS, HTTP2) to URI /azure on the Apache APISIX gateway will trigger an HTTP based function For example ( here Azure Cloud Function just take the name query param and returns Hello $name):

Output:

As we reviewed, the plugin can invoke Azure Functions and supports authorization to Azure cloud service via API keys and Azure active directory.

Sometimes your service requires you to use many plugins together or create custom plugins in addition to Apache Apisix provides. Plugin orchestration is a form of low-code that can help enterprises automate development.

In the Apache APISIX Dashboard’s, Plugin config web interface lists the currently available plugins and drawing boards, and we can drag and drop the plugins onto the drawing boards to arrange them.

Let’s think of new scenario where we decide the subsequent API request processing logic based on the processing result of previous plugin:

After putting all building blocks to the drawing board (plugins, condition), we will have a diagram similar to below:

We need to also configure a rule for our condition like code == 403 for negative case, if the request from unknown IP address. Double-click Condition and new Configure Rule pop-up menu appears.

You can fill in ip-restriction plugin config the following details in the Plugin Editor. Double-click on ip-restriction, apply config and click Submit.

Similarly to limit-count:

Finally, click Next and Submit the changes applied on the route.

During technological selection in a project implementation, the most important consideration for the development team is whether the chosen product matches the team’s technology stack or not. Apache APISIX has been supporting customized plugins since the day it was born.

A plugin is an important mechanism in APISIX API Gateway by using it, we can create high-performance systems under tight deadlines. With Apache APISIX we can write custom plugins in a programming language we are familiar with, including Lua, Python, Java, Go, PHP and more.

Let’s create new file-logger custom plugin. Users can use the file-logger plug-in to append JSON-formatted request and response data to log files, or push the Log data stream to a specified location given in the path.

Below the whole process of new plugin creation:

The source code is located in custom-plugin folder in the project.

Up to now, we have already prepared example_upstream locally. We can setup new route with our new plugin enabled.

Then you will see a status code of 200 with the response, indicating that the route has been successfully created.

In the apisix_log/error.log file there will be a record likely below in JSON format:

It can be seen that the path: logs/file.log we configured for the plugin as the conf parameter has been successfully saved. So far we have successfully created a minimal usable plugin that prints the data for the conf and ctx parameters in the log phase.

You can also try to write core functionality for the custom file-logger plugin, where the program can get the log output path from conf param, create/update the file with new logs. Please refer to Apache APISIX Plug-in Development Guide and Lua’s IO library to learn how to implement it.