DevFW-CICD/ingress-nginx-helm
6
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add 'use regex' annotation to toggle nginx regex location modifier

Browse source
This commit is contained in:
Zenara Daley 2018-10-01 13:54:11 -04:00
parent f56e839134
commit f29bdc3e8d
10 changed files with 325 additions and 39 deletions
Download patch file Download diff file Expand all files Collapse all files

1
docs/examples/rewrite/README.md
View file

@ -20,6 +20,7 @@ Rewriting can be controlled using the following annotations:
|nginx.ingress.kubernetes.io/ssl-redirect|Indicates if the location section is accessible SSL only (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|
## Validation

155
docs/user-guide/ingress-path-matching.md Normal file
View file

@ -0,0 +1,155 @@
# Ingress Path Matching
## Regular Expression Support
The ingress controller supports **case insensitive** regular expressions in the `spec.rules.http.paths.path` field. __Currently curly braces `{}` cannot be used in regular expressions due to a [known issue](https://github.com/kubernetes/ingress-nginx/issues/3155).__
See the [description](./nginx-configuration/annotations.md#use-regex) of the `use-regex` annotation for more details.
```
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: test-ingress
annotations:
nginx.ingress.kubernetes.io/use-regex: true
spec:
host: test.com
rules:
- http:
paths:
- path: /foo/.*
backend:
serviceName: test
servicePort: 80
```
The preceding ingress definition would translate to the following location block within the NGINX configuration for the `test.com` server:
```
location ~* ^/foo/.* {
...
}
```
## Path Priority
In NGINX, regular expressions follow a **first match** policy. In order to enable more acurate path matching, ingress-nginx first orders the paths by descending length before writing them to the NGINX template as location blocks.
__Please read the [warning](#warning) before using regular expressions in your ingress definitions.__
### Example
Let the following two ingress definitions be created:
```
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: test-ingress-1
spec:
host: test.com
rules:
- http:
paths:
- path: /foo/bar
backend:
serviceName: test
servicePort: 80
- path: /foo/bar/
backend:
serviceName: test
servicePort: 80
```
```
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: test-ingress-2
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /
spec:
host: test.com
rules:
- http:
paths:
- path: /foo/bar/.+
backend:
serviceName: test
servicePort: 80
```
The ingress controller would define the following location blocks, in order of descending length, within the NGINX template for the `test.com` server:
```
location ~* ^/foo/bar/.+\/?(?<baseuri>.*) {
...
}
location ~* ^/foo/bar/ {
...
}
location ~* ^/foo/bar {
...
}
```
The following request URI's would match the corresponding location blocks:
- `test.com/foo/bar/1` matches `~* ^/foo/bar/.+\/?(?<baseuri>.*)`
- `test.com/foo/bar/` matches `~* ^/foo/bar/`
- `test.com/foo/bar` matches `~* ^/foo/bar`
__IMPORTANT NOTES__:
- paths created under the `rewrite-ingress` are sorted before `\/?(?<baseuri>.*)` is appended. For example if the path defined within `test-ingress-2` was `/foo/.+` then the location block for `^/foo/.+\/?(?<baseuri>.*)` would be the LAST block listed.
- If the `use-regex` OR `rewrite-target` annotation is used on any Ingress for a given host, then the case insensitive regular expression [location modifier](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.
## Warning
The following example describes a case that may inflict unwanted path matching behaviour.
This case is expected and a result of NGINX's a first match policy for paths that use the regular expression [location modifier](https://nginx.org/en/docs/http/ngx_http_core_module.html#location). For more information about how a path is chosen, please read the following article: ["Understanding Nginx Server and Location Block Selection Algorithms"](https://www.digitalocean.com/community/tutorials/understanding-nginx-server-and-location-block-selection-algorithms).
### Example
Let the following ingress be defined:
```
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: test-ingress-1
annotations:
nginx.ingress.kubernetes.io/use-regex: true
spec:
host: test.com
rules:
- http:
paths:
- path: /foo/bar/bar
backend:
serviceName: test
servicePort: 80
- path: /foo/bar/[A-Z0-9]{3}
backend:
serviceName: test
servicePort: 80
```
The ingress controller would define the following location blocks (in this order) within the NGINX template for the `test.com` server:
```
location ~* ^/foo/bar/[A-Z0-9]{3} {
...
}
location ~* ^/foo/bar/bar {
...
}
```
A request to `test.com/foo/bar/bar` would match the `^/foo/[A-Z0-9]{3}` location block instead of the longest EXACT matching path.

23
docs/user-guide/nginx-configuration/annotations.md
View file

@ -86,6 +86,7 @@ You can add these Kubernetes annotations to specific Ingress objects to customiz
|[nginx.ingress.kubernetes.io/influxdb-port](#influxdb)|string|
|[nginx.ingress.kubernetes.io/influxdb-host](#influxdb)|string|
|[nginx.ingress.kubernetes.io/influxdb-server-name](#influxdb)|string|
|[nginx.ingress.kubernetes.io/use-regex](#use-regex)|bool|
### Rewrite
@ -630,3 +631,25 @@ Example:
```yaml
nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
```
### Use Regex
Using the `nginx.ingress.kubernetes.io/use-regex` annotation will indicate whether or not the paths defined on an Ingress use regular expressions. The default value is `false`.
The following will indicate that regular expression paths are being used:
```yaml
nginx.ingress.kubernetes.io/use-regex: "true"
```
The following will indicate that regular expression paths are __not__ being used:
```yaml
nginx.ingress.kubernetes.io/use-regex: "false"
```
When this annotation is set to `true`, the case insensitive regular expression [location modifier](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.
Additionally, if the [`rewrite-target` annotation](#rewrite) is used on any Ingress for a given host, then the case insensitive regular expression [location modifier](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.
Please read about [ingress path matching](../ingress-path-matching.md) before using this modifier.