Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update consumer and upstream docs #8223

Merged
merged 9 commits into from
Nov 29, 2022
Merged

docs: update consumer and upstream docs #8223

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
4aa4123
docs: update consumer and upstream docs
Nov 1, 2022
87fc571
fix typo
Nov 1, 2022
5890086
fix typo
Nov 1, 2022
86b11df
fix typo
Nov 1, 2022
4dc4f9e
fix typo
Nov 1, 2022
036fe58
fix comment
Nov 1, 2022
9c3071e
fix comment
Nov 1, 2022
48f45ee
fix typo
Nov 4, 2022
3a495d1
docs: fix conflict
Nov 29, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/en/latest/terminology/api-gateway.md
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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