# Proxy Rewrite

The `proxy-rewrite` plugin offers options to rewrite requests that APISIX forwards to upstream services. With the plugin, you can modify the HTTP methods, request destination upstream addresses, request headers, and more.

## Examples[​](#examples "Direct link to Examples")

The examples below demonstrate how you can configure `proxy-rewrite` on a route in different scenarios.

### Check URI Normalization Before Adding Rewrites[​](#check-uri-normalization-before-adding-rewrites "Direct link to Check URI Normalization Before Adding Rewrites")

For APISIX 3.19.0, distinguish the path used to match a route from the original request target and the path sent upstream:

| Value                               | Meaning before route plugins rewrite the request                                                                                                         |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uri`                               | Normalized path without the query string. NGINX has decoded escapes and resolved path components; configured APISIX normalization can adjust it further. |
| `request_uri` in the plugin context | That normalized path plus the query string.                                                                                                              |
| `real_request_uri`                  | Original request target, including its encoding and query string.                                                                                        |

The `uri-blocker` plugin checks the plugin context's `request_uri` during `rewrite`. A rule therefore sees the normalized path and the query string, not the original encoded path. For `/a%2Fb?x=%2F`, the default normalized path is `/a/b`, while the query remains `x=%2F`. A literal encoded-path rule is not an equivalent test of the normalized resource.

`proxy-rewrite` starts from `uri` by default. Its `uri` and `regex_uri` settings select what to forward after the route has already matched; they do not select another route. `use_real_request_uri_unsafe` changes the rewrite input to the original request target and bypasses normal safety processing. Do not enable it merely to make a blocking expression see raw bytes.

Verify the matched route, gateway log values, and upstream-observed path together. Use `curl --path-as-is` when a test must preserve path components that a client would otherwise remove. Check plain, encoded, repeated-slash, and query-string cases on the deployed release. URI forwarding fixes and router settings can change these results; one deny expression is not a complete access-control boundary.

A rejected request can still produce access logs, error or warning logs, metrics, and configured external log delivery. Blocking the upstream call does not eliminate gateway processing or logging costs.

### Rewrite Host Header[​](#rewrite-host-header "Direct link to 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.

* Admin API
* ADC
* Ingress Controller

```
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "id": "proxy-rewrite-route",

    "methods": ["GET"],

    "uri": "/headers",

    "plugins": {

      "proxy-rewrite": {

        "host": "myapisix.demo"

      }

    },

    "upstream": {

      "type": "roundrobin",

      "nodes": {

        "httpbin.org:80": 1

      }

    }

  }'
```

adc.yaml

```
services:

  - name: httpbin

    routes:

      - uris:

          - /headers

        name: proxy-rewrite-route

        methods:

          - GET

        plugins:

          proxy-rewrite:

            host: myapisix.demo

    upstream:

      type: roundrobin

      nodes:

        - host: httpbin.org

          port: 80

          weight: 1
```

Preview the changes and confirm that they only affect resources for this guide:

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=proxy-rewrite
```

Synchronize the configuration to the gateway:

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=proxy-rewrite
```

* Gateway API
* APISIX CRD

proxy-rewrite-ic.yaml

```
apiVersion: v1

kind: Service

metadata:

  namespace: aic

  name: httpbin-external-domain

spec:

  type: ExternalName

  externalName: httpbin.org

---

apiVersion: apisix.apache.org/v1alpha1

kind: PluginConfig

metadata:

  namespace: aic

  name: proxy-rewrite-plugin-config

spec:

  plugins:

    - name: proxy-rewrite

      config:

        host: myapisix.demo

---

apiVersion: gateway.networking.k8s.io/v1

kind: HTTPRoute

metadata:

  namespace: aic

  name: proxy-rewrite-route

spec:

  parentRefs:

    - name: apisix

  rules:

    - matches:

        - path:

            type: Exact

            value: /headers

      filters:

        - type: ExtensionRef

          extensionRef:

            group: apisix.apache.org

            kind: PluginConfig

            name: proxy-rewrite-plugin-config

      backendRefs:

        - name: httpbin-external-domain

          port: 80
```

Apply the configuration to your cluster:

```
kubectl apply -f proxy-rewrite-ic.yaml
```

proxy-rewrite-ic.yaml

```
apiVersion: apisix.apache.org/v2

kind: ApisixUpstream

metadata:

  namespace: aic

  name: httpbin-external-domain

spec:

  ingressClassName: apisix

  externalNodes:

  - type: Domain

    name: httpbin.org

---

apiVersion: apisix.apache.org/v2

kind: ApisixRoute

