This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch docs/apisix-getting-started
in repository https://gitbox.apache.org/repos/asf/apisix.git
commit 8893f774e7ea52c85172bce8e6177b07f8f4afe7
Author: 琚致远 <juzhiy...@apache.org>
AuthorDate: Fri Mar 10 11:07:05 2023 +0800
docs: contribute Getting Started tutorials
---
docs/en/latest/config.json | 11 +-
docs/en/latest/getting-started/README.md | 72 ++++++++
docs/en/latest/getting-started/configure-routes.md | 73 +++++++++
.../latest/getting-started/key-authentication.md | 182 +++++++++++++++++++++
docs/en/latest/getting-started/load-balancing.md | 97 +++++++++++
docs/en/latest/getting-started/rate-limiting.md | 104 ++++++++++++
6 files changed, 537 insertions(+), 2 deletions(-)
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index 0d0302dcc..d9804a157 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 000000000..4c38eec67
--- /dev/null
+++ b/docs/en/latest/getting-started/README.md
@@ -0,0 +1,72 @@
+---
+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.
+---
+
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/apisix/getting-started/"; />
+</head>
+
+> The Getting Started tutorials are contributed by [API7.ai](https://api7.ai/)
and are licensed under the Apache 2.0 license.
+
+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 000000000..8c3eea945
--- /dev/null
+++ b/docs/en/latest/getting-started/configure-routes.md
@@ -0,0 +1,73 @@
+---
+title: Configure Routes
+slug: /getting-started/configure-routes
+---
+
+<head>
+ <link rel="canonical"
href="https://docs.api7.ai/apisix/getting-started/configure-routes"; />
+</head>
+
+> The Getting Started tutorials are contributed by [API7.ai](https://api7.ai/)
and are licensed under the Apache 2.0 license.
+
+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):
+
+[//]: <TODO: Add the link to the authorization of Admin API>
+
+```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 000000000..6e3fea7ba
--- /dev/null
+++ b/docs/en/latest/getting-started/key-authentication.md
@@ -0,0 +1,182 @@
+---
+title: Key Authentication
+slug: /getting-started/key-authentication
+---
+
+<head>
+ <link rel="canonical"
href="https://docs.api7.ai/apisix/getting-started/key-authentication"; />
+</head>
+
+> The Getting Started tutorials are contributed by [API7.ai](https://api7.ai/)
and are licensed under the Apache 2.0 license.
+
+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.
+
+
+
+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 000000000..66939bafa
--- /dev/null
+++ b/docs/en/latest/getting-started/load-balancing.md
@@ -0,0 +1,97 @@
+---
+title: Load Balancing
+slug: /getting-started/load-balancing
+---
+
+<head>
+ <link rel="canonical"
href="https://docs.api7.ai/apisix/getting-started/load-balancing"; />
+</head>
+
+> The Getting Started tutorials are contributed by [API7.ai](https://api7.ai/)
and are licensed under the Apache 2.0 license.
+
+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 000000000..b3ac9e545
--- /dev/null
+++ b/docs/en/latest/getting-started/rate-limiting.md
@@ -0,0 +1,104 @@
+---
+title: Rate Limiting
+slug: /getting-started/rate-limiting
+---
+
+<head>
+ <link rel="canonical"
href="https://docs.api7.ai/apisix/getting-started/rate-limiting"; />
+</head>
+
+> The Getting Started tutorials are contributed by [API7.ai](https://api7.ai/)
and are licensed under the Apache 2.0 license.
+
+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.
+
+<br />
+<div style={{textAlign: 'center'}}>
+<img
src="https://static.apiseven.com/uploads/2023/02/20/l9G9Kq41_rate-limiting.png";
alt="Routes Diagram" />
+</div>
+<br />
+
+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
+
+[//]: <TODO: Add the link to matching rules configuration>
+[//]: <TODO: Add the link to cluster-level rate limiting>
+[//]: <TODO: Add the link to APISIX variables>
+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.
![https://static.apiseven.com/uploads/2023/02/20/l9G9Kq41_rate-limiting.png"](https://static.apiseven.com/uploads/2023/02/20/l9G9Kq41_rate-limiting.png"){kind=link}