Skip to content

Commit

Permalink
docs: update consumer and upstream docs (#8223)
Browse files Browse the repository at this point in the history
  • Loading branch information
@guitu168
guitu168 authored Nov 29, 2022
1 parent 7926408 commit a71f410
Show file tree
Hide file tree
Showing 7 changed files with 467 additions and 349 deletions.
5 changes: 5 additions & 0 deletions docs/en/latest/terminology/api-gateway.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
---
title: API Gateway
keywords:
- APISIX
- API Gateway
- Gateway
description: This article mainly introduces the role of the API gateway and why it is needed.
---

<!--
Expand Down
159 changes: 93 additions & 66 deletions docs/en/latest/terminology/consumer.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
---
title: Consumer
keywords:
- Apache APISIX
- API Gateway
- APISIX Consumer
- Consumer
description: This article describes the role of the Apache APISIX Consumer object and how to use the Consumer.
---

<!--
Expand All @@ -25,6 +31,8 @@ title: Consumer

For an API gateway, it is usually possible to identify the type of the requester by using things like their request domain name and client IP address. A gateway like APISIX can then filter these requests using [Plugins](./plugin.md) and forward it to the specified [Upstream](./upstream.md).

It has the highest priority: Consumer > Route > Plugin Config > Service.

But this level of depth can be insufficient on some occasions.

![consumer-who](../../../assets/images/consumer-who.png)
Expand All @@ -37,8 +45,8 @@ The fields for defining a Consumer are defined as below.

| Field | Required | Description |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `username` | Yes | Name of the consumer |
| `plugins` | No | Plugin configuration of the **Consumer**. It has the highest priority: Consumer > Route > Service. For specific Plugin configurations, refer the [Plugins](./plugin.md) section. |
| `username` | True | Name of the consumer. |
| `plugins` | False | Plugin configuration of the **Consumer**. For specific Plugin configurations, please refer the [Plugins](./plugin.md). |

## Identifying a Consumer

Expand All @@ -54,83 +62,102 @@ Consumers are useful when you have different consumers requesting the same API a

Refer to the documentation for the [key-auth](../plugins/key-auth.md) authentication Plugin to further understand the concept of a Consumer.

:::note

For more information about the Consumer object, you can refer to the [Admin API Consumer](../admin-api.md#consumer) object resource introduction.

:::

## Example

The example below shows how you can enable a Plugin for a specific Consumer.

```shell
# Create a Consumer, specify the authentication plugin key-auth, and enable the specific plugin limit-count
$ curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"username": "jack",
"plugins": {
"key-auth": {
"key": "auth-one"
},
"limit-count": {
"count": 2,
"time_window": 60,
"rejected_code": 503,
"key": "remote_addr"
1. Create a Consumer, specify the authentication plugin `key-auth`, and enable the specific plugin `limit-count`.

```shell
curl http://127.0.0.1:9180/apisix/admin/consumers \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"username": "jack",
"plugins": {
"key-auth": {
"key": "auth-one"
},
"limit-count": {
"count": 2,
"time_window": 60,
"rejected_code": 503,
"key": "remote_addr"
}
}
}
}'

# Create a Router, set routing rules and enable plugin configuration
$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"key-auth": {}
},
"upstream": {
"nodes": {
"127.0.0.1:1980": 1
}'
```

2. Create a Router, set routing rules and enable plugin configuration.

```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"key-auth": {}
},
"upstream": {
"nodes": {
"127.0.0.1:1980": 1
},
"type": "roundrobin"
},
"type": "roundrobin"
},
"uri": "/hello"
}'
"uri": "/hello"
}'
```

# Send a test request, the first two return to normal, did not reach the speed limit threshold
$ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
...
3. Send a test request, the first two return to normal, did not reach the speed limit threshold.

$ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
...
```shell
curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
```

# The third test returns 503 and the request is restricted
$ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
HTTP/1.1 503 Service Temporarily Unavailable
...
The third test returns `503` and the request is restricted.

```
```shell
HTTP/1.1 503 Service Temporarily Unavailable
...
```

We can use the [consumer-restriction](../plugins/consumer-restriction.md) Plugin to restrict our user "Jack" from accessing the API.

```shell
# Add Jack to the blacklist
$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"key-auth": {},
"consumer-restriction": {
"blacklist": [
"jack"
]
}
},
"upstream": {
"nodes": {
"127.0.0.1:1980": 1
1. Add Jack to the blacklist.

```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"key-auth": {},
"consumer-restriction": {
"blacklist": [
"jack"
]
}
},
"type": "roundrobin"
},
"uri": "/hello"
}'
"upstream": {
"nodes": {
"127.0.0.1:1980": 1
},
"type": "roundrobin"
},
"uri": "/hello"
}'
```

2. Repeated tests, all return `403`; Jack is forbidden to access this API.

# Repeated tests, all return 403; Jack is forbidden to access this API
$ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
HTTP/1.1 403
...
```shell
curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
```

```
```shell
HTTP/1.1 403
...
```
67 changes: 42 additions & 25 deletions docs/en/latest/terminology/upstream.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
---
title: Upstream
keywords:
- Apache APISIX
- API Gateway
- APISIX Upstream
- Upstream
description: This article describes the role of the Apache APISIX Upstream object and how to use the Upstream.
---

<!--
Expand Down Expand Up @@ -35,12 +41,13 @@ An Upstream configuration can be directly bound to a Route or a Service, but the

## Configuration

In addition to the equalization algorithm selections, Upstream also supports passive health check and retry for the upstream. You can learn more about this [here](../admin-api.md#upstream).
In addition to the equalization algorithm selections, Upstream also supports passive health check and retry for the upstream. You can learn more about this [Admin API Upstream](../admin-api.md#upstream).

To create an Upstream object, you can use the Admin API as shown below:
To create an Upstream object, you can use the Admin API as shown below.

```shell
curl http://127.0.0.1:9180/apisix/admin/upstreams/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
curl http://127.0.0.1:9180/apisix/admin/upstreams/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"type": "chash",
"key": "remote_addr",
Expand All @@ -51,20 +58,22 @@ curl http://127.0.0.1:9180/apisix/admin/upstreams/1 -H 'X-API-KEY: edd1c9f034335
}'
```

After creating an Upstream object, it can be referenced by a specific Route or Service as shown below:
After creating an Upstream object, it can be referenced by a specific Route or Service as shown below.

```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"upstream_id": 1
}'
```

For convenience, you can directly bind the upstream address to a Route or Service:
For convenience, you can directly bind the upstream address to a Route or Service.

```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
Expand All @@ -86,10 +95,11 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13

## Example

The example below shows how you can configure a health check:
The example below shows how you can configure a health check.

```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
Expand Down Expand Up @@ -124,16 +134,17 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```

You can learn more about health checks [here](../tutorials/health-check.md).
You can learn more about health checks [health-check](../tutorials/health-check.md).

The examples below show configurations that use different `hash_on` types.

#### Consumer
### Consumer

Creating a Consumer object:
Creating a Consumer object.

```shell
curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
curl http://127.0.0.1:9180/apisix/admin/consumers \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"username": "jack",
"plugins": {
Expand All @@ -144,10 +155,11 @@ curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f1
}'
```

Creating a Route object and enabling the `key-auth` authentication Plugin:
Creating a Route object and enabling the `key-auth` authentication Plugin.

```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"key-auth": {}
Expand All @@ -170,12 +182,13 @@ To test the request, the `consumer_name` passed for authentication will be used
curl http://127.0.0.1:9080/server_port -H "apikey: auth-jack"
```

#### Cookie
### Cookie

Creating a Route and an upstream object:
Creating a Route and an upstream object.

```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/hash_on_cookie",
"upstream": {
Expand All @@ -190,18 +203,20 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```

The client can then send a request with a cookie:
The client can then send a request with a cookie.

```shell
curl http://127.0.0.1:9080/hash_on_cookie -H "Cookie: sid=3c183a30cffcda1408daf1c61d47b274"
curl http://127.0.0.1:9080/hash_on_cookie \
-H "Cookie: sid=3c183a30cffcda1408daf1c61d47b274"
```

#### Header
### Header

Creating a Route and an upstream object:
Creating a Route and an upstream object.

```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/hash_on_header",
"upstream": {
Expand All @@ -216,8 +231,10 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```

The client can now send requests with a header. The example below shows using the header `Content-Type`:
The client can now send requests with a header. The example below shows using the header `Content-Type`.

```shell
curl http://127.0.0.1:9080/hash_on_header -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -H "Content-Type: application/json"
curl http://127.0.0.1:9080/hash_on_header \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
-H "Content-Type: application/json"
```
Loading

0 comments on commit a71f410

Please sign in to comment.