diff --git a/.licenserc.yaml b/.licenserc.yaml index ea5863015302..315fa71bcf42 100644 --- a/.licenserc.yaml +++ b/.licenserc.yaml @@ -47,5 +47,6 @@ header: - 't/plugin/authz-casbin' - 't/coredns' - 'autodocs/' + - 'docs/**/*.md' comment: on-failure diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json index 0d0302dcc393..d9804a15770a 100644 --- a/docs/en/latest/config.json +++ b/docs/en/latest/config.json @@ -2,8 +2,15 @@ "version": "3.2.0", "sidebar": [ { - "type": "doc", - "id": "getting-started" + "type": "category", + "label": "Getting Started", + "items": [ + "getting-started/README", + "getting-started/configure-routes", + "getting-started/load-balancing", + "getting-started/key-authentication", + "getting-started/rate-limiting" + ] }, { "type": "doc", diff --git a/docs/en/latest/getting-started/README.md b/docs/en/latest/getting-started/README.md new file mode 100644 index 000000000000..40e832cce8e6 --- /dev/null +++ b/docs/en/latest/getting-started/README.md @@ -0,0 +1,71 @@ +--- +title: Get APISIX +description: This tutorial uses a script to quickly install Apache APISIX in your local environment and verify it through the Admin API. +--- + + + + + +> The Getting Started tutorials are contributed by [API7.ai](https://api7.ai/). + +Apache APISIX is a dynamic, real-time, and high-performance API Gateway. It is a [top-level project](https://projects.apache.org/project.html?apisix) of the Apache Software Foundation. + +You can use APISIX API Gateway as a traffic entrance to process all business data. It offers features 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, and more. + +This tutorial uses a script to quickly install [Apache APISIX](https://api7.ai/apisix) in your local environment and verifies the installation through the Admin API. + +## Prerequisite(s) + +The quickstart script relies on several components: + +* [Docker](https://docs.docker.com/get-docker/) is used to install the containerized **etcd** and **APISIX**. +* [curl](https://curl.se/) is used to send requests to APISIX for validation. + +## Get APISIX + +:::caution + +To provide a better experience in this tutorial, the authorization of Admin API is switched off by default. Please turn on the authorization of Admin API in the production environment. + +::: +APISIX can be easily installed and started with the quickstart script: + +```shell +curl -sL https://run.api7.ai/apisix/quickstart | sh +``` + +The script should start two Docker containers, _apisix-quickstart_ and _etcd_. APISIX uses etcd to save and synchronize configurations. Both the etcd and the APISIX use [**host**](https://docs.docker.com/network/host/) Docker network mode. That is, the APISIX can be accessed from local. + +You will see the following message once APISIX is ready: + +```text +✔ APISIX is ready! +``` + + +## Validate + +Once APISIX is running, you can use curl to interact with it. Send a simple HTTP request to validate if APISIX is working properly: + +```shell +curl "http://127.0.0.1:9080" --head | grep Server +``` + +If everything is ok, you will get the following response: + +```text +Server: APISIX/3.1.0 +``` + +You now have APISIX installed and running successfully!​ + +## Next Steps + +The following tutorial is based on the working APISIX, please keep everything running and move on to the next step. + +* [Configure Routes](configure-routes.md) +* [Load Balancing](load-balancing.md) +* [Rate Limiting](rate-limiting.md) +* [Key Authentication](key-authentication.md) + diff --git a/docs/en/latest/getting-started/configure-routes.md b/docs/en/latest/getting-started/configure-routes.md new file mode 100644 index 000000000000..bc2b53c9f289 --- /dev/null +++ b/docs/en/latest/getting-started/configure-routes.md @@ -0,0 +1,73 @@ +--- +title: Configure Routes +slug: /getting-started/configure-routes +--- + + + + + +> The Getting Started tutorials are contributed by [API7.ai](https://api7.ai/). + +Apache APISIX provides flexible gateway management capabilities based on _routes_, where routing paths and targets are defined for requests. + +This tutorial guides you on how to create a route and validate it. You will complete the following steps: + +1. Create a route with a sample _upstream_ that points to [httpbin.org](http://httpbin.org). +2. Use _cURL_ to send a test request to see how APISIX proxies and forwards the request. + +## What is a Route + +A route is a routing path to upstream targets. In [Apache APISIX](https://api7.ai/apisix), routes are responsible for matching client's requests based on defined rules, loading and executing the corresponding plugins, as well as forwarding requests to the specified upstream services. + +In APISIX, a simple route can be set up with a path-matching URI and a corresponding upstream address. + +## What is an Upstream + +An upstream is a set of target nodes with the same work. It defines a virtual host abstraction that performs load balancing on a given set of service nodes according to the configured rules. + +## Prerequisite(s) + +1. Complete [Get APISIX](./) to install APISIX. + +## Create a Route + +In this section, you will create a route that forwards client requests to [httpbin.org](http://httpbin.org), a public HTTP request and response service. + +The following command creates a route, which should forward all requests sent to `http://127.0.0.1:9080/ip` to [httpbin.org/ip](http://httpbin.org/ip): + +[//]: + +```shell +curl -i "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d ' +{ + "id": "getting-started-ip", + "uri": "/ip", + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } +}' +``` + +You will receive an `HTTP/1.1 201 OK` response if the route was created successfully. + +## Validate + +```shell +curl "http://127.0.0.1:9080/ip" +``` + +The expected response is similar to the following: + +```text +{ + "origin": "183.94.122.205" +} +``` + +## What's Next + +This tutorial creates a route with only one target node. In the next tutorial, you will learn how to configure load balancing with multiple target nodes. diff --git a/docs/en/latest/getting-started/key-authentication.md b/docs/en/latest/getting-started/key-authentication.md new file mode 100644 index 000000000000..7dfe40b13139 --- /dev/null +++ b/docs/en/latest/getting-started/key-authentication.md @@ -0,0 +1,182 @@ +--- +title: Key Authentication +slug: /getting-started/key-authentication +--- + + + + + +> The Getting Started tutorials are contributed by [API7.ai](https://api7.ai/). + +An API gateway's primary role is to connect API consumers and providers. For security reasons, it should authenticate and authorize consumers before access to internal resources. + +![Key Authentication](https://static.apiseven.com/uploads/2023/02/08/8mRaK3v1_consumer.png) + +APISIX has a flexible plugin extension system and a number of existing plugins for user authentication and authorization. For example: + +- [Key Authentication](https://apisix.apache.org/docs/apisix/plugins/key-auth/) +- [Basic Authentication](https://apisix.apache.org/docs/apisix/plugins/basic-auth/) +- [JSON Web Token (JWT) Authentication](https://apisix.apache.org/docs/apisix/plugins/jwt-auth/) +- [Keycloak](https://apisix.apache.org/docs/apisix/plugins/authz-keycloak/) +- [Casdoor](https://apisix.apache.org/docs/apisix/plugins/authz-casdoor/) +- [Wolf RBAC](https://apisix.apache.org/docs/apisix/plugins/wolf-rbac/) +- [OpenID Connect](https://apisix.apache.org/docs/apisix/plugins/openid-connect/) +- [Central Authentication Service (CAS)](https://apisix.apache.org/docs/apisix/plugins/cas-auth/) +- [HMAC](https://apisix.apache.org/docs/apisix/plugins/hmac-auth/) +- [Casbin](https://apisix.apache.org/docs/apisix/plugins/authz-casbin/) +- [LDAP](https://apisix.apache.org/docs/apisix/plugins/ldap-auth/) +- [Open Policy Agent (OPA)](https://apisix.apache.org/docs/apisix/plugins/opa/) +- [Forward Authentication](https://apisix.apache.org/docs/apisix/plugins/forward-auth/) + +In this tutorial, you will create a _consumer_ with _key authentication_, and learn how to enable and disable key authentication. + +## What is a Consumer + +A Consumer is an application or a developer who consumes the API. + +In APISIX, a Consumer requires a unique _username_ and an authentication _plugin_ from the list above to be created. + +## What is Key Authentication + +Key authentication is a relatively simple but widely used authentication approach. The idea is as follows: +1. Administrator adds an authentication key (API key) to the Route. +2. API consumers add the key to the query string or headers for authentication when sending requests. + +## Enable Key Authentication + +### Prerequisite(s) + +1. Complete [Get APISIX](./) to install APISIX. +2. Complete [Configure Routes](./configure-routes#whats-a-route). + +### Create a Consumer + +Let's create a consumer named `tom` and enable the `key-auth` plugin with an API key `secret-key`. All requests sent with the key `secret-key` should be authenticated as `tom`. + +:::caution + +Please use a complex key in the Production environment. + +::: + +```shell +curl -i "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT -d ' +{ + "username": "tom", + "plugins": { + "key-auth": { + "key": "secret-key" + } + } +}' +``` + +You will receive an `HTTP/1.1 201 OK` response if the consumer was created successfully. + +### Enable Authentication + +Inheriting the route `getting-started-ip` from [Configure Routes](./configure-routes), we only need to use the `PATCH` method to add the `key-auth` plugin to the route: + +```shell +curl -i "http://127.0.0.1:9180/apisix/admin/routes/getting-started-ip" -X PATCH -d ' +{ + "plugins": { + "key-auth": {} + } +}' +``` + +You will receive an `HTTP/1.1 201 Created` response if the plugin was added successfully. + +### Validate + +Let's validate the authentication in the following scenarios: + +#### 1. Send a request without any key + +Send a request without the `apikey` header. + +```shell +curl -i "http://127.0.0.1:9080/ip" +``` + +Since you enabled the key authentication, you will receive an unauthorized response with `HTTP/1.1 401 Unauthorized`. + +```text +HTTP/1.1 401 Unauthorized +Date: Wed, 08 Feb 2023 09:38:36 GMT +Content-Type: text/plain; charset=utf-8 +Transfer-Encoding: chunked +Connection: keep-alive +Server: APISIX/3.1.0 +``` + +#### 2. Send a request with a wrong key + +Send a request with a wrong key (e.g. `wrong-key`) in the `apikey` header. + +```shell +curl -i "http://127.0.0.1:9080/ip" -H 'apikey: wrong-key' +``` + +Since the key is incorrect, you will receive an unauthorized response with `HTTP/1.1 401 Unauthorized`. + +```text +HTTP/1.1 401 Unauthorized +Date: Wed, 08 Feb 2023 09:38:27 GMT +Content-Type: text/plain; charset=utf-8 +Transfer-Encoding: chunked +Connection: keep-alive +Server: APISIX/3.1.0 +``` + +#### 3. Send a request with the correct key + +Send a request with the correct key (`secret-key`) in the `apikey` header. + +```shell +curl -i "http://127.0.0.1:9080/ip" -H 'apikey: secret-key' +``` + +You will receive an `HTTP/1.1 200 OK` response. + +```text +HTTP/1.1 200 OK +Content-Type: application/json +Content-Length: 44 +Connection: keep-alive +Date: Thu, 09 Feb 2023 03:27:57 GMT +Access-Control-Allow-Origin: * +Access-Control-Allow-Credentials: true +Server: APISIX/3.1.0 +``` + +### Disable Authentication + +Disable the key authentication plugin by setting the `_meta.disable` parameter to `true`. + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes/getting-started-ip" -X PATCH -d ' +{ + "plugins": { + "key-auth": { + "_meta": { + "disable": true + } + } + } +}' +``` + +You can send a request without any key to validate: + +```shell +curl -i "http://127.0.0.1:9080/ip" +``` + +Because you have disabled the key authentication plugin, you will receive an `HTTP/1.1 200 OK` response. + +## What's Next + +You have learned how to configure key authentication for a route. In the next tutorial, you will learn how to configure rate limiting. diff --git a/docs/en/latest/getting-started/load-balancing.md b/docs/en/latest/getting-started/load-balancing.md new file mode 100644 index 000000000000..5ab95ff5af12 --- /dev/null +++ b/docs/en/latest/getting-started/load-balancing.md @@ -0,0 +1,97 @@ +--- +title: Load Balancing +slug: /getting-started/load-balancing +--- + + + + + +> The Getting Started tutorials are contributed by [API7.ai](https://api7.ai/). + +Load balancing manages traffic between clients and servers. It is a mechanism used to decide which server handles a specific request, allowing for improved performance, scalability, and reliability. Load balancing is a key consideration in designing systems that need to handle a large volume of traffic. + +Apache APISIX supports weighted round-robin load balancing, in which incoming traffic are distributed across a set of servers in a cyclical pattern, with each server taking a turn in a predefined order. + +In this tutorial, you will create a route with two upstream services and enable round-robin load balancing to distribute traffic between the two services. + +## Prerequisite(s) + +1. Complete [Get APISIX](./) to install APISIX. +2. Understand APISIX [Route and Upstream](./configure-routes#whats-a-route). + +## Enable Load Balancing + +Let's create a route with two upstream services. All requests sent to the `/headers` endpoint will be forwarded to [httpbin.org](https://httpbin.org/headers) and [mock.api7.ai](https://mock.api7.ai/headers), which should echo back the requester's headers. + +```shell +curl -i "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d ' +{ + "id": "getting-started-headers", + "uri": "/headers", + "upstream" : { + "type": "roundrobin", + "nodes": { + "httpbin.org:443": 1, + "mock.api7.ai:443": 1 + }, + "pass_host": "node", + "scheme": "https" + } +}' +``` + +You will receive an `HTTP/1.1 201 OK` response if the route was created successfully. + +:::info +1. The `pass_host` field is set to `node` to pass the host header to the upstream. +2. The `scheme` field is set to `https` to enable TLS when sending requests to the upstream. +::: + +## Validate + +The two services respond with different data. + +From `httpbin.org`: + +```json +{ + "headers": { + "Accept": "*/*", + "Host": "httpbin.org", + "User-Agent": "curl/7.58.0", + "X-Amzn-Trace-Id": "Root=1-63e34b15-19f666602f22591b525e1e80", + "X-Forwarded-Host": "localhost" + } +} +``` + +From `mock.api7.ai`: + +```json +{ + "headers": { + "accept": "*/*", + "host": "mock.api7.ai", + "user-agent": "curl/7.58.0", + "content-type": "application/json", + "x-application-owner": "API7.ai" + } +} +``` + +Let's generate 100 requests to test the load-balancing effect: + +```shell +hc=$(seq 100 | xargs -i curl "http://127.0.0.1:9080/headers" -sL | grep "httpbin" | wc -l); echo httpbin.org: $hc, mock.api7.ai: $((100 - $hc)) +``` + +The result shows the requests were distributed over the two services almost equally: + +```text +httpbin.org: 51, mock.api7.ai: 49 +``` + +## What's Next + +You have learned how to configure load balancing. In the next tutorial, you will learn how to configure key authentication. diff --git a/docs/en/latest/getting-started/rate-limiting.md b/docs/en/latest/getting-started/rate-limiting.md new file mode 100644 index 000000000000..80547f41cfe8 --- /dev/null +++ b/docs/en/latest/getting-started/rate-limiting.md @@ -0,0 +1,104 @@ +--- +title: Rate Limiting +slug: /getting-started/rate-limiting +--- + + + + + +> The Getting Started tutorials are contributed by [API7.ai](https://api7.ai/). + +APISIX is a unified control point, managing the ingress and egress of APIs and microservices traffic. In addition to the legitimate client requests, these requests may also include unwanted traffic generated by web crawlers as well as cyber attacks, such as DDoS. + +APISIX offers rate limiting capabilities to protect APIs and microservices by limiting the number of requests sent to upstream services in a given period of time. The count of requests is done efficiently in memory with low latency and high performance. + +
+
+Routes Diagram +
+
+ +In this tutorial, you will enable the `limit-count` plugin to set a rate limiting constraint on the incoming traffic. + +## Prerequisite(s) + +1. Complete the [Get APISIX](./) step to install APISIX first. +2. Complete the [Configure Routes](./configure-routes#whats-a-route) step. + +## Enable Rate Limiting + +The following route `getting-started-ip` is inherited from [Configure Routes](./configure-routes). You only need to use the `PATCH` method to add the `limit-count` plugin to the route: + +```shell +curl -i "http://127.0.0.1:9180/apisix/admin/routes/getting-started-ip" -X PATCH -d ' +{ + "plugins": { + "limit-count": { + "count": 2, + "time_window": 10, + "rejected_code": 503 + } + } +}' +``` + +You will receive an `HTTP/1.1 201 OK` response if the plugin was added successfully. The above configuration limits the incoming requests to a maximum of 2 requests within 10 seconds. + +### Validate + +Let's generate 100 simultaneous requests to see the rate limiting plugin in effect. + +```shell +count=$(seq 100 | xargs -i curl "http://127.0.0.1:9080/ip" -I -sL | grep "503" | wc -l); echo \"200\": $((100 - $count)), \"503\": $count +``` + +The results are as expected: out of the 100 requests, 2 requests were sent successfully (status code `200`) while the others were rejected (status code `503`). + +```text +"200": 2, "503": 98 +``` + +## Disable Rate Limiting + +Disable rate limiting by setting the `_meta.disable` parameter to `true`: + +```shell +curl -i "http://127.0.0.1:9180/apisix/admin/routes/getting-started-ip" -X PATCH -d ' +{ + "plugins": { + "limit-count": { + "_meta": { + "disable": true + } + } + } +}' +``` + +### Validate + +Let's generate 100 requests again to validate if it is disabled: + +```shell +count=$(seq 100 | xargs -i curl "http://127.0.0.1:9080/ip" -I -sL | grep "503" | wc -l); echo \"200\": $((100 - $count)), \"503\": $count +``` + +The results below show that all of the requests were sent successfully: + +```text +"200": 100, "503": 0 +``` + +## More + +[//]: +[//]: +[//]: +You can use the APISIX variables to configure fined matching rules of rate limiting, such as `$host` and `$uri`. In addition, APISIX also supports rate limiting at the cluster level using Redis. + +## What's Next + +Congratulations! You have learned how to configure rate limiting and completed the Getting Started tutorials. + +You can continue to explore other documentations to customize APISIX and meet your production needs.