1614027cd4
* clarify link * Add section headers * console blocks * grpc example json was not valid * multi-tls update text The preceding point 1 related to4f2cb51ef8/ingress/controllers/nginx/examples/ingress.yamland the deployments referenced in4f2cb51ef8/ingress/controllers/nginx/examples/README.mdThey are not relevant to the current instructions. * add whitespace around parens * grammar setup would be a proper noun, but it is not the intended concept, which is a state * grammar * is-only * via * Use bullets for choices * ingress-controller nginx is a distinct brand. generally this repo talks about ingress-controller, although it is quite inconsistent about how... * drop stray paren * OAuth is a brand and needs an article here also GitHub is a brand * Indent text under numbered lists * use e.g. * Document that customer header config maps changes do not trigger updates This should be removed if https://github.com/kubernetes/ingress-nginx/issues/5238 is fixed. * article * period * infinitive verb + period * clarify that the gRPC server is responsible for listening for TCP traffic and not some other part of the backend application * avoid using ; and reword * whitespace * brand: gRPC * only-does is the right form `for` adds nothing here * spelling: GitHub * punctuation `;` is generally not the right punctuation... * drop stray `to` * sentence * backticks * fix link * Improve readability of compare/vs * Renumber list * punctuation * Favor Ingress-NGINX and Ingress NGINX * Simplify custom header restart text * Undo typo damage Co-authored-by: Josh Soref <jsoref@users.noreply.github.com>
107 lines
3.4 KiB
Markdown
107 lines
3.4 KiB
Markdown
# Rewrite
|
|
|
|
This example demonstrates how to use `Rewrite` annotations.
|
|
|
|
## Prerequisites
|
|
|
|
You will need to make sure your Ingress targets exactly one Ingress
|
|
controller by specifying the [ingress.class annotation](../../user-guide/multiple-ingress.md),
|
|
and that you have an ingress controller [running](../../deploy/) in your cluster.
|
|
|
|
## Deployment
|
|
|
|
Rewriting can be controlled using the following annotations:
|
|
|
|
|Name|Description|Values|
|
|
| --- | --- | --- |
|
|
|nginx.ingress.kubernetes.io/rewrite-target|Target URI where the traffic must be redirected|string|
|
|
|nginx.ingress.kubernetes.io/ssl-redirect|Indicates if the location section is only accessible via SSL (defaults to True when Ingress contains a Certificate)|bool|
|
|
|nginx.ingress.kubernetes.io/force-ssl-redirect|Forces the redirection to HTTPS even if the Ingress is not TLS Enabled|bool|
|
|
|nginx.ingress.kubernetes.io/app-root|Defines the Application Root that the Controller must redirect if it's in `/` context|string|
|
|
|nginx.ingress.kubernetes.io/use-regex|Indicates if the paths defined on an Ingress use regular expressions|bool|
|
|
|
|
## Examples
|
|
|
|
### Rewrite Target
|
|
|
|
!!! attention
|
|
Starting in Version 0.22.0, ingress definitions using the annotation `nginx.ingress.kubernetes.io/rewrite-target` are not backwards compatible with previous versions. In Version 0.22.0 and beyond, any substrings within the request URI that need to be passed to the rewritten path must explicitly be defined in a [capture group](https://www.regular-expressions.info/refcapture.html).
|
|
|
|
!!! note
|
|
[Captured groups](https://www.regular-expressions.info/refcapture.html) are saved in numbered placeholders, chronologically, in the form `$1`, `$2` ... `$n`. These placeholders can be used as parameters in the `rewrite-target` annotation.
|
|
|
|
Create an Ingress rule with a rewrite annotation:
|
|
|
|
```console
|
|
$ echo '
|
|
apiVersion: networking.k8s.io/v1
|
|
kind: Ingress
|
|
metadata:
|
|
annotations:
|
|
nginx.ingress.kubernetes.io/rewrite-target: /$2
|
|
name: rewrite
|
|
namespace: default
|
|
spec:
|
|
ingressClassName: nginx
|
|
rules:
|
|
- host: rewrite.bar.com
|
|
http:
|
|
paths:
|
|
- path: /something(/|$)(.*)
|
|
pathType: Prefix
|
|
backend:
|
|
service:
|
|
name: http-svc
|
|
port:
|
|
number: 80
|
|
' | kubectl create -f -
|
|
```
|
|
|
|
In this ingress definition, any characters captured by `(.*)` will be assigned to the placeholder `$2`, which is then used as a parameter in the `rewrite-target` annotation.
|
|
|
|
For example, the ingress definition above will result in the following rewrites:
|
|
|
|
- `rewrite.bar.com/something` rewrites to `rewrite.bar.com/`
|
|
- `rewrite.bar.com/something/` rewrites to `rewrite.bar.com/`
|
|
- `rewrite.bar.com/something/new` rewrites to `rewrite.bar.com/new`
|
|
|
|
### App Root
|
|
|
|
Create an Ingress rule with an app-root annotation:
|
|
```
|
|
$ echo "
|
|
apiVersion: networking.k8s.io/v1
|
|
kind: Ingress
|
|
metadata:
|
|
annotations:
|
|
nginx.ingress.kubernetes.io/app-root: /app1
|
|
name: approot
|
|
namespace: default
|
|
spec:
|
|
ingressClassName: nginx
|
|
rules:
|
|
- host: approot.bar.com
|
|
http:
|
|
paths:
|
|
- path: /
|
|
pathType: Prefix
|
|
backend:
|
|
service:
|
|
name: http-svc
|
|
port:
|
|
number: 80
|
|
" | kubectl create -f -
|
|
```
|
|
|
|
Check the rewrite is working
|
|
|
|
```
|
|
$ curl -I -k http://approot.bar.com/
|
|
HTTP/1.1 302 Moved Temporarily
|
|
Server: nginx/1.11.10
|
|
Date: Mon, 13 Mar 2017 14:57:15 GMT
|
|
Content-Type: text/html
|
|
Content-Length: 162
|
|
Location: http://approot.bar.com/app1
|
|
Connection: keep-alive
|
|
```
|