This is an automated email from the ASF dual-hosted git repository.
juzhiyuan 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 7569eb993 docs: update "Other protocols" Plugins (#7312)
7569eb993 is described below
commit 7569eb99326f72f69a6e275126decce2b7e486d1
Author: Navendu Pottekkat <[email protected]>
AuthorDate: Thu Jun 30 12:00:46 2022 +0530
docs: update "Other protocols" Plugins (#7312)
---
docs/en/latest/config.json | 2 +-
docs/en/latest/plugins/dubbo-proxy.md | 85 +++++++++++++++++------------------
docs/en/latest/plugins/mqtt-proxy.md | 56 +++++++++++++----------
3 files changed, 74 insertions(+), 69 deletions(-)
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index 7fe61986b..46c6ab4e9 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -171,7 +171,7 @@
},
{
"type": "category",
- "label": "Other Protocols",
+ "label": "Other protocols",
"items": [
"plugins/dubbo-proxy",
"plugins/mqtt-proxy",
diff --git a/docs/en/latest/plugins/dubbo-proxy.md
b/docs/en/latest/plugins/dubbo-proxy.md
index fb8873595..c69dd6117 100644
--- a/docs/en/latest/plugins/dubbo-proxy.md
+++ b/docs/en/latest/plugins/dubbo-proxy.md
@@ -1,5 +1,12 @@
---
title: dubbo-proxy
+keywords:
+ - APISIX
+ - API Gateway
+ - Plugin
+ - Apache Dubbo
+ - dubbo-proxy
+description: This document contains information about the Apache APISIX
dubbo-proxy Plugin.
---
<!--
@@ -23,40 +30,39 @@ title: dubbo-proxy
## Description
-dubbo-proxy plugin allows you proxy HTTP request to
[**dubbo**](http://dubbo.apache.org).
+The `dubbo-proxy` Plugin allows you to proxy HTTP requests to [Apache
Dubbo](https://dubbo.apache.org/en/index.html).
+
+:::info IMPORTANT
-## Requirement
+If you are using OpenResty, you need to build it with Dubbo support. See [How
do I build the APISIX base
environment](./../FAQ.md#how-do-i-build-the-apisix-base-environment) for
details.
-If you are using OpenResty, you need to build it with dubbo support, see
[APISIX-Base](./FAQ/#how-do-i-build-the-apisix-base-environment).
+:::
## Runtime Attributes
-| Name | Type | Requirement | Default | Valid | Description
|
-| ------------ | ------ | ----------- | -------- | ------------ |
-------------------------------------------------------------------- |
-| service_name | string | required | | | dubbo
provider service name|
-| service_version | string | required | | | dubbo
provider service version|
-| method | string | optional | the path of uri | | dubbo
provider service method|
+| Name | Type | Required | Default | Description
|
+| --------------- | ------ | -------- | -------------------- |
------------------------------- |
+| service_name | string | True | | Dubbo provider
service name. |
+| service_version | string | True | | Dubbo provider
service version. |
+| method | string | False | The path of the URI. | Dubbo provider
service method. |
## Static Attributes
-| Name | Type | Requirement | Default | Valid | Description
|
-| ------------ | ------ | ----------- | -------- | ------------ |
-------------------------------------------------------------------- |
-| upstream_multiplex_count | number | required | 32 | >= 1 | the
maximum number of multiplex requests in an upstream connection |
+| Name | Type | Required | Default | Valid values |
Description |
+| ------------------------ | ------ | -------- | ------- | ------------ |
--------------------------------------------------------------- |
+| upstream_multiplex_count | number | True | 32 | >= 1 | Maximum
number of multiplex requests in an upstream connection. |
-## How To Enable
+## Enabling the Plugin
-First of all, enable the dubbo-proxy plugin in the `config.yaml`:
+To enable the `dubbo-proxy` Plugin, you have to add it in your configuration
file (`conf/config.yaml`):
-```
-# Add this in config.yaml
+```yaml title="conf/config.yaml"
plugins:
- - ... # plugin you need
+ - ...
- dubbo-proxy
```
-Then reload APISIX.
-
-Here's an example, enable the dubbo-proxy plugin on the specified route:
+Now, when APISIX is reloaded, you can add it to a specific Route as shown
below:
```shell
curl http://127.0.0.1:9080/apisix/admin/upstreams/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -83,44 +89,41 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f1
}'
```
-## Test Plugin
+## Example usage
-You can follow the [Quick
Start](https://github.com/alibaba/tengine/tree/master/modules/mod_dubbo#quick-start)
example in Tengine and use the configuration above to test it.
-They should provide the same result.
+You can follow the [Quick
Start](https://github.com/alibaba/tengine/tree/master/modules/mod_dubbo#quick-start)
guide in Tengine with the configuration above for testing.
-The returned data from upstream dubbo service must be a `Map<String, String>`.
+Dubbo returns data in the form `Map<String, String>`.
-If the returned data is
+If the returned data is:
```json
{
- "status": "200",
- "header1": "value1",
- "header2": "valu2",
- "body": "blahblah"
+ "status": "200",
+ "header1": "value1",
+ "header2": "value2",
+ "body": "body of the message"
}
```
-the converted HTTP response will be
+The converted HTTP response will be:
```
-HTTP/1.1 200 OK # "status" will be the status code
+HTTP/1.1 200 OK
...
header1: value1
header2: value2
...
-blahblah # "body" will be the body
+body of the message
```
## Disable Plugin
-When you want to disable the dubbo-proxy plugin on a route/service, it is very
simple,
- you can delete the corresponding json configuration in the plugin
configuration,
- no need to restart the service, it will take effect immediately:
+To disable the `dubbo-proxy` 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.
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uris": [
@@ -133,15 +136,9 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335
}'
```
-The dubbo-proxy plugin has been disabled now. It works for other plugins.
-
-If you want to disable dubbo-proxy plugin totally,
-you need to comment out in the `config.yaml`:
+To completely disable the `dubbo-proxy` Plugin, you can remove it from your
configuration file (`conf/config.yaml`):
-```yaml
+```yaml title="conf/config.yaml"
plugins:
- - ... # plugin you need
- #- dubbo-proxy
+ # - dubbo-proxy
```
-
-And then reload APISIX.
diff --git a/docs/en/latest/plugins/mqtt-proxy.md
b/docs/en/latest/plugins/mqtt-proxy.md
index ae112e543..ce49a79e0 100644
--- a/docs/en/latest/plugins/mqtt-proxy.md
+++ b/docs/en/latest/plugins/mqtt-proxy.md
@@ -1,5 +1,11 @@
---
title: mqtt-proxy
+keywords:
+ - APISIX
+ - API Gateway
+ - Plugin
+ - MQTT Proxy
+description: This document contains information about the Apache APISIX
mqtt-proxy Plugin.
---
<!--
@@ -23,28 +29,26 @@ title: mqtt-proxy
## Description
-The plugin `mqtt-proxy` only works in stream model, it help you to dynamic load
-balance by `client_id` of MQTT.
+The `mqtt-proxy` Plugin is used for dynamic load balancing with `client_id` of
MQTT. It only works in stream model.
-And this plugin both support MQTT protocol
[3.1.*](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) and
[5.0](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html).
+This Plugin supports both the protocols
[3.1.*](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) and
[5.0](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html).
## Attributes
-| Name | Type | Requirement | Default | Valid | Description
|
-| -------------- | ------- | ----------- | ------- | ----- |
--------------------------------------------------------------------------------------
|
-| protocol_name | string | required | | | Name of protocol,
should be `MQTT` in normal. |
-| protocol_level | integer | required | | | Level of
protocol, it should be `4` for MQTT `3.1.*`. it should be `5` for MQTT `5.0`. |
-| upstream | object | deprecated | | | Use separate
upstream in the route instead. |
-| upstream.host | string | required | | | the IP or host of
upstream, will forward current request to. |
-| upstream.ip | string | deprecated | | | Use "host"
instead. IP address of upstream, will forward current request to.|
-| upstream.port | number | required | | | Port of upstream,
will forward current request to. |
+| Name | Type | Required | Description
|
+|----------------|---------|------------|-----------------------------------------------------------------------------------|
+| protocol_name | string | True | Name of the protocol. Generally
`MQTT`. |
+| protocol_level | integer | True | Level of the protocol. It should be
`4` for MQTT `3.1.*` and `5` for MQTT `5.0`. |
+| upstream | object | Deprecated | Use separate Upstream in the Route
instead. |
+| upstream.host | string | True | IP or host of the upstream to
forward the current request to. |
+| upstream.ip | string | Deprecated | Use `host` instead. IP address of
the upstream to forward the current request to. |
+| upstream.port | number | True | Port of the upstream to forward the
current request to. |
-## How To Enable
+## Enabling the Plugin
-To enable this plugin, we need to enable the stream_proxy configuration in
`conf/config.yaml` first.
-For example, the following configuration represents listening on the 9100 TCP
port.
+To enable the Plugin, you need to first enable the `stream_proxy`
configuration in your configuration file (`conf/config.yaml`). The below
configuration represents listening on the `9100` TCP port:
-```yaml
+```yaml title="conf/config.yaml"
...
router:
http: 'radixtree_uri'
@@ -57,9 +61,9 @@ For example, the following configuration represents listening
on the 9100 TCP po
...
```
-Then send the MQTT request to port 9100.
+You can now send the MQTT request to port `9100`.
-Creates a stream route, and enable plugin `mqtt-proxy`.
+You can now create a stream Route and enable the `mqtt-proxy` Plugin:
```shell
curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -81,9 +85,13 @@ curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H
'X-API-KEY: edd1c9f03
}'
```
-In case Docker is used in combination with MacOS `host.docker.internal` is the
right parameter for `host`.
+:::note
-This plugin exposes a variable `mqtt_client_id`, and we can use it to load
balance via the client id. For example:
+If you are using Docker in macOS, then `host.docker.internal` is the right
parameter for the `host` attribute.
+
+:::
+
+This Plugin exposes a variable `mqtt_client_id` which can be used for load
balancing as shown below:
```shell
curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -113,12 +121,12 @@ curl http://127.0.0.1:9080/apisix/admin/stream_routes/1
-H 'X-API-KEY: edd1c9f03
}'
```
-MQTT connections with different client ID will be forwarded to different node
via the consistent hash algorithm. If the client ID is missing, we will balance
via client IP instead.
+MQTT connections with different client ID will be forwarded to different nodes
based on the consistent hash algorithm. If client ID is missing, client IP is
used instead for load balancing.
-## Delete Plugin
+## Disable Plugin
+
+To disable the `mqtt-proxy` Plugin you can remove the corresponding
configuration as shown below:
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X DELETE
+curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X DELETE
```
-
-The `mqtt-proxy` plugin has been deleted now.
