docs: contribute Getting Started tutorials (#9046)

Co-authored-by: Qi Guo <979918879@qq.com>
apache · Mar 13, 2023 · 27535e9 · 27535e9
1 parent 2d94db1
commit 27535e9
Show file tree

Hide file tree

Showing 7 changed files with 537 additions and 2 deletions.
diff --git 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
@@ -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
@@ -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.
+---
+
+<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/).
+
+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
@@ -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/).
+
+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
@@ -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/).
+
+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.