2019-10-31 09:27:28 +08:00
<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
-->
2019-11-24 21:15:39 +08:00
[Chinese ](README_CN.md )
2019-06-06 12:39:49 +08:00
## APISIX
2019-10-30 10:45:09 +08:00
[![Build Status ](https://travis-ci.org/apache/incubator-apisix.svg?branch=master )](https://travis-ci.org/apache/incubator-apisix)
[![License ](https://img.shields.io/badge/License-Apache%202.0-blue.svg )](https://github.com/apache/incubator-apisix/blob/master/LICENSE)
2019-05-06 10:14:39 +08:00
2019-06-06 14:40:04 +08:00
- **QQ group**: 552030619
2019-11-02 08:44:15 +08:00
- Mail list: Mail to dev-subscribe@apisix.apache.org, follow the reply to subscribe the mail list.
2019-12-12 15:40:43 +08:00
- ![Twitter Follow ](https://img.shields.io/twitter/follow/ApacheAPISIX?style=social )
2019-06-06 14:38:55 +08:00
APISIX is a cloud-native microservices API gateway, delivering the ultimate performance, security, open source and scalable platform for all your APIs and microservices.
2019-06-05 17:28:50 +08:00
2019-11-02 09:05:38 +08:00
APISIX is based on Nginx and etcd. Compared with traditional API gateways, APISIX has dynamic routing and plug-in hot loading, which is especially suitable for API management under micro-service system.
2019-06-13 12:34:43 +08:00
## Why APISIX?
2019-07-06 16:49:06 +08:00
2019-06-13 12:34:43 +08:00
If you are building a website, mobile device or IoT (Internet of Things) application, you may need to use an API gateway to handle interface traffic.
2019-12-06 14:48:50 +08:00
APISIX is a cloud-based microservices API gateway that handles traditional north-south traffic and handles east-west traffic between services, and can also be used as a k8s ingress controller.
2019-06-13 12:34:43 +08:00
2019-11-04 10:21:33 +08:00
APISIX provides dynamic load balancing, authentication, rate limiting, other plugins through plugin mechanisms, and supports plugins you develop yourself.
2019-06-13 12:34:43 +08:00
2019-06-30 22:06:01 +08:00
![](doc/images/apisix.png)
## Features
2020-01-10 13:30:21 +08:00
You can use Apache APISIX as a traffic entrance to process all business data, including dynamic routing, dynamic upstream, dynamic certificates,
A/B testing, canary release, blue-green deployment, limit rate, defense against malicious attacks, metrics, monitoring alarms, service observability, service governance, etc.
- **All platforms**
- Cloud-Native: Platform agnostic, No vendor lock-in, APISIX can run from bare-metal to Kubernetes.
- Run Environment: Both OpenResty and Tengine are supported.
2020-05-27 20:23:26 +08:00
- Supports ARM64: Don't worry about the lock-in of the infra technology.
2020-01-10 13:30:21 +08:00
- **Multi protocols**
- [TCP/UDP Proxy ](doc/stream-proxy.md ): Dynamic TCP/UDP proxy.
2020-01-10 14:03:13 +08:00
- [Dynamic MQTT Proxy ](doc/plugins/mqtt-proxy.md ): Supports to load balance MQTT by `client_id` , both support MQTT [3.1.* ](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html ), [5.0 ](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html ).
2020-02-01 11:30:41 +08:00
- [gRPC proxy ](doc/grpc-proxy.md ): Proxying gRPC traffic.
- [gRPC transcoding ](doc/plugins/grpc-transcoding.md ): Supports protocol transcoding so that clients can access your gRPC API by using HTTP/JSON.
2020-01-10 13:30:21 +08:00
- Proxy Websocket
2020-02-12 10:53:20 +08:00
- Proxy Protocol
2020-01-19 15:06:28 +08:00
- Proxy Dubbo: Dubbo Proxy based on Tengine.
2020-01-10 13:30:21 +08:00
- HTTP(S) Forward Proxy
- [SSL ](doc/https.md ): Dynamically load an SSL certificate.
- **Full dynamic**
2020-01-10 14:03:13 +08:00
- [Hot Updates And Hot Plugins ](doc/plugins.md ): Continuously updates its configurations and plugins without restarts!
2020-01-19 15:06:28 +08:00
- [Proxy Rewrite ](doc/plugins/proxy-rewrite.md ): Support rewrite the `host` , `uri` , `schema` , `enable_websocket` , `headers` of the request before send to upstream.
2020-01-10 13:30:21 +08:00
- [Response Rewrite ](doc/plugins/response-rewrite.md ): Set customized response status code, body and header to the client.
- [Serverless ](doc/plugins/serverless.md ): Invoke functions in each phase in APISIX.
- Dynamic Load Balancing: Round-robin load balancing with weight.
- Hash-based Load Balancing: Load balance with consistent hashing sessions.
2020-02-01 11:30:41 +08:00
- [Health Checks ](doc/health-check.md ): Enable health check on the upstream node, and will automatically filter unhealthy nodes during load balancing to ensure system stability.
2020-01-10 13:30:21 +08:00
- Circuit-Breaker: Intelligent tracking of unhealthy upstream services.
- **Fine-grained routing**
- [Supports full path matching and prefix matching ](doc/router-radixtree.md#how-to-use-libradixtree-in-apisix )
2020-01-10 14:03:13 +08:00
- [Support all Nginx built-in variables as conditions for routing ](/doc/router-radixtree.md#how-to-filter-route-by-nginx-builtin-variable ), so you can use `cookie` ,` args`, etc. as routing conditions to implement canary release, A/B testing, etc.
2020-01-10 13:30:21 +08:00
- Support [various operators as judgment conditions for routing ](https://github.com/iresty/lua-resty-radixtree#operator-list ), for example `{"arg_age", ">", 24}`
- Support [custom route matching function ](https://github.com/iresty/lua-resty-radixtree/blob/master/t/filter-fun.t#L10 )
- IPv6: Use IPv6 to match route.
- Support [TTL ](doc/admin-api-cn.md#route )
- [Support priority ](doc/router-radixtree.md#3-match-priority )
2020-04-29 21:40:45 +08:00
- [Support Batch Http Requests ](doc/plugins/batch-requests.md )
2020-01-10 13:30:21 +08:00
- **Security**
2020-02-14 11:08:11 +08:00
- Authentications: [key-auth ](doc/plugins/key-auth.md ), [JWT ](doc/plugins/jwt-auth.md ), [basic-auth ](doc/plugins/basic-auth.md ), [wolf-rbac ](doc/plugins/wolf-rbac.md )
2020-01-10 13:30:21 +08:00
- [IP Whitelist/Blacklist ](doc/plugins/ip-restriction.md )
2020-01-19 15:06:28 +08:00
- [IdP ](doc/plugins/oauth.md ): Support external authentication services, such as Auth0, okta, etc., users can use this to connect to OAuth 2.0 and other authentication methods.
2020-01-10 13:30:21 +08:00
- [Limit-req ](doc/plugins/limit-req.md )
- [Limit-count ](doc/plugins/limit-count.md )
- [Limit-concurrency ](doc/plugins/limit-conn.md )
- Anti-ReDoS(Regular expression Denial of Service): Built-in policies to Anti ReDoS without configuration.
2020-03-29 10:30:59 +08:00
- [CORS ](doc/plugins/cors.md )
2020-01-10 13:30:21 +08:00
- **OPS friendly**
2020-05-27 17:55:47 +08:00
- OpenTracing: support [Apache Skywalking ](doc/plugins/skywalking.md ) and [Zipkin ](doc/plugins/zipkin.md )
2020-01-10 13:30:21 +08:00
- Monitoring And Metrics: [Prometheus ](doc/plugins/prometheus.md )
2020-03-17 07:46:59 +08:00
- Clustering: APISIX nodes are stateless, creates clustering of the configuration center, please refer to [etcd Clustering Guide ](https://github.com/etcd-io/etcd/blob/master/Documentation/op-guide/clustering.md ).
2020-03-19 19:14:19 +08:00
- High availability: support to configure multiple etcd addresses in the same cluster.
2020-01-10 13:30:21 +08:00
- Dashboard: Built-in dashboard to control APISIX.
- Version Control: Supports rollbacks of operations.
- CLI: start\stop\reload APISIX through the command line.
- [Stand-alone mode ](doc/stand-alone.md ): Supports to load route rules from local yaml file, it is more friendly such as under the kubernetes(k8s).
2020-03-07 19:52:55 +08:00
- [Global Rule ](doc/architecture-design.md#Global-Rule ): Allows to run any plugin for all request, eg: limit rate, IP filter etc.
2020-01-10 14:03:13 +08:00
- High performance: The single-core QPS reaches 18k with an average delay of less than 0.2 milliseconds.
2020-01-15 17:41:26 +08:00
- [Fault Injection ](doc/plugins/fault-injection.md )
2020-04-15 22:39:11 +08:00
- [REST Admin API ](doc/admin-api.md ): Using the REST Admin API to control Apache APISIX, which only allows 127.0.0.1 access by default, you can modify the `allow_admin` field in `conf/config.yaml` to specify a list of IPs that are allowed to call the Admin API. Also note that the Admin API uses key auth to verify the identity of the caller. **The `admin_key` field in `conf/config.yaml` needs to be modified before deployment to ensure security** .
2020-04-16 19:22:44 +08:00
- External Loggers: Export access logs to external log management tools. ([HTTP Logger](doc/plugins/http-logger.md), [TCP Logger ](doc/plugins/tcp-logger.md ), [Kafka Logger ](doc/plugins/kafka-logger.md ), [UDP Logger ](doc/plugins/udp-logger.md ))
2020-01-10 13:30:21 +08:00
- **Highly scalable**
2020-02-24 13:52:29 +08:00
- [Custom plugins ](doc/plugin-develop.md ): Allows hooking of common phases, such as `rewrite` , `access` , `header filer` , `body filter` and `log` , also allows to hook the `balancer` stage.
2020-01-10 13:30:21 +08:00
- Custom load balancing algorithms: You can use custom load balancing algorithms during the `balancer` phase.
2020-01-19 15:06:28 +08:00
- Custom routing: Support users to implement routing algorithms themselves.
2019-08-19 13:59:47 +08:00
2019-10-23 15:14:55 +08:00
## Installation
2019-05-28 16:26:30 +08:00
2019-11-02 09:05:38 +08:00
APISIX Installed and tested in the following systems(OpenResty MUST >= 1.15.8.1, or Tengine >= 2.3.2):
2019-09-11 15:22:18 +08:00
2019-11-25 13:09:32 +08:00
CentOS 7, Ubuntu 16.04, Ubuntu 18.04, Debian 9, Debian 10, macOS, **ARM64** Ubuntu 18.04
2019-06-04 19:54:45 +08:00
2019-11-25 13:09:32 +08:00
Steps to install APISIX:
2020-05-27 20:23:26 +08:00
1. Installation runtime dependencies: Nginx and etcd, refer to [documentation ](doc/install-dependencies.md )
2019-11-25 13:09:32 +08:00
2. There are several ways to install Apache APISIX:
2019-11-27 21:55:56 +08:00
- [Source Release ](doc/how-to-build.md#installation-via-source-release )
2019-11-25 13:09:32 +08:00
- [RPM package ](doc/how-to-build.md#installation-via-rpm-package-centos-7 ) for CentOS 7
- [Luarocks ](doc/how-to-build.md#installation-via-luarocks-macos-not-supported )
- [Docker ](https://github.com/apache/incubator-apisix-docker )
2019-07-05 19:01:20 +08:00
2019-05-28 16:26:30 +08:00
## Quickstart
2019-06-04 17:00:37 +08:00
1. start server:
2019-07-06 16:49:06 +08:00
2019-05-28 16:26:30 +08:00
```shell
2019-06-04 17:00:37 +08:00
sudo apisix start
2019-05-28 16:26:30 +08:00
```
2020-03-18 08:47:55 +08:00
2. Try the getting started guide
2019-05-28 16:26:30 +08:00
2020-03-18 08:47:55 +08:00
The getting-started guide is a good way to learn the basics of APISIX. Follow the [getting started guide ](doc/getting-started.md ).
2019-05-28 16:26:30 +08:00
2019-10-23 15:14:55 +08:00
Then you can try more [plugins ](doc/README.md#plugins ).
2019-05-28 16:26:30 +08:00
2019-08-07 15:26:53 +08:00
## Dashboard
2020-01-21 17:58:24 +08:00
APISIX has built-in support for Dashboard, as follows:
2019-11-26 21:24:45 +08:00
2020-04-22 09:48:53 +08:00
1. Please make sure your machine has the latest Node.js(10 or higher), or there will occur build issues.
2020-01-21 17:58:24 +08:00
2020-04-26 11:05:22 +08:00
2. Download the source codes of dashboard submodule:
2019-11-26 21:24:45 +08:00
```
2020-04-26 11:05:22 +08:00
git submodule update --init --recursive
2019-11-26 21:24:45 +08:00
```
2020-01-21 17:58:24 +08:00
3. Install [yarn ](https://yarnpkg.com/en/docs/install )
4. Install dependencies then run build command:
2019-11-26 21:24:45 +08:00
```
2020-04-26 11:05:22 +08:00
cd dashboard
2020-01-21 17:58:24 +08:00
yarn & & yarn build:prod
2019-11-26 21:24:45 +08:00
```
2019-08-07 15:26:53 +08:00
2020-01-21 17:58:24 +08:00
5. Integration with APISIX
2019-12-19 19:09:08 +08:00
Copy the compiled files under `/dist` directory to the `apisix/dashboard` directory,
2020-04-26 11:05:22 +08:00
```
cp -r dist/* .
```
2019-12-19 19:09:08 +08:00
open `http://127.0.0.1:9080/apisix/dashboard/` in the browser.
2019-08-07 15:26:53 +08:00
Do not need to fill the user name and password, log in directly.
2020-04-15 22:39:11 +08:00
The dashboard only allows 127.0.0.1 by default, and you can modify `allow_admin` in `conf/config.yaml` by yourself, to list the list of IPs allowed to access.
2019-06-30 22:06:01 +08:00
2019-05-31 16:37:26 +08:00
## Benchmark
2019-07-06 16:49:06 +08:00
2019-11-25 13:09:32 +08:00
Using AWS's 8 core server, APISIX's QPS reach to 140,000 with a latency of only 0.2 ms.
2019-06-06 14:40:04 +08:00
2019-11-25 13:09:32 +08:00
## Document
2020-01-14 11:34:01 +08:00
[Document Indexing for Apache APISIX ](doc/README.md )
2019-07-18 07:48:41 +08:00
2020-01-10 13:30:21 +08:00
## Apache APISIX vs Kong
2020-01-14 11:34:01 +08:00
#### Both of them have been covered core features of API gateway
2020-01-10 14:03:13 +08:00
2020-01-14 11:34:01 +08:00
| **Features** | **Apache APISIX** | **KONG** |
|:----|:----|:----|
| **Dynamic upstream** | Yes | Yes |
| **Dynamic router** | Yes | Yes |
| **Health check** | Yes | Yes |
| **Dynamic SSL** | Yes | Yes |
| **L4 and L7 proxy** | Yes | Yes |
| **Opentracing** | Yes | Yes |
| **Custom plugin** | Yes | Yes |
| **REST API** | Yes | Yes |
| **CLI** | Yes | Yes |
2020-01-10 13:30:21 +08:00
#### The advantages of Apache APISIX
2020-01-15 11:57:11 +08:00
2020-01-10 13:30:21 +08:00
| **Features** | **Apache APISIX** | **Kong** |
|:----|:----|:----|
2020-01-15 11:57:11 +08:00
| Belongs to | Apache Software Foundation | Kong Inc. |
2020-01-10 13:30:21 +08:00
| Tech Architecture | Nginx + etcd | Nginx + postgres |
2020-01-14 11:34:01 +08:00
| Communication channels | Mail list, Wechat group, QQ group, Github, meetup | Github, freenode, forum |
2020-01-10 13:30:21 +08:00
| Single-core CPU, QPS(enable limit-count and prometheus plugins) | 18000 | 1700 |
2020-01-15 11:57:11 +08:00
| Latency | 0.2 ms | 2 ms |
2020-01-10 13:30:21 +08:00
| Dubbo | Yes | No |
| Configuration rollback | Yes | No |
2020-01-15 11:57:11 +08:00
| Route with TTL | Yes | No |
| Plug-in hot loading | Yes | No |
| Custom LB and route | Yes | No |
| REST API < -- > gRPC transcoding | Yes | No |
2020-01-10 13:30:21 +08:00
| Tengine | Yes | No |
| MQTT | Yes | No |
2020-01-14 11:34:01 +08:00
| Configuration effective time | Event driven, < 1ms | polling , 5 seconds |
2020-01-15 11:57:11 +08:00
| Dashboard | Yes | No |
2020-01-10 13:30:21 +08:00
| IdP | Yes | No |
| Configuration Center HA | Yes | No |
| Speed limit for a specified time window | Yes | No |
2020-01-14 11:34:01 +08:00
| Support any Nginx variable as routing condition | Yes | No |
2019-07-31 22:42:17 +08:00
2020-01-10 13:30:21 +08:00
## Videos And Articles
2020-02-01 11:30:41 +08:00
- [APISIX technology selection, testing and continuous integration ](https://medium.com/@ming_wen/apache-apisixs-technology-selection-testing-and-continuous-integration-313221b02542 )
- [Analysis of Excellent Performance of Apache APISIX Microservices Gateway ](https://medium.com/@ming_wen/analysis-of-excellent-performance-of-apache-apisix-microservices-gateway-fc77db4090b5 )
2019-07-31 22:42:17 +08:00
2020-01-10 13:30:21 +08:00
## User Stories
2020-01-10 14:03:13 +08:00
- [ke.com: How to Build a Gateway Based on Apache APISIX(Chinese) ](https://mp.weixin.qq.com/s/yZl9MWPyF1-gOyCp8plflA )
- [360: Apache APISIX Practice in OPS Platform(Chinese) ](https://mp.weixin.qq.com/s/zHF_vlMaPOSoiNvqw60tVw )
- [HelloTalk: Exploring Globalization Based on OpenResty and Apache APISIX(Chinese) ](https://www.upyun.com/opentalk/447.html )
- [Tencent Cloud: Why choose Apache APISIX to implement the k8s ingress controller?(Chinese) ](https://www.upyun.com/opentalk/448.html )
- [aispeech: Why we create a new k8s ingress controller?(Chinese) ](https://mp.weixin.qq.com/s/bmm2ibk2V7-XYneLo9XAPQ )
2020-01-10 13:30:21 +08:00
2019-09-18 15:08:52 +08:00
## Who Uses APISIX?
2019-11-25 13:09:32 +08:00
A wide variety of companies and organizations use APISIX for research, production and commercial product, including:
2019-11-26 21:24:45 +08:00
2020-04-08 22:59:30 +08:00
< img src = "https://raw.githubusercontent.com/api7/website-of-API7/master/user-wall.jpg" width = "900" height = "500" >
2019-09-18 15:08:52 +08:00
Users are encouraged to add themselves to the [Powered By ](doc/powered-by.md ) page.
2019-07-18 16:09:30 +08:00
## Landscape
2019-11-25 13:09:32 +08:00
< p align = "left" >
< img src = "https://landscape.cncf.io/images/left-logo.svg" width = "150" > < img src = "https://landscape.cncf.io/images/right-logo.svg" width = "200" >
< br / > < br / >
APISIX enriches the < a href = "https://landscape.cncf.io/category=api-gateway&format=card-mode&grouping=category" >
CNCF API Gateway Landscape.< / a >
< / p >
2019-08-07 13:12:40 +08:00
2019-06-06 14:38:55 +08:00
## Contributing
2019-07-06 16:49:06 +08:00
2019-09-09 11:01:24 +08:00
See [CONTRIBUTING ](Contributing.md ) for details on submitting patches and the contribution workflow.
2019-06-04 15:20:41 +08:00
2019-06-06 14:38:55 +08:00
## Acknowledgments
2019-07-06 16:49:06 +08:00
2020-01-19 15:06:28 +08:00
Inspired by Kong and Orange.