Ingress Path Matching¶
Regular Expression Support¶
Important
Regular expressions and wild cards are not supported in the spec.rules.host
field. Full hostnames must be used.
The ingress controller supports case insensitive regular expressions in the spec.rules.http.paths.path
field.
See the description 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: rules: - host: test.com 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 accurate 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 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: rules: - host: test.com http: paths: - path: /foo/bar backend: serviceName: service1 servicePort: 80 - path: /foo/bar/ backend: serviceName: service2 servicePort: 80
apiVersion: extensions/v1beta1 kind: Ingress metadata: name: test-ingress-2 annotations: nginx.ingress.kubernetes.io/rewrite-target: / spec: rules: - host: test.com http: paths: - path: /foo/bar/.+ backend: serviceName: service3 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/.+ { ... } 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/.+
and will go to service 3.test.com/foo/bar/
matches~* ^/foo/bar/
and will go to service 2.test.com/foo/bar
matches~* ^/foo/bar
and will go to service 1.
IMPORTANT NOTES:
- If the
use-regex
ORrewrite-target
annotation is used on any Ingress for a given host, then the case insensitive regular expression location modifier 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. For more information about how a path is chosen, please read the following article: "Understanding Nginx Server and Location Block Selection Algorithms".
Example¶
Let the following ingress be defined:
apiVersion: extensions/v1beta1 kind: Ingress metadata: name: test-ingress-3 annotations: nginx.ingress.kubernetes.io/use-regex: "true" spec: rules: - host: test.com 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.