kayx23 commented on code in PR #11849: URL: https://github.com/apache/apisix/pull/11849#discussion_r2000613251
########## docs/en/latest/plugins/proxy-rewrite.md: ########## @@ -65,68 +64,446 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### Rewrite Host Header + +The following example demonstrates how you can modify the `Host` header in a request. Note that you should not use `headers.set` to set the `Host` header. + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", + "methods": ["GET"], + "uri": "/headers", + "plugins": { + "proxy-rewrite": { + "host": "myapisix.demo" + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` + +Send a request to `/headers` to check all the request headers sent to upstream: + ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' +curl "http://127.0.0.1:9080/headers"; +``` + +You should see a response similar to the following: + +```text { + "headers": { + "Accept": "*/*", + "Host": "myapisix.demo", + "User-Agent": "curl/8.2.1", + "X-Amzn-Trace-Id": "Root=1-64fef198-29da0970383150175bd2d76d", + "X-Forwarded-Host": "127.0.0.1" + } +} +``` + +### Rewrite URI And Set Headers + +The following example demonstrates how you can rewrite the request Upstream URI and set additional header values. If the same headers present in the client request, the corresponding header values set in the Plugin will overwrite the values present in the client request. + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", "methods": ["GET"], - "uri": "/test/index.html", + "uri": "/", "plugins": { - "proxy-rewrite": { - "uri": "/test/home.html", - "host": "iresty.com", - "headers": { - "set": { - "X-Api-Version": "v1", - "X-Api-Engine": "apisix", - "X-Api-useless": "" - }, - "add": { - "X-Request-ID": "112233" - }, - "remove":[ - "X-test" - ] - } + "proxy-rewrite": { + "uri": "/anything", + "headers": { + "set": { + "X-Api-Version": "v1", + "X-Api-Engine": "apisix" + } } + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:80": 1 + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` + +Send a request to verify: + +```shell +curl "http://127.0.0.1:9080/"; -H '"X-Api-Version": "v2"' +``` + +You should see a response similar to the following: + +```text +{ + "args": {}, + "data": "", + "files": {}, + "form": {}, + "headers": { + "Accept": "*/*", + "Host": "httpbin.org", + "User-Agent": "curl/8.2.1", + "X-Amzn-Trace-Id": "Root=1-64fed73a-59cd3bd640d76ab16c97f1f1", + "X-Api-Engine": "apisix", + "X-Api-Version": "v1", + "X-Forwarded-Host": "127.0.0.1" + }, + "json": null, + "method": "GET", + "origin": "::1, 103.248.35.179", + "url": "http://localhost/anything"; +} +``` + +Note that both headers present and the header value of `X-Api-Version` configured in the Plugin overwrites the header value passed in the request. + +### Rewrite URI And Append Headers + +The following example demonstrates how you can rewrite the request Upstream URI and append additional header values. If the same headers present in the client request, their headers values will append to the configured header values in the plugin. + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", + "methods": ["GET"], + "uri": "/", + "plugins": { + "proxy-rewrite": { + "uri": "/headers", + "headers": { + "add": { + "X-Api-Version": "v1", + "X-Api-Engine": "apisix" + } + } + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` + +Send a request to verify: + +```shell +curl "http://127.0.0.1:9080/"; -H '"X-Api-Version": "v2"' +``` + +You should see a response similar to the following: + +```text +{ + "headers": { + "Accept": "*/*", + "Host": "httpbin.org", + "User-Agent": "curl/8.2.1", + "X-Amzn-Trace-Id": "Root=1-64fed73a-59cd3bd640d76ab16c97f1f1", + "X-Api-Engine": "apisix", + "X-Api-Version": "v1,v2", + "X-Forwarded-Host": "127.0.0.1" + } +} +``` + +Note that both headers present and the header value of `X-Api-Version` configured in the Plugin is appended by the header value passed in the request. + +### Remove Existing Header + +The following example demonstrates how you can remove an existing header `User-Agent`. + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", + "methods": ["GET"], + "uri": "/headers", + "plugins": { + "proxy-rewrite": { + "headers": { + "remove":[ + "User-Agent" + ] } + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } -}' + }' +``` + +Send a request to verify if the specified header is removed: + +```shell +curl "http://127.0.0.1:9080/headers"; +``` + +You should see a response similar to the following, where the `User-Agent` header is not present: + +```text +{ + "headers": { + "Accept": "*/*", + "Host": "httpbin.org", + "X-Amzn-Trace-Id": "Root=1-64fef302-07f2b13e0eb006ba776ad91d", + "X-Forwarded-Host": "127.0.0.1" + } +} ``` -## Example usage +### Rewrite URI Using RegEx -Once you have enabled the Plugin as mentioned below, you can test the Route: +The following example demonstrates how you can parse text from the original Upstream URI path and use them to compose a new Upstream URI path. In this example, APISIX is configured to forward all requests from `/test/user/agent` to `/user-agent`. ```shell -curl -X GET http://127.0.0.1:9080/test/index.html +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", + "uri": "/test/*", + "plugins": { + # highlight-start + "proxy-rewrite": { + "regex_uri": ["^/test/(.*)/(.*)", "/$1-$2"] + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' ``` -Once you send the request, you can check the Upstream `access.log` for its output: +Send a request to `/test/user/agent` to check if it is redirected to `/user-agent`: +```shell +curl "http://127.0.0.1:9080/test/user/agent"; ``` -127.0.0.1 - [26/Sep/2019:10:52:20 +0800] iresty.com GET /test/home.html HTTP/1.1 200 38 - curl/7.29.0 - 0.000 199 107 + +You should see a response similar to the following: + +```text +{ + "user-agent": "curl/8.2.1" +} ``` -## Delete Plugin +### Add URL Parameters -To remove the `proxy-rewrite` 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. +The following example demonstrates how you can add URL parameters to the request. ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", + "methods": ["GET"], + "uri": "/get", + "plugins": { + "proxy-rewrite": { + "uri": "/get?arg1=apisix&arg2=plugin" + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` + +Send a request to verify if the URL parameters are also forwarded to upstream: + +```shell +curl "http://127.0.0.1:9080/get"; +``` + +You should see a response similar to the following: + +```text { + "args": { + "arg1": "apisix", + "arg2": "plugin" + }, + "headers": { + "Accept": "*/*", + "Host": "127.0.0.1", + "User-Agent": "curl/8.2.1", + "X-Amzn-Trace-Id": "Root=1-64fef6dc-2b0e09591db7353a275cdae4", + "X-Forwarded-Host": "127.0.0.1" + }, + "origin": "127.0.0.1, 103.248.35.148", + # highlight-next-line + "url": "http://127.0.0.1/get?arg1=apisix&arg2=plugin"; +} +``` + +### Rewrite HTTP Method + +The following example demonstrates how you can rewrite a GET request into a POST request. + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-rewrite-route", "methods": ["GET"], - "uri": "/test/index.html", - "plugins": {}, + "uri": "/get", + "plugins": { + "proxy-rewrite": { + "uri": "/anything", + "method":"POST" + } + }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:80": 1 + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` + +Send a GET request to `/get` to verify if it is transformed into a POST request to `/anything`: + +```shell +curl "http://127.0.0.1:9080/get"; +``` + +You should see a response similar to the following: + +```text +{ + "args": {}, + "data": "", + "files": {}, + "form": {}, + "headers": { + "Accept": "*/*", + "Host": "127.0.0.1", + "User-Agent": "curl/8.2.1", + "X-Amzn-Trace-Id": "Root=1-64fef7de-0c63387645353998196317f2", + "X-Forwarded-Host": "127.0.0.1" + }, + "json": null, + "method": "POST", + "origin": "::1, 103.248.35.179", + "url": "http://localhost/anything"; +} +``` + +### Forward Consumer Names to Upstream + +The following example demonstrates how you can forward the name of consumers who authenticates successfully to Upstream services. As an example, you will be using `key-auth` as the authentication method. + +Create a consumer `JohnDoe`: Review Comment: this one's right; I just checked for other instances as well -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