metadata:

  namespace: aic

  name: proxy-rewrite-route

spec:

  ingressClassName: apisix

  http:

    - name: proxy-rewrite-route

      match:

        paths:

          - /headers

      upstreams:

      - name: httpbin-external-domain

      plugins:

      - name: proxy-rewrite

        enable: true

        config:

          host: myapisix.demo
```

Apply the configuration to your cluster:

```
kubectl apply -f proxy-rewrite-ic.yaml
```

Send a request to `/headers` to check all the request headers sent to upstream:

```
curl "http://127.0.0.1:9080/headers"
```

You should see a response similar to the following:

```
{

  "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[​](#rewrite-uri-and-set-headers "Direct link to Rewrite URI And Set Headers")

The following example rewrites the upstream URI and sets request headers. A scalar value sets one header line, while an array sets repeated header lines in array order. Here, `X-Api-Engine` remains a scalar and `X-Api-Version` replaces any client value with two values.

* Admin API
* ADC
* Ingress Controller

```
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "id": "proxy-rewrite-route",

    "methods": ["GET"],

    "uri": "/",

    "plugins": {

      "proxy-rewrite": {

        "uri": "/anything",

        "headers": {

          "set": {

            "X-Api-Version": [

              "v1",

              "v2"

            ],

            "X-Api-Engine": "apisix"

          }

        }

      }

    },

    "upstream": {

      "type": "roundrobin",

      "nodes": {

        "httpbingo.org:80": 1

      }

    }

  }'
```

adc.yaml

```
services:

  - name: httpbingo

    routes:

      - uris:

          - /

        name: proxy-rewrite-route

        methods:

          - GET

        plugins:

          proxy-rewrite:

            uri: /anything

            headers:

              set:

                X-Api-Version:

                  - v1

                  - v2

                X-Api-Engine: apisix

    upstream:

      type: roundrobin

      nodes:

        - host: httpbingo.org

          port: 80

          weight: 1
```

Preview the changes and confirm that they only affect resources for this guide:

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=proxy-rewrite
```

Synchronize the configuration to the gateway:

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=proxy-rewrite
```

* Gateway API
* APISIX CRD

proxy-rewrite-ic.yaml

```
apiVersion: v1

kind: Service

metadata:

  namespace: aic

  name: httpbingo-external-domain

spec:

  type: ExternalName

  externalName: httpbingo.org

---

apiVersion: apisix.apache.org/v1alpha1

kind: PluginConfig

metadata:

  namespace: aic

  name: proxy-rewrite-plugin-config

spec:

  plugins:

    - name: proxy-rewrite

      config:

        uri: /anything

        headers:

          set:

            X-Api-Version:

              - v1

              - v2

            X-Api-Engine: apisix

---

apiVersion: gateway.networking.k8s.io/v1

kind: HTTPRoute

metadata:

  namespace: aic

  name: proxy-rewrite-route

spec:

  parentRefs:

    - name: apisix

  rules:

    - matches:

        - path:

            type: Exact

            value: /

      filters:

        - type: ExtensionRef

          extensionRef:

            group: apisix.apache.org

            kind: PluginConfig

            name: proxy-rewrite-plugin-config

      backendRefs:

        - name: httpbingo-external-domain

          port: 80
```

Apply the configuration to your cluster:

```
kubectl apply -f proxy-rewrite-ic.yaml
```

proxy-rewrite-ic.yaml

```
apiVersion: apisix.apache.org/v2

kind: ApisixUpstream

metadata:

  namespace: aic

  name: httpbingo-external-domain

spec:

  ingressClassName: apisix

  externalNodes:

  - type: Domain

    name: httpbingo.org

---

apiVersion: apisix.apache.org/v2

kind: ApisixRoute

metadata:

  namespace: aic

  name: proxy-rewrite-route

spec:

  ingressClassName: apisix

  http:

    - name: proxy-rewrite-route

      match:

        paths:

          - /

      upstreams:

      - name: httpbingo-external-domain

      plugins:

      - name: proxy-rewrite

        enable: true

        config:

          uri: /anything

          headers:

            set:

              X-Api-Version:

                - v1

                - v2

              X-Api-Engine: apisix
```

Apply the configuration to your cluster:

```
kubectl apply -f proxy-rewrite-ic.yaml
```

Send a request to verify:

```
curl "http://127.0.0.1:9080/" -H 'X-Api-Version: client'
```

You should see a response similar to the following:

```
{

  "headers": {

    "X-Api-Engine": [

      "apisix"

    ],

    "X-Api-Version": [

      "v1",

      "v2"

    ]

  }

}
```

The plugin sends two `X-Api-Version` header lines in the configured order. The incoming `client` value is absent because `headers.set` replaces existing values. The scalar `X-Api-Engine` configuration continues to set one header line.

### Rewrite URI And Append Headers[​](#rewrite-uri-and-append-headers "Direct link to 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.

* Admin API
* ADC
* Ingress Controller

```
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_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

      }

    }

  }'
```

adc.yaml

```
services:

  - name: httpbin

    routes:

      - uris:

          - /

        name: proxy-rewrite-route

        methods:

          - GET

        plugins:

          proxy-rewrite:

            uri: /headers

            headers:

              add:

                X-Api-Version: v1

                X-Api-Engine: apisix

    upstream:

      type: roundrobin

      nodes:

        - host: httpbin.org

          port: 80

          weight: 1
```

Preview the changes and confirm that they only affect resources for this guide:

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=proxy-rewrite
```

Synchronize the configuration to the gateway:

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=proxy-rewrite
```

* Gateway API
* APISIX CRD

proxy-rewrite-ic.yaml

```
apiVersion: v1

kind: Service

metadata:

  namespace: aic

  name: httpbin-external-domain

spec:

  type: ExternalName

  externalName: httpbin.org

---

apiVersion: apisix.apache.org/v1alpha1

kind: PluginConfig

metadata:

  namespace: aic

  name: proxy-rewrite-plugin-config

spec:

  plugins:

    - name: proxy-rewrite

      config:

        uri: /headers

        headers:

          add:

            X-Api-Version: v1

            X-Api-Engine: apisix

---

apiVersion: gateway.networking.k8s.io/v1

kind: HTTPRoute

metadata:

  namespace: aic

  name: proxy-rewrite-route

spec:

  parentRefs:

    - name: apisix

  rules:

    - matches:

        - path:

            type: Exact

            value: /

      filters:

        - type: ExtensionRef

          extensionRef:

            group: apisix.apache.org

            kind: PluginConfig

            name: proxy-rewrite-plugin-config

      backendRefs:

        - name: httpbin-external-domain

          port: 80
```

Apply the configuration to your cluster:

```
kubectl apply -f proxy-rewrite-ic.yaml
```

proxy-rewrite-ic.yaml

```
apiVersion: apisix.apache.org/v2

kind: ApisixUpstream

metadata:

  namespace: aic

  name: httpbin-external-domain

spec:

  ingressClassName: apisix

  externalNodes:

  - type: Domain

    name: httpbin.org

---

apiVersion: apisix.apache.org/v2

kind: ApisixRoute

metadata:

  namespace: aic

  name: proxy-rewrite-route

spec:

  ingressClassName: apisix

  http:

    - name: proxy-rewrite-route

      match:

        paths:

          - /

      upstreams:

      - name: httpbin-external-domain

      plugins:

      - name: proxy-rewrite

        enable: true

        config:

          uri: /headers

          headers:

            add:

              X-Api-Version: v1

              X-Api-Engine: apisix
```

Apply the configuration to your cluster:

```
kubectl apply -f proxy-rewrite-ic.yaml
```

Send a request to verify:

```
curl "http://127.0.0.1:9080/" -H 'X-Api-Version: v2'
```

You should see a response similar to the following:

```
{

  "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": "v2,v1",

    "X-Forwarded-Host": "127.0.0.1"

  }

}
```

Note that both headers present and the header value of `X-Api-Version` passed in the request is preserved, with the plugin's configured value appended after it.

### Remove Existing Header[​](#remove-existing-header "Direct link to Remove Existing Header")

The following example demonstrates how you can remove an existing header `User-Agent`.

* Admin API
* ADC
* Ingress Controller

```
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_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

      }

    }

  }'
```

adc.yaml

```
services:

  - name: httpbin

    routes:

      - uris:

          - /headers

        name: proxy-rewrite-route

        methods:

          - GET

        plugins:

          proxy-rewrite:

            headers:

              remove:

                - User-Agent

    upstream:

      type: roundrobin

      nodes:

        - host: httpbin.org

          port: 80

          weight: 1
```

Preview the changes and confirm that they only affect resources for this guide:

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=proxy-rewrite
```

Synchronize the configuration to the gateway:

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=proxy-rewrite
```

* Gateway API
* APISIX CRD

proxy-rewrite-ic.yaml

```
apiVersion: v1

kind: Service

metadata:

  namespace: aic

  name: httpbin-external-domain

spec:

  type: ExternalName

  externalName: httpbin.org

---

apiVersion: apisix.apache.org/v1alpha1

kind: PluginConfig

metadata:

  namespace: aic

  name: proxy-rewrite-plugin-config

spec:

  plugins:

    - name: proxy-rewrite

      config:

        headers:

          remove:

            - User-Agent

---

apiVersion: gateway.networking.k8s.io/v1

kind: HTTPRoute

metadata:

  namespace: aic

  name: proxy-rewrite-route

spec:

  parentRefs:

    - name: apisix

  rules:

    - matches:

        - path:

            type: Exact

            value: /headers

      filters:

        - type: ExtensionRef

          extensionRef:

            group: apisix.apache.org

            kind: PluginConfig

            name: proxy-rewrite-plugin-config

      backendRefs:

        - name: httpbin-external-domain

          port: 80
```

Apply the configuration to your cluster:

```
kubectl apply -f proxy-rewrite-ic.yaml
```

proxy-rewrite-ic.yaml

```
apiVersion: apisix.apache.org/v2

kind: ApisixUpstream

metadata:

  namespace: aic

  name: httpbin-external-domain

spec:

  ingressClassName: apisix

  externalNodes:

  - type: Domain

    name: httpbin.org

---

apiVersion: apisix.apache.org/v2

kind: ApisixRoute

metadata:

  namespace: aic

  name: proxy-rewrite-route

spec:

  ingressClassName: apisix

  http:

    - name: proxy-rewrite-route

      match:

        paths:

          - /headers

      upstreams:

      - name: httpbin-external-domain

      plugins:

      - name: proxy-rewrite

        enable: true

        config:

          headers:

            remove:

              - User-Agent
```

Apply the configuration to your cluster:

```
kubectl apply -f proxy-rewrite-ic.yaml
```

Send a request to verify if the specified header is removed:

```
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:

```
{

  "headers": {

    "Accept": "*/*", 

    "Host": "httpbin.org", 

    "X-Amzn-Trace-Id": "Root=1-64fef302-07f2b13e0eb006ba776ad91d", 

    "X-Forwarded-Host": "127.0.0.1"

  }

}
```

### Rewrite URI Using RegEx[​](#rewrite-uri-using-regex "Direct link to Rewrite URI Using RegEx")

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`.

* Admin API
* ADC
* Ingress Controller

```
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "id": "proxy-rewrite-route",

    "uri": "/test/*",

    "plugins": {

      "proxy-rewrite": {

        "regex_uri": ["^/test/(.*)/(.*)", "/$1-$2"]

      }

    },

    "upstream": {

      "type": "roundrobin",

      "nodes": {

        "httpbin.org:80": 1

      }

    }

  }'
```

adc.yaml

```
services:

  - name: httpbin

    routes:

      - uris:

          - /test/*

        name: proxy-rewrite-route

        plugins:

          proxy-rewrite:

            regex_uri:

              - ^/test/(.*)/(.*)

              - /$1-$2

    upstream:

      type: roundrobin

      nodes:

        - host: httpbin.org

          port: 80

          weight: 1
```

Preview the changes and confirm that they only affect resources for this guide:

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=proxy-rewrite
```

Synchronize the configuration to the gateway:

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=proxy-rewrite
```

* Gateway API
* APISIX CRD

proxy-rewrite-ic.yaml

```
apiVersion: v1

kind: Service

metadata:

  namespace: aic

  name: httpbin-external-domain

spec:

  type: ExternalName

  externalName: httpbin.org

---

apiVersion: apisix.apache.org/v1alpha1

kind: PluginConfig

metadata:

  namespace: aic

  name: proxy-rewrite-plugin-config

spec:

  plugins:

    - name: proxy-rewrite

      config:

        regex_uri:

          - ^/test/(.*)/(.*)

          - /$1-$2

---

apiVersion: gateway.networking.k8s.io/v1

kind: HTTPRoute

metadata:

  namespace: aic

  name: proxy-rewrite-route

spec:

  parentRefs:

    - name: apisix

  rules:

    - matches:

        - path:

            type: PathPrefix

            value: /test/

      filters:

        - type: ExtensionRef

          extensionRef:

            group: apisix.apache.org

            kind: PluginConfig

            name: proxy-rewrite-plugin-config

      backendRefs:

        - name: httpbin-external-domain

          port: 80
```

Apply the configuration to your cluster:

```
kubectl apply -f proxy-rewrite-ic.yaml
```

proxy-rewrite-ic.yaml

```
apiVersion: apisix.apache.org/v2

kind: ApisixUpstream

metadata:

  namespace: aic

  name: httpbin-external-domain

spec:

  ingressClassName: apisix

  externalNodes:

  - type: Domain

    name: httpbin.org

---

apiVersion: apisix.apache.org/v2

kind: ApisixRoute

metadata:

  namespace: aic

  name: proxy-rewrite-route

spec:

  ingressClassName: apisix

  http:

    - name: proxy-rewrite-route

      match:

        paths:

          - /test/*

      upstreams:

      - name: httpbin-external-domain

      plugins:

      - name: proxy-rewrite

        enable: true

        config:

          regex_uri:

            - ^/test/(.*)/(.*)

            - /$1-$2
```

Apply the configuration to your cluster:

```
kubectl apply -f proxy-rewrite-ic.yaml
```

Send a request to `/test/user/agent` to check if it is redirected to `/user-agent`:

```
curl "http://127.0.0.1:9080/test/user/agent"
```

You should see a response similar to the following:

```
{

  "user-agent": "curl/8.2.1"

}
```

### Add URL Parameters[​](#add-url-parameters "Direct link to Add URL Parameters")

The following example demonstrates how you can add URL parameters to the request.

* Admin API
* ADC
* Ingress Controller

```
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_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

      }

    }

  }'
```

adc.yaml

```
services:

  - name: httpbin

    routes:

      - uris:

          - /get

        name: proxy-rewrite-route

        methods:

          - GET

        plugins:

          proxy-rewrite:

            uri: /get?arg1=apisix&arg2=plugin

    upstream:

      type: roundrobin

      nodes:

        - host: httpbin.org

          port: 80

          weight: 1
```

Preview the changes and confirm that they only affect resources for this guide:

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=proxy-rewrite
```

Synchronize the configuration to the gateway:

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=proxy-rewrite
```

* Gateway API
* APISIX CRD

proxy-rewrite-ic.yaml

```
apiVersion: v1

kind: Service

metadata:

  namespace: aic

  name: httpbin-external-domain

spec:

  type: ExternalName

  externalName: httpbin.org

---

apiVersion: apisix.apache.org/v1alpha1

kind: PluginConfig

metadata:

  namespace: aic

  name: proxy-rewrite-plugin-config

spec:

  plugins:

    - name: proxy-rewrite

      config:

        uri: /get?arg1=apisix&arg2=plugin

---

apiVersion: gateway.networking.k8s.io/v1

kind: HTTPRoute

metadata:

  namespace: aic

  name: proxy-rewrite-route

spec:

  parentRefs:

    - name: apisix

  rules:

    - matches:

        - path:

            type: Exact

            value: /get

      filters:

        - type: ExtensionRef

          extensionRef:

            group: apisix.apache.org

            kind: PluginConfig

            name: proxy-rewrite-plugin-config

      backendRefs:

        - name: httpbin-external-domain

          port: 80
```

Apply the configuration to your cluster:

```
kubectl apply -f proxy-rewrite-ic.yaml
```

proxy-rewrite-ic.yaml

```
apiVersion: apisix.apache.org/v2

kind: ApisixUpstream

metadata:

  namespace: aic

  name: httpbin-external-domain

spec:

  ingressClassName: apisix

  externalNodes:

  - type: Domain

    name: httpbin.org

---

apiVersion: apisix.apache.org/v2

kind: ApisixRoute

metadata:

  namespace: aic

  name: proxy-rewrite-route

spec:

  ingressClassName: apisix

  http:

    - name: proxy-rewrite-route

      match:

        paths:

          - /get

      upstreams:

      - name: httpbin-external-domain

      plugins:

      - name: proxy-rewrite

        enable: true

        config:

          uri: /get?arg1=apisix&arg2=plugin
```

Apply the configuration to your cluster:

```
kubectl apply -f proxy-rewrite-ic.yaml
```

Send a request to verify if the URL parameters are also forwarded to upstream:

```
curl "http://127.0.0.1:9080/get"
```

You should see a response similar to the following:

```
{

  "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",

  "url": "http://127.0.0.1/get?arg1=apisix&arg2=plugin"

}
```

### Rewrite HTTP Method[​](#rewrite-http-method "Direct link to Rewrite HTTP Method")

The following example demonstrates how you can rewrite a GET request into a POST request.

* Admin API
* ADC
* Ingress Controller

```
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "id": "proxy-rewrite-route",

    "methods": ["GET"],

    "uri": "/get",

    "plugins": {

      "proxy-rewrite": {

        "uri": "/anything",

        "method":"POST"

      }

    },

    "upstream": {

      "type": "roundrobin",

      "nodes": {

        "httpbin.org:80": 1

      }

    }

  }'
```

adc.yaml

```
services:

  - name: httpbin

    routes:

      - uris:

          - /get

        name: proxy-rewrite-route

        methods:

          - GET

        plugins:

          proxy-rewrite:

            uri: /anything

            method: POST

    upstream:

      type: roundrobin

      nodes:

        - host: httpbin.org

          port: 80

          weight: 1
```

Preview the changes and confirm that they only affect resources for this guide:

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=proxy-rewrite
```

Synchronize the configuration to the gateway:

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=proxy-rewrite
```

* Gateway API
* APISIX CRD

proxy-rewrite-ic.yaml

```
apiVersion: v1

kind: Service

metadata:

  namespace: aic

  name: httpbin-external-domain

spec:

  type: ExternalName

  externalName: httpbin.org

---

apiVersion: apisix.apache.org/v1alpha1

kind: PluginConfig

metadata:

  namespace: aic

  name: proxy-rewrite-plugin-config

spec:

  plugins:

    - name: proxy-rewrite

      config:

        uri: /anything

        method: POST

---

apiVersion: gateway.networking.k8s.io/v1

kind: HTTPRoute

metadata:

  namespace: aic

  name: proxy-rewrite-route

spec:

  parentRefs:

    - name: apisix

  rules:

    - matches:

        - path:

            type: Exact

            value: /get

      filters:

        - type: ExtensionRef

          extensionRef:

            group: apisix.apache.org

            kind: PluginConfig

            name: proxy-rewrite-plugin-config

      backendRefs:

        - name: httpbin-external-domain

          port: 80
```

Apply the configuration to your cluster:

```
kubectl apply -f proxy-rewrite-ic.yaml
```

proxy-rewrite-ic.yaml

```
apiVersion: apisix.apache.org/v2

kind: ApisixUpstream

metadata:

  namespace: aic

  name: httpbin-external-domain

spec:

  ingressClassName: apisix

  externalNodes:

  - type: Domain

    name: httpbin.org

---

apiVersion: apisix.apache.org/v2

kind: ApisixRoute

metadata:

  namespace: aic

  name: proxy-rewrite-route

spec:

  ingressClassName: apisix

  http:

    - name: proxy-rewrite-route

      match:

        paths:

          - /get

      upstreams:

      - name: httpbin-external-domain

      plugins:

      - name: proxy-rewrite

        enable: true

        config:

          uri: /anything

          method: POST
```

Apply the configuration to your cluster:

```
kubectl apply -f proxy-rewrite-ic.yaml
```

Send a GET request to `/get` to verify if it is transformed into a POST request to `/anything`:

```
curl "http://127.0.0.1:9080/get"
```

You should see a response similar to the following:

```
{

  "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[​](#forward-consumer-names-to-upstream "Direct link to 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`](https://docs.api7.ai/hub/key-auth.md) as the authentication method.

* Admin API
* ADC
* Ingress Controller

Create a consumer `JohnDoe`:

```
curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "username": "JohnDoe"

  }'
```

Create `key-auth` credential for the consumer:

```
curl "http://127.0.0.1:9180/apisix/admin/consumers/JohnDoe/credentials" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "id": "cred-john-key-auth",

    "plugins": {

      "key-auth": {

        "key": "john-key"

      }

    }

  }'
```

Next, create a route with key authentication enabled, and configure `proxy-rewrite` to add consumer name to the header:

```
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "id": "consumer-restricted-route",

    "uri": "/get",

    "plugins": {

      "key-auth": {},

      "proxy-rewrite": {

        "headers": {

          "set": {

            "X-Apisix-Consumer": "$consumer_name"

          },

          "remove": [ "Apikey" ]

        }

      }

    },

    "upstream" : {

      "nodes": {

        "httpbin.org":1

      }

    }

  }'
```

Create a consumer with `key-auth` credential and a route with `key-auth` and `proxy-rewrite` plugins configured as such:

adc.yaml

```
consumers:

  - username: JohnDoe

    credentials:

      - name: cred-john-key-auth

        type: key-auth

        config:

          key: john-key

services:

  - name: httpbin

    routes:

      - name: consumer-restricted-route

        uris:

          - /get

        plugins:

          key-auth: {}

          proxy-rewrite:

            headers:

              set:

                X-Apisix-Consumer: $consumer_name

              remove:

                - Apikey

    upstream:

      type: roundrobin

      nodes:

        - host: httpbin.org

          port: 80

          weight: 1
```

Preview the changes and confirm that they only affect resources for this guide:

```
adc diff -f adc.yaml \

  --include-resource-type consumer \

  --include-resource-type service \

  --label-selector docs-example=proxy-rewrite
```

Synchronize the configuration to the gateway:

```
adc sync -f adc.yaml \

  --include-resource-type consumer \

  --include-resource-type service \

  --label-selector docs-example=proxy-rewrite
```

* Gateway API
* APISIX CRD

proxy-rewrite-ic.yaml

```
apiVersion: apisix.apache.org/v1alpha1

kind: Consumer

metadata:

  namespace: aic

  name: johndoe

spec:

  gatewayRef:

    name: apisix

  credentials:

    - type: key-auth

      name: cred-john-key-auth

      config:

        key: john-key

---

apiVersion: v1

kind: Service

metadata:

  namespace: aic

  name: httpbin-external-domain

spec:

  type: ExternalName

  externalName: httpbin.org

---

apiVersion: apisix.apache.org/v1alpha1

kind: PluginConfig

metadata:

  namespace: aic

  name: proxy-rewrite-plugin-config

spec:

  plugins:

    - name: key-auth

      config:

        _meta:

          disable: false

    - name: proxy-rewrite

      config:

        headers:

          set:

            X-Apisix-Consumer: $consumer_name

          remove:

            - Apikey

---

apiVersion: gateway.networking.k8s.io/v1

kind: HTTPRoute

metadata:

  namespace: aic

  name: consumer-restricted-route

spec:

  parentRefs:

    - name: apisix

  rules:

    - matches:

        - path:

            type: Exact

            value: /get

      filters:

        - type: ExtensionRef

          extensionRef:

            group: apisix.apache.org

            kind: PluginConfig

            name: proxy-rewrite-plugin-config

      backendRefs:

        - name: httpbin-external-domain

          port: 80
```

Apply the configuration to your cluster:

```
kubectl apply -f proxy-rewrite-ic.yaml
```

proxy-rewrite-ic.yaml

```
apiVersion: apisix.apache.org/v2

kind: ApisixConsumer

metadata:

  namespace: aic

  name: johndoe

spec:

  ingressClassName: apisix

  authParameter:

    keyAuth:

      value:

        key: john-key

---

apiVersion: apisix.apache.org/v2

kind: ApisixUpstream

metadata:

  namespace: aic

  name: httpbin-external-domain

spec:

  ingressClassName: apisix

  externalNodes:

  - type: Domain

    name: httpbin.org

---

apiVersion: apisix.apache.org/v2

kind: ApisixRoute

metadata:

  namespace: aic

  name: consumer-restricted-route

spec:

  ingressClassName: apisix

  http:

    - name: consumer-restricted-route

      match:

        paths:

          - /get

      upstreams:

      - name: httpbin-external-domain

      plugins:

      - name: key-auth

        enable: true

      - name: proxy-rewrite

        enable: true

        config:

          headers:

            set:

              X-Apisix-Consumer: $consumer_name

            remove:

              - Apikey
```

Apply the configuration to your cluster:

```
kubectl apply -f proxy-rewrite-ic.yaml
```

❶ Add the consumer name to the header `X-Apisix-Consumer` using the [built-in variables](https://docs.api7.ai/apisix/reference/built-in-variables.md#apisix-variables).

❷ Remove the authentication key so that it is not visible to the upstream service.

Send a request to the route as consumer `JohnDoe`:

```
curl -i "http://127.0.0.1:9080/get" -H 'apikey: john-key'
```

You should receive an `HTTP/1.1 200 OK` response with the following body:

```
{

  "args": {}, 

  "headers": {

    "Accept": "*/*",

    "Host": "127.0.0.1", 

    "User-Agent": "curl/8.4.0", 

    "X-Amzn-Trace-Id": "Root=1-664b01a6-2163c0156ed4bff51d87d877",

    "X-Apisix-Consumer": "JohnDoe", 

    "X-Forwarded-Host": "127.0.0.1"

  }, 

  "origin": "172.19.0.1, 203.12.12.12", 

  "url": "http://127.0.0.1/get"

}
```

info

When using the Ingress Controller, the consumer name is prefixed with the namespace. For example, a consumer named `JohnDoe` in namespace `aic` will appear as `aic_johndoe` in the `X-Apisix-Consumer` header.

Send another request to the route without the valid credential:

```
curl -i "http://127.0.0.1:9080/get"
```

You should receive an `HTTP/1.1 401 Unauthorized` response.

### Dynamically Forward Requests in `radixtree_uri_with_parameter` Router Mode[​](#dynamically-forward-requests-in-radixtree_uri_with_parameter-router-mode "Direct link to dynamically-forward-requests-in-radixtree_uri_with_parameter-router-mode")

The following example demonstrates how to extract part of the URL path using the `uri_param_*` variable and forward the value to the upstream service in a new header. This example assumes that APISIX is operating in the `radixtree_uri_with_parameter` [router mode](https://docs.api7.ai/apisix/reference/router-options.md).

Create a route as such:

* Admin API
* ADC
* Ingress Controller

```
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "id": "httpbin",

    "uri": "/anything/user/:user_id/profile",

    "plugins":{

      "proxy-rewrite": {

        "headers": {

          "set": {

            "X-User-ID": "$uri_param_user_id"

          }

        }

      }

    },

    "upstream": {

      "type": "roundrobin",

      "nodes": {

        "httpbin.org:80": 1

      }

    }

  }'
```

adc.yaml

```
services:

  - name: httpbin

    routes:

      - name: httpbin

        uris:

          - /anything/user/:user_id/profile

        plugins:

          proxy-rewrite:

            headers:

              set:

                X-User-ID: $uri_param_user_id

    upstream:

      type: roundrobin

      nodes:

        - host: httpbin.org

          port: 80

          weight: 1
```

Preview the changes and confirm that they only affect resources for this guide:

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=proxy-rewrite
```

Synchronize the configuration to the gateway:

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=proxy-rewrite
```

* Gateway API
* APISIX CRD

proxy-rewrite-ic.yaml

```
apiVersion: v1

kind: Service

metadata:

  namespace: aic

  name: httpbin-external-domain

spec:

  type: ExternalName

  externalName: httpbin.org

---

apiVersion: apisix.apache.org/v1alpha1

kind: PluginConfig

metadata:

  namespace: aic

  name: proxy-rewrite-plugin-config

spec:

  plugins:

    - name: proxy-rewrite

      config:

        headers:

          set:

            X-User-ID: $uri_param_user_id

---

apiVersion: gateway.networking.k8s.io/v1

kind: HTTPRoute

metadata:

  namespace: aic

  name: httpbin

spec:

  parentRefs:

    - name: apisix

  rules:

    - matches:

        - path:

            type: PathPrefix

            value: /anything/user/

      filters:

        - type: ExtensionRef

          extensionRef:

            group: apisix.apache.org

            kind: PluginConfig

            name: proxy-rewrite-plugin-config

      backendRefs:

        - name: httpbin-external-domain

          port: 80
```

Apply the configuration to your cluster:

```
kubectl apply -f proxy-rewrite-ic.yaml
```

proxy-rewrite-ic.yaml

```
apiVersion: apisix.apache.org/v2

kind: ApisixUpstream

metadata:

  namespace: aic

  name: httpbin-external-domain

spec:

  ingressClassName: apisix

  externalNodes:

  - type: Domain

    name: httpbin.org

---

apiVersion: apisix.apache.org/v2

kind: ApisixRoute

metadata:

  namespace: aic

  name: httpbin

spec:

  ingressClassName: apisix

  http:

    - name: httpbin

      match:

        paths:

          - /anything/user/*/profile

      upstreams:

      - name: httpbin-external-domain

      plugins:

      - name: proxy-rewrite

        enable: true

        config:

          headers:

            set:

              X-User-ID: $uri_param_user_id
```

Apply the configuration to your cluster:

```
kubectl apply -f proxy-rewrite-ic.yaml
```

❶ Match requests to `/anything/user/:user_id/profile` where `user_id` is a parameter.

❷ Assign the `user_id` parameter value to a new header `X-User-ID`.

Send a request to the route:

```
curl "http://127.0.0.1:9080/anything/user/123/profile"
```

You should see the following response:

```
{

  "args": {}, 

  "data": "", 

  "files": {}, 

  "form": {}, 

  "headers": {

    "Accept": "*/*",

    "Host": "127.0.0.1",

    "User-Agent": "curl/8.6.0",

    "X-Amzn-Trace-Id": "Root=1-68873cf5-7248f64d19d607ea50aa9735",

    "X-Forwarded-Host": "127.0.0.1",

    "X-User-Id": "123"

  }, 

  ...

}
```

The route parameter can also accept URL-encoded string. For instance, if you send a request as such:

```
curl -i "http://127.0.0.1:9080/anything/user/123%20456/profile"
```

The user ID would be extracted as `123 456`:

```
{

  "args": {}, 

  "data": "", 

  "files": {}, 

  "form": {}, 

  "headers": {

    "Accept": "*/*", 

    "Host": "127.0.0.1", 

    "User-Agent": "curl/8.6.0",

    "X-Amzn-Trace-Id": "Root=1-68873d37-7634825b20d05dee3a852cb9",

    "X-Forwarded-Host": "127.0.0.1",

    "X-User-Id": "123 456"

  }, 

  ...

}
```
