2024-09-15 15:04:08 +00:00
<!doctype html> < html lang = en class = no-js > < head > < meta charset = utf-8 > < meta name = viewport content = "width=device-width,initial-scale=1" > < link href = https://kubernetes.github.io/ingress-nginx/user-guide/ingress-path-matching/ rel = canonical > < link href = ../fcgi-services/ rel = prev > < link href = ../external-articles/ rel = next > < link rel = icon href = ../../assets/images/favicon.png > < meta name = generator content = "mkdocs-1.5.3, mkdocs-material-9.4.5" > < title > Regular expressions in paths - Ingress-Nginx Controller< / title > < link rel = stylesheet href = ../../assets/stylesheets/main.6a10b989.min.css > < link rel = stylesheet href = ../../assets/stylesheets/palette.356b1318.min.css > < link rel = preconnect href = https://fonts.gstatic.com crossorigin > < link rel = stylesheet href = "https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback" > < style > : root { --md-text-font : "Roboto" ; --md-code-font : "Roboto Mono" } < / style > < link rel = stylesheet href = ../../extra.css > < script > _ _md _scope = new URL ( "../.." , location ) , _ _md _hash = e => [ ... e ] . reduce ( ( e , _ ) => ( e << 5 ) - e + _ . charCodeAt ( 0 ) , 0 ) , _ _md _get = ( e , _ = localStorage , t = _ _md _scope ) => JSON . parse ( _ . getItem ( t . pathname + "." + e ) ) , _ _md _set = ( e , _ , t = localStorage , a = _ _md _scope ) => { try { t . setItem ( a . pathname + "." + e , JSON . stringify ( _ ) ) } catch ( e ) { } } < / script > < / head > < body dir = ltr data-md-color-scheme = default data-md-color-primary = teal data-md-color-accent = green > < input class = md-toggle data-md-toggle = drawer type = checkbox id = __drawer autocomplete = off > < input class = md-toggle data-md-toggle = search type = checkbox id = __search autocomplete = off > < label class = md-overlay for = __drawer > < / label > < div data-md-component = skip > < a href = #ingress-path-matching class = md-skip > Skip to content < / a > < / div > < div data-md-component = announce > < / div > < header class = "md-header md-header--shadow md-header--lifted" data-md-component = header > < nav class = "md-header__inner md-grid" aria-label = Header > < a href = ../.. title = "Ingress-Nginx Controller" class = "md-header__button md-logo" aria-label = "Ingress-Nginx Controller" data-md-component = logo > < svg xmlns = http://www.w3.org/2000/svg viewbox = "0 0 24 24" > < path d = "M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54Z" / > < / svg > < / a > < label class = "md-header__button md-icon" for = __drawer > < svg xmlns = http://www.w3.org/2000/svg viewbox = "0 0 24 24" > < path d = "M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2Z" / > < / svg > < / label > < div class = md-header__title data-md-component = header-title > < div class = md-header__ellipsis > < div class = md-header__topic > < span class = md-ellipsis > Ingress-Nginx Controller < / span > < / div > < div class = md-header__topic data-md-component = header-topic > < span class = md-ellipsis > Regular expressions in paths < / span > < / div > < / div > < / div > < label class = "md-header__button md-icon" for = __search > < svg xmlns = http://www.w3.org/2000/svg viewbox = "0 0 24 24" > < path d = "M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z" / > < / svg > < / label > < div class = md-search data-md-component = search role = dialog > < label class = md-search__overlay for = __search > < / label > < div class = md-search__inner role = search > < form class = md-search__form name = search > < input type = text class = md-search__input name = query aria-label = Search placeholder = Search autocapitalize = off autocorrect = off autocomplete = off spellcheck = false data-md-component = search-query required > < label class = "md-search__icon md-icon" for = __search > < svg xmlns = http://www.w3.org/2000/svg viewbox = "0 0 24 24" > < path d = "M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z" / > < / svg > < svg xmlns = http://www.w3.org/2000/svg viewbox = "0 0 24 24" > < path d = "M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12Z" / > < / svg > < / label > < nav class = md-search__options aria-label = Se
2023-10-12 19:31:18 +00:00
< span class = nt > kind< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > Ingress< / span >
2021-01-11 15:59:14 +00:00
< span class = nt > metadata< / span > < span class = p > :< / span >
2023-10-12 19:31:18 +00:00
< span class = w > < / span > < span class = nt > name< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > test-ingress< / span >
< span class = w > < / span > < span class = nt > annotations< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > nginx.ingress.kubernetes.io/use-regex< / span > < span class = p > :< / span > < span class = w > < / span > < span class = s > " true" < / span >
2021-01-11 15:59:14 +00:00
< span class = nt > spec< / span > < span class = p > :< / span >
2023-10-12 19:31:18 +00:00
< span class = w > < / span > < span class = nt > ingressClassName< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > nginx< / span >
< span class = w > < / span > < span class = nt > rules< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = "p p-Indicator" > -< / span > < span class = w > < / span > < span class = nt > host< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > test.com< / span >
< span class = w > < / span > < span class = nt > http< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > paths< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = "p p-Indicator" > -< / span > < span class = w > < / span > < span class = nt > path< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > /foo/.*< / span >
< span class = w > < / span > < span class = nt > pathType< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > ImplementationSpecific< / span >
< span class = w > < / span > < span class = nt > backend< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > service< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > name< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > test< / span >
< span class = w > < / span > < span class = nt > port< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > number< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > 80< / span >
2021-01-11 15:59:14 +00:00
< / code > < / pre > < / div > < p > The preceding ingress definition would translate to the following location block within the NGINX configuration for the < code > test.com< / code > server:< / p > < div class = highlight > < pre > < span > < / span > < code > location ~* " ^/foo/.*" {
2020-04-15 17:09:38 +00:00
...
}
2023-10-12 19:31:18 +00:00
< / code > < / pre > < / div > < h2 id = path-priority > Path Priority< a class = headerlink href = #path-priority title = "Permanent link" > ¶< / a > < / h2 > < p > In NGINX, regular expressions follow a < strong > first match< / strong > 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.< / p > < p > < strong > Please read the < a href = #warning > warning< / a > before using regular expressions in your ingress definitions.< / strong > < / p > < h3 id = example > Example< a class = headerlink href = #example title = "Permanent link" > ¶< / a > < / h3 > < p > Let the following two ingress definitions be created:< / p > < div class = highlight > < pre > < span > < / span > < code > < span class = nt > apiVersion< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > networking.k8s.io/v1< / span >
< span class = nt > kind< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > Ingress< / span >
2021-01-11 15:59:14 +00:00
< span class = nt > metadata< / span > < span class = p > :< / span >
2023-10-12 19:31:18 +00:00
< span class = w > < / span > < span class = nt > name< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > test-ingress-1< / span >
2021-01-11 15:59:14 +00:00
< span class = nt > spec< / span > < span class = p > :< / span >
2023-10-12 19:31:18 +00:00
< span class = w > < / span > < span class = nt > ingressClassName< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > nginx< / span >
< span class = w > < / span > < span class = nt > rules< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = "p p-Indicator" > -< / span > < span class = w > < / span > < span class = nt > host< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > test.com< / span >
< span class = w > < / span > < span class = nt > http< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > paths< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = "p p-Indicator" > -< / span > < span class = w > < / span > < span class = nt > path< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > /foo/bar< / span >
< span class = w > < / span > < span class = nt > pathType< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > Prefix< / span >
< span class = w > < / span > < span class = nt > backend< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > service< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > name< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > service1< / span >
< span class = w > < / span > < span class = nt > port< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > number< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > 80< / span >
< span class = w > < / span > < span class = "p p-Indicator" > -< / span > < span class = w > < / span > < span class = nt > path< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > /foo/bar/< / span >
< span class = w > < / span > < span class = nt > pathType< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > Prefix< / span >
< span class = w > < / span > < span class = nt > backend< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > service< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > name< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > service2< / span >
< span class = w > < / span > < span class = nt > port< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > number< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > 80< / span >
< / code > < / pre > < / div > < div class = highlight > < pre > < span > < / span > < code > < span class = nt > apiVersion< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > networking.k8s.io/v1< / span >
< span class = nt > kind< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > Ingress< / span >
2021-01-11 15:59:14 +00:00
< span class = nt > metadata< / span > < span class = p > :< / span >
2023-10-12 19:31:18 +00:00
< span class = w > < / span > < span class = nt > name< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > test-ingress-2< / span >
< span class = w > < / span > < span class = nt > annotations< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > nginx.ingress.kubernetes.io/rewrite-target< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > /$1< / span >
2021-01-11 15:59:14 +00:00
< span class = nt > spec< / span > < span class = p > :< / span >
2023-10-12 19:31:18 +00:00
< span class = w > < / span > < span class = nt > ingressClassName< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > nginx< / span >
< span class = w > < / span > < span class = nt > rules< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = "p p-Indicator" > -< / span > < span class = w > < / span > < span class = nt > host< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > test.com< / span >
< span class = w > < / span > < span class = nt > http< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > paths< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = "p p-Indicator" > -< / span > < span class = w > < / span > < span class = nt > path< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > /foo/bar/(.+)< / span >
< span class = w > < / span > < span class = nt > pathType< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > ImplementationSpecific< / span >
< span class = w > < / span > < span class = nt > backend< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > service< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > name< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > service3< / span >
< span class = w > < / span > < span class = nt > port< / span > < span class = p > :< / span > < span class = w > < / span >
< span class = w > < / span > < span class = nt > number< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > 80< / span >
2021-01-11 15:59:14 +00:00
< / code > < / pre > < / div > < p > The ingress controller would define the following location blocks, in order of descending length, within the NGINX template for the < code > test.com< / code > server:< / p > < div class = highlight > < pre > < span > < / span > < code > location ~* ^/foo/bar/.+ {
2020-04-15 17:09:38 +00:00
...
}
2018-10-01 19:44:22 +00:00
2020-04-15 17:09:38 +00:00
location ~* " ^/foo/bar/" {
...
}
2018-10-01 19:44:22 +00:00
2020-04-15 17:09:38 +00:00
location ~* " ^/foo/bar" {
...
}
2023-10-12 19:31:18 +00:00
< / code > < / pre > < / div > < p > The following request URI's would match the corresponding location blocks:< / p > < ul > < li > < code > test.com/foo/bar/1< / code > matches < code > ~* ^/foo/bar/.+< / code > and will go to service 3.< / li > < li > < code > test.com/foo/bar/< / code > matches < code > ~* ^/foo/bar/< / code > and will go to service 2.< / li > < li > < code > test.com/foo/bar< / code > matches < code > ~* ^/foo/bar< / code > and will go to service 1.< / li > < / ul > < p > < strong > IMPORTANT NOTES< / strong > :< / p > < ul > < li > If the < code > use-regex< / code > OR < code > rewrite-target< / code > annotation is used on any Ingress for a given host, then the case insensitive regular expression < a href = https://nginx.org/en/docs/http/ngx_http_core_module.html#location > location modifier< / a > will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.< / li > < / ul > < h2 id = warning > Warning< a class = headerlink href = #warning title = "Permanent link" > ¶< / a > < / h2 > < p > The following example describes a case that may inflict unwanted path matching behavior.< / p > < p > This case is expected and a result of NGINX's a first match policy for paths that use the regular expression < a href = https://nginx.org/en/docs/http/ngx_http_core_module.html#location > location modifier< / a > . For more information about how a path is chosen, please read the following article: < a href = https://www.digitalocean.com/community/tutorials/understanding-nginx-server-and-location-block-selection-algorithms > "Understanding Nginx Server and Location Block Selection Algorithms"< / a > .< / p > < h3 id = example_1 > Example< a class = headerlink href = #example_1 title = "Permanent link" > ¶< / a > < / h3 > < p > Let the following ingress be defined:< / p > < div class = highlight > < pre > < span > < / span > < code > < span class = nt > apiVersion< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > networking.k8s.io/v1< / span >
< span class = nt > kind< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > Ingress< / span >
2021-01-11 15:59:14 +00:00
< span class = nt > metadata< / span > < span class = p > :< / span >
2023-10-12 19:31:18 +00:00
< span class = w > < / span > < span class = nt > name< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > test-ingress-3< / span >
< span class = w > < / span > < span class = nt > annotations< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > nginx.ingress.kubernetes.io/use-regex< / span > < span class = p > :< / span > < span class = w > < / span > < span class = s > " true" < / span >
2021-01-11 15:59:14 +00:00
< span class = nt > spec< / span > < span class = p > :< / span >
2023-10-12 19:31:18 +00:00
< span class = w > < / span > < span class = nt > ingressClassName< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > nginx< / span >
< span class = w > < / span > < span class = nt > rules< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = "p p-Indicator" > -< / span > < span class = w > < / span > < span class = nt > host< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > test.com< / span >
< span class = w > < / span > < span class = nt > http< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > paths< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = "p p-Indicator" > -< / span > < span class = w > < / span > < span class = nt > path< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > /foo/bar/bar< / span >
< span class = w > < / span > < span class = nt > pathType< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > Prefix< / span >
< span class = w > < / span > < span class = nt > backend< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > service< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > name< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > test< / span >
< span class = w > < / span > < span class = nt > port< / span > < span class = p > :< / span > < span class = w > < / span >
< span class = w > < / span > < span class = nt > number< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > 80< / span >
< span class = w > < / span > < span class = "p p-Indicator" > -< / span > < span class = w > < / span > < span class = nt > path< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > /foo/bar/[A-Z0-9]{3}< / span >
< span class = w > < / span > < span class = nt > pathType< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > ImplementationSpecific< / span >
< span class = w > < / span > < span class = nt > backend< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > service< / span > < span class = p > :< / span >
< span class = w > < / span > < span class = nt > name< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > test< / span >
< span class = w > < / span > < span class = nt > port< / span > < span class = p > :< / span > < span class = w > < / span >
< span class = w > < / span > < span class = nt > number< / span > < span class = p > :< / span > < span class = w > < / span > < span class = "l l-Scalar l-Scalar-Plain" > 80< / span >
2021-01-11 15:59:14 +00:00
< / code > < / pre > < / div > < p > The ingress controller would define the following location blocks (in this order) within the NGINX template for the < code > test.com< / code > server:< / p > < div class = highlight > < pre > < span > < / span > < code > location ~* " ^/foo/bar/[A-Z0-9]{3}" {
2020-04-15 17:09:38 +00:00
...
}
2018-10-01 19:44:22 +00:00
2020-04-15 17:09:38 +00:00
location ~* " ^/foo/bar/bar" {
...
}
2023-10-12 19:31:18 +00:00
< / code > < / pre > < / div > < p > A request to < code > test.com/foo/bar/bar< / code > would match the < code > ^/foo/bar/[A-Z0-9]{3}< / code > location block instead of the longest EXACT matching path.< / p > < / article > < / div > < / div > < / main > < footer class = md-footer > < div class = "md-footer-meta md-typeset" > < div class = "md-footer-meta__inner md-grid" > < div class = md-copyright > Made with < a href = https://squidfunk.github.io/mkdocs-material/ target = _blank rel = noopener > Material for MkDocs < / a > < / div > < / div > < / div > < / footer > < / div > < div class = md-dialog data-md-component = dialog > < div class = "md-dialog__inner md-typeset" > < / div > < / div > < script id = __config type = application/json > { "base" : "../.." , "features" : [ "navigation.tabs" , "navigation.tabs.sticky" , "navigation.instant" , "navigation.sections" ] , "search" : "../../assets/javascripts/workers/search.f886a092.min.js" , "translations" : { "clipboard.copied" : "Copied to clipboard" , "clipboard.copy" : "Copy to clipboard" , "search.result.more.one" : "1 more on this page" , "search.result.more.other" : "# more on this page" , "search.result.none" : "No matching documents" , "search.result.one" : "1 matching document" , "search.result.other" : "# matching documents" , "search.result.placeholder" : "Type to start searching" , "search.result.term.missing" : "Missing" , "select.version" : "Select version" } } < / script > < script src = ../../assets/javascripts/bundle.aecac24b.min.js > < / script > < / body > < / html >
