This is an automated email from the ASF dual-hosted git repository.
traky pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new c0e07ad07 docs: improve `ip-restriction` plugin docs (#11925)
c0e07ad07 is described below
commit c0e07ad0708828c27473449d7fa7652717cefac3
Author: Traky Deng <[email protected]>
AuthorDate: Mon Mar 31 14:14:34 2025 +0800
docs: improve `ip-restriction` plugin docs (#11925)
---
docs/en/latest/plugins/ip-restriction.md | 154 ++++++++++++++----------------
docs/zh/latest/plugins/ip-restriction.md | 155 ++++++++++++++-----------------
2 files changed, 142 insertions(+), 167 deletions(-)
diff --git a/docs/en/latest/plugins/ip-restriction.md
b/docs/en/latest/plugins/ip-restriction.md
index cbeb0d93a..e332a3c6c 100644
--- a/docs/en/latest/plugins/ip-restriction.md
+++ b/docs/en/latest/plugins/ip-restriction.md
@@ -6,7 +6,7 @@ keywords:
- Plugin
- IP restriction
- ip-restriction
-description: This document contains information about the Apache APISIX
ip-restriction Plugin.
+description: The ip-restriction Plugin supports restricting access to upstream
resources by IP addresses, through either configuring a whitelist or blacklist
of IP addresses.
---
<!--
@@ -28,11 +28,13 @@ description: This document contains information about the
Apache APISIX ip-restr
#
-->
-## Description
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/ip-restriction"; />
+</head>
-The `ip-restriction` Plugin allows you to restrict access to a Service or a
Route by either whitelisting or blacklisting IP addresses.
+## Description
-Single IPs, multiple IPs or even IP ranges in CIDR notation like
`10.10.10.0/24` can be used.
+The `ip-restriction` Plugin supports restricting access to upstream resources
by IP addresses, through either configuring a whitelist or blacklist of IP
addresses. Restricting IP to resources helps prevent unauthorized access and
harden API security.
## Attributes
@@ -45,15 +47,16 @@ Single IPs, multiple IPs or even IP ranges in CIDR notation
like `10.10.10.0/24`
:::note
-Either one of `whitelist` or `blacklist` attribute must be specified. They
cannot be used together.
+At least one of the `whitelist` or `blacklist` should be configured, but they
cannot be configured at the same time.
:::
-## Enable Plugin
+## Examples
-You can enable the Plugin on a Route or a Service as shown below:
+The examples below demonstrate how you can configure the `ip-restriction`
Plugin for different scenarios.
:::note
+
You can fetch the `admin_key` from `config.yaml` and save to an environment
variable with the following command:
```bash
@@ -62,103 +65,90 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
:::
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X
PUT -d '
-{
- "uri": "/index.html",
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
- },
- "plugins": {
- "ip-restriction": {
- "whitelist": [
- "127.0.0.1",
- "113.74.26.106/24"
- ]
- }
- }
-}'
-```
+### Restrict Access by Whitelisting
-To return a custom message when an IP address is not allowed access, configure
it in the Plugin as shown below:
+The following example demonstrates how you can whitelist a list of IP
addresses that should have access to the upstream resource and customize the
error message for access denial.
-```json
-"plugins": {
- "ip-restriction": {
+Create a Route with the `ip-restriction` Plugin to whitelist a range of IPs
and customize the error message when the access is denied:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "ip-restriction-route",
+ "uri": "/anything",
+ "plugins": {
+ "ip-restriction": {
"whitelist": [
- "127.0.0.1",
- "113.74.26.106/24"
+ "192.168.0.1/24"
],
- "message": "Do you want to do something bad?"
+ "message": "Access denied"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
}
-}
+ }'
```
-## Example usage
-
-After you have configured the Plugin as shown above, when you make a request
from the IP `127.0.0.1`:
-
-```shell
-curl http://127.0.0.1:9080/index.html -i
-```
+Send a request to the Route:
```shell
-HTTP/1.1 200 OK
-...
+curl -i "http://127.0.0.1:9080/anything";
```
-But if you make requests from `127.0.0.2`:
+If your IP is allowed, you should receive an `HTTP/1.1 200 OK` response. If
not, you should receive an `HTTP/1.1 403 Forbidden` response with the following
error message:
-```shell
-curl http://127.0.0.1:9080/index.html -i --interface 127.0.0.2
+```text
+{"message":"Access denied"}
```
-```
-HTTP/1.1 403 Forbidden
-...
-{"message":"Your IP address is not allowed"}
-```
+### Restrict Access Using Modified IP
+
+The following example demonstrates how you can modify the IP used for IP
restriction, using the `real-ip` Plugin. This is particularly useful if APISIX
is behind a reverse proxy and the real client IP is not available to APISIX.
-To change the whitelisted/blacklisted IPs, you can update the Plugin
configuration. The changes are hot reloaded and there is no need to restart the
service.
+Create a Route with the `ip-restriction` Plugin to whitelist a specific IP
address and obtain client IP address from the URL parameter `realip`:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X
PUT -d '
-{
- "uri": "/index.html",
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
- },
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "ip-restriction-route",
+ "uri": "/anything",
"plugins": {
- "ip-restriction": {
- "whitelist": [
- "127.0.0.2",
- "113.74.26.106/24"
- ]
- }
+ "ip-restriction": {
+ "whitelist": [
+ "192.168.1.241"
+ ]
+ },
+ "real-ip": {
+ "source": "arg_realip"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
}
-}'
+ }'
+```
+
+Send a request to the Route:
+
+```shell
+curl -i "http://127.0.0.1:9080/anything?realip=192.168.1.241";
```
-## Delete Plugin
+You should receive an `HTTP/1.1 200 OK` response.
-To remove the `ip-restriction` Plugin, you can delete the corresponding JSON
configuration from the Plugin configuration. APISIX will automatically reload
and you do not have to restart for this to take effect.
+Send another request with a different IP address:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X
PUT -d '
-{
- "uri": "/index.html",
- "plugins": {},
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
- }
-}'
+curl -i "http://127.0.0.1:9080/anything?realip=192.168.10.24";
```
+
+You should receive an `HTTP/1.1 403 Forbidden` response.
diff --git a/docs/zh/latest/plugins/ip-restriction.md
b/docs/zh/latest/plugins/ip-restriction.md
index 95757f8a0..fccc265cc 100644
--- a/docs/zh/latest/plugins/ip-restriction.md
+++ b/docs/zh/latest/plugins/ip-restriction.md
@@ -6,7 +6,7 @@ keywords:
- Plugin
- IP restriction
- ip-restriction
-description: 本文介绍了 Apache APISIX ip-restriction 插件的基本信息及使用方法。
+description: ip-restriction 插件支持通过配置 IP 地址白名单或黑名单来限制 IP 地址对上游资源的访问。
---
<!--
@@ -28,29 +28,31 @@ description: 本文介绍了 Apache APISIX ip-restriction 插件的基本信息
#
-->
-## 描述
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/ip-restriction"; />
+</head>
-`ip-restriction` 插件可以通过将 IP 地址列入白名单或黑名单来限制对服务或路由的访问。
+## 描述
-支持对单个 IP 地址、多个 IP 地址和类似 `10.10.10.0/24` 的 CIDR（无类别域间路由）范围的限制。
+`ip-restriction` 插件支持通过配置 IP 地址白名单或黑名单来限制 IP 地址对上游资源的访问。限制 IP
对资源的访问有助于防止未经授权的访问并加强 API 安全性。
## 属性
| 参数名 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| --------- | ------------- | ------ | ------ | ------ |
-------------------------------- |
-| whitelist | array[string] | 否 | | | 加入白名单的 IP 地址或 CIDR 范围。 |
-| blacklist | array[string] | 否 | | | 加入黑名单的 IP 地址或 CIDR 范围。 |
+| whitelist | array[string] | 否 | | | 要列入白名单的 IP 列表。支持
IPv4、IPv6 和 CIDR 表示法。 |
+| blacklist | array[string] | 否 | | | 要列入黑名单的 IP 列表。支持
IPv4、IPv6 和 CIDR 表示法。 |
| message | string | 否 | "Your IP address is not allowed" | [1, 1024] |
在未允许的 IP 访问的情况下返回的信息。 |
:::note
-`whitelist` 和 `blacklist` 属性无法同时在同一个服务或路由上使用，只能使用其中之一。
+`whitelist` 或 `blacklist` 至少配置一个，但不能同时配置。
:::
-## 启用插件
+## 示例
-以下示例展示了如何在特定路由上启用 `ip-restriction` 插件，并配置 `whitelist` 属性：
+以下示例演示了如何针对不同场景配置 `ip-restriction` 插件。
:::note
@@ -62,107 +64,90 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
:::
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X
PUT -d '
-{
- "uri": "/index.html",
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
- },
- "plugins": {
- "ip-restriction": {
- "whitelist": [
- "127.0.0.1",
- "113.74.26.106/24"
- ]
- }
- }
-}'
-```
+### 通过白名单限制访问
-当使用白名单之外的 IP 访问时，默认返回 `{"message":"Your IP address is not allowed"}`。如果想使用自定义的
`message`，可以在插件配置中进行调整：
+以下示例演示了如何将有权访问上游资源的 IP 地址列表列入白名单，并自定义拒绝访问的错误消息。
-```json
-"plugins": {
- "ip-restriction": {
+使用 `ip-restriction` 插件创建路由，将一系列 IP 列入白名单，并自定义拒绝访问时的错误消息：
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "ip-restriction-route",
+ "uri": "/anything",
+ "plugins": {
+ "ip-restriction": {
"whitelist": [
- "127.0.0.1",
- "113.74.26.106/24"
+ "192.168.0.1/24"
],
- "message": "Do you want to do something bad?"
+ "message": "Access denied"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
}
-}
+ }'
```
-## 测试插件
-
-启用插件后，使用 `curl` 命令访问 APISIX 实例地址：
+向路由发送请求：
```shell
-curl http://127.0.0.1:9080/index.html -i
+curl -i "http://127.0.0.1:9080/anything";
```
-返回 `200` HTTP 状态码，代表访问成功：
+如果您的 IP 被允许，您应该会收到 `HTTP/1.1 200 OK` 响应。如果不允许，您应该会收到 `HTTP/1.1 403 Forbidden`
响应，并显示以下错误消息：
-```shell
-HTTP/1.1 200 OK
-...
+```text
+{"message":"Access denied"}
```
-再从 IP 地址 `127.0.0.2` 发出请求：
+### 使用修改后的 IP 限制访问
-```shell
-curl http://127.0.0.1:9080/index.html -i --interface 127.0.0.2
-```
+以下示例演示了如何使用 `real-ip` 插件修改用于 IP 限制的 IP。如果 APISIX 位于反向代理之后，并且 APISIX 无法获得真实客户端
IP，则此功能特别有用。
-返回 `403` HTTP 状态码，代表访问被阻止：
+使用 `ip-restriction` 插件创建路由，将特定 IP 地址列入白名单，并从 URL 参数 `realip` 获取客户端 IP 地址：
```shell
-HTTP/1.1 403 Forbidden
-...
-{"message":"Your IP address is not allowed"}
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "ip-restriction-route",
+ "uri": "/anything",
+ "plugins": {
+ "ip-restriction": {
+ "whitelist": [
+ "192.168.1.241"
+ ]
+ },
+ "real-ip": {
+ "source": "arg_realip"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
+ }
+ }'
```
-如果你需要更改白名单或黑名单的 IP 地址，你只需更新插件配置，无需重启服务：
+向路由发送请求：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X
PUT -d '
-{
- "uri": "/index.html",
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
- },
- "plugins": {
- "ip-restriction": {
- "whitelist": [
- "127.0.0.2",
- "113.74.26.106/24"
- ]
- }
- }
-}'
+curl -i "http://127.0.0.1:9080/anything?realip=192.168.1.241";
```
-## 删除插件
+您应该会收到 `HTTP/1.1 200 OK` 响应。
-当你需要禁用 `ip-restriction` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
+使用不同的 IP 地址发送另一个请求：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X
PUT -d '
-{
- "uri": "/index.html",
- "plugins": {},
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
- }
-}'
+curl -i "http://127.0.0.1:9080/anything?realip=192.168.10.24";
```
+
+您应该会收到 `HTTP/1.1 403 Forbidden` 响应。
