Add path-regex annotation for ingress (#4127)

docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md

@@ -112,6 +112,7 @@ The table below summarizes the available annotations.
 |``nginx.org/proxy-buffer-size`` | ``proxy-buffer-size`` | Sets the value of the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) and [grpc_buffer_size](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size) directives. | Depends on the platform. |  |
 |``nginx.org/proxy-max-temp-file-size`` | ``proxy-max-temp-file-size`` | Sets the value of the  [proxy_max_temp_file_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size) directive. | ``1024m`` |  |
 |``nginx.org/server-tokens`` | ``server-tokens`` | Enables or disables the [server_tokens](https://nginx.org/en/docs/http/ngx_http_core_module.html#server_tokens) directive. Additionally, with the NGINX Plus, you can specify a custom string value, including the empty string value, which disables the emission of the “Server” field. | ``True`` |  |
+|``nginx.org/path-regex`` | N/A | Enables regular expression modifiers for [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) directive. You can specify one of these values: "case_sensitive", "case_insensitive" or "exact". The annotation is applied to the entire Ingress resource and its paths. |  |  [Path Regex](https://github.com/nginxinc/kubernetes-ingress/tree/examples/ingress-resources/path-regex). |
 {{% /table %}}
 
 ### Request URI/Header Manipulation

examples/ingress-resources/path-regex/README.md

@@ -0,0 +1,191 @@
+# Support for path regular expressions
+
+NGINX and NGINX Plus support regular expression modifiers for [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location)
+ directive.
+
+The NGINX Ingress Controller provides the following annotations for configuring regular expression support:
+
+- Optional: ```nginx.org/path-regex: "case_sensitive"``` - specifies a preceding regex modifier to be case sensitive (`~*`).
+- Optional: ```nginx.org/path-regex: "case_insensitive"``` - specifies a preceding regex modifier to be case sensitive (`~`).
+- Optional: ```nginx.org/path-regex: "exact"``` - specifies exact match preceding modifier (`=`).
+
+[NGINX documentation](https://docs.nginx.com/nginx/admin-guide/web-server/web-server/#nginx-location-priority) provides
+additional information about how NGINX and NGINX Plus resolve location priority.
+Read [it](https://docs.nginx.com/nginx/admin-guide/web-server/web-server/#nginx-location-priority) before using
+ the ``path-regex`` annotation.
+
+Nginx uses a specific syntax to decide which location block to use to handle a request.
+Location blocks live within server blocks (or other location blocks) and are used to decide how to process
+ the request URI, for example:
+
+```bash
+location optional_modifier location_match {
+  ...
+}
+```
+
+The ``location_match`` defines what NGINX checks the request URI against. The existence or nonexistence of the modifier
+ in the example affects the way that the Nginx attempts to match the location block.
+ The modifiers you can apply using the ``path-regex`` annotation will cause the associated location block
+  to be interpreted as follows:
+
+- **no modifier** : No modifiers (no annotation applied) - the location is interpreted as a prefix match.
+This means that the location given will be matched against the beginning of the request URI to determine a match
+
+- **~** : Tilde modifier (annotation value ``case_sensitive``) - the location is interpreted as a case-sensitive
+regular expression match
+
+- **~***: Tilde and asterisk modifier (annotation value ``case_insensitive``) - the location is interpreted
+as a case-insensitive regular expression match
+
+- **=** : Equal sign modifier (annotation value ``exact``) - the location is considered a match if the request
+ URI exactly matches the location provided.
+
+## Example 1: Case Sensitive RegEx
+
+In the following example you enable path regex annotation ``nginx.org/path-regex`` and set its value to `case_sensitive`.
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: cafe-ingress
+  annotations:
+    nginx.org/path-regex: "case_sensitive"
+spec:
+  tls:
+  - hosts:
+    - cafe.example.com
+    secretName: cafe-secret
+  rules:
+  - host: cafe.example.com
+    http:
+      paths:
+      - path: /tea/[A-Z0-9]
+        backend:
+          serviceName: tea-svc
+          servicePort: 80
+      - path: /coffee/[A-Z0-9]
+        backend:
+          serviceName: coffee-svc
+          servicePort: 80
+```
+
+Corresponding NGINX config file snippet:
+
+```bash
+...
+
+  location ~ "^/tea/[A-Z0-9]" {
+
+    set $service "tea-svc";
+    status_zone "tea-svc";
+
+...
+
+  location ~ "^/coffee/[A-Z0-9]" {
+
+    set $service "coffee-svc";
+    status_zone "coffee-svc";
+
+...
+```
+
+## Example 2: Case Insensitive RegEx
+
+In the following example you enable path regex annotation ``nginx.org/path-regex`` and set its value to `case_insensitive`.
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: cafe-ingress
+  annotations:
+    nginx.org/path-regex: "case_insensitive"
+spec:
+  tls:
+  - hosts:
+    - cafe.example.com
+    secretName: cafe-secret
+  rules:
+  - host: cafe.example.com
+    http:
+      paths:
+      - path: /tea/[A-Z0-9]
+        backend:
+          serviceName: tea-svc
+          servicePort: 80
+      - path: /coffee/[A-Z0-9]
+        backend:
+          serviceName: coffee-svc
+          servicePort: 80
+```
+
+Corresponding NGINX config file snippet:
+
+```bash
+...
+
+  location ~* "^/tea/[A-Z0-9]" {
+
+    set $service "tea-svc";
+    status_zone "tea-svc";
+
+...
+
+  location ~* "^/coffee/[A-Z0-9]" {
+
+    set $service "coffee-svc";
+    status_zone "coffee-svc";
+
+...
+```
+
+## Example 3: Exact RegEx
+
+In the following example you enable path regex annotation ``nginx.org/path-regex`` and set its value to `exact` match.
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: cafe-ingress
+  annotations:
+    nginx.org/path-regex: "exact"
+spec:
+  tls:
+  - hosts:
+    - cafe.example.com
+    secretName: cafe-secret
+  rules:
+  - host: cafe.example.com
+    http:
+      paths:
+      - path: /tea/
+        backend:
+          serviceName: tea-svc
+          servicePort: 80
+      - path: /coffee/
+        backend:
+          serviceName: coffee-svc
+          servicePort: 80
+```
+
+Corresponding NGINX config file snippet:
+
+```bash
+...
+
+  location = "/tea" {
+
+    set $service "tea-svc";
+    status_zone "tea-svc";
+
+...
+
+  location = "/coffee" {
+
+    set $service "coffee-svc";
+    status_zone "coffee-svc";
+...
+```

internal/configs/annotations.go

@@ -10,6 +10,9 @@ const JWTKeyAnnotation = "nginx.com/jwt-key"
 // BasicAuthSecretAnnotation is the annotation where the Secret with the HTTP basic user list
 const BasicAuthSecretAnnotation = "nginx.org/basic-auth-secret" // #nosec G101
 
+// PathRegexAnnotation is the annotation where the regex location (path) modifier is specified.
+const PathRegexAnnotation = "nginx.org/path-regex"
+
 // AppProtectPolicyAnnotation is where the NGINX App Protect policy is specified
 const AppProtectPolicyAnnotation = "appprotect.f5.com/app-protect-policy"
 
@@ -73,6 +76,12 @@ var minionInheritanceList = map[string]bool{
 	"nginx.org/fail-timeout":             true,
 }
 
+var validPathRegex = map[string]bool{
+	"case_sensitive":   true,
+	"case_insensitive": true,
+	"exact":            true,
+}
+
 func parseAnnotations(ingEx *IngressEx, baseCfgParams *ConfigParams, isPlus bool, hasAppProtect bool, hasAppProtectDos bool, enableInternalRoutes bool) ConfigParams {
 	cfgParams := *baseCfgParams
 
@@ -385,6 +394,13 @@ func parseAnnotations(ingEx *IngressEx, baseCfgParams *ConfigParams, isPlus bool
 			}
 		}
 	}
+
+	if pathRegex, exists := ingEx.Ingress.Annotations[PathRegexAnnotation]; exists {
+		_, ok := validPathRegex[pathRegex]
+		if !ok {
+			glog.Errorf("Ingress %s/%s: Invalid value nginx.org/path-regex: got %q. Allowed values: 'case_sensitive', 'case_insensitive', 'exact'", ingEx.Ingress.GetNamespace(), ingEx.Ingress.GetName(), pathRegex)
+		}
+	}
 	return cfgParams
 }
 

internal/configs/version1/nginx-plus.ingress.tmpl

@@ -177,7 +177,11 @@ server {
 	{{end -}}
 
 	{{range $location := $server.Locations}}
-	location {{$location.Path}} {
+	{{ if index $.Ingress.Annotations "nginx.org/path-regex" }}
+	location {{  makePathRegex $location.Path $.Ingress.Annotations | printf }} {
+	{{ else }}
+	location {{ $location.Path }} {
+	{{ end }}
 		set $service "{{$location.ServiceName}}";
 		status_zone "{{ $location.ServiceName }}";
 		{{with $location.MinionIngress}}

internal/configs/version1/nginx.ingress.tmpl

@@ -102,7 +102,11 @@ server {
 	{{- end}}
 
 	{{range $location := $server.Locations}}
-	location {{$location.Path}} {
+	{{ if index $.Ingress.Annotations "nginx.org/path-regex" }}
+	location {{  makePathRegex $location.Path $.Ingress.Annotations | printf }} {
+	{{ else }}
+	location {{ $location.Path }} {
+	{{ end }}
 		set $service "{{$location.ServiceName}}";
 		{{with $location.MinionIngress}}
 		# location for minion {{$location.MinionIngress.Namespace}}/{{$location.MinionIngress.Name}}

internal/configs/version1/template_helper.go

@@ -1,6 +1,7 @@
 package version1
 
 import (
+	"fmt"
 	"strings"
 	"text/template"
 )
@@ -13,7 +14,31 @@ func trim(s string) string {
 	return strings.TrimSpace(s)
 }
 
+// makePathRegex takes a string representing a location path
+// and a map representing Ingress annotations.
+// It returns a location path with added regular expression modifier.
+// See [Location Directive].
+//
+// [Location Directive]: https://nginx.org/en/docs/http/ngx_http_core_module.html#location
+func makePathRegex(path string, annotations map[string]string) string {
+	p, ok := annotations["nginx.org/path-regex"]
+	if !ok {
+		return path
+	}
+	switch p {
+	case "case_sensitive":
+		return fmt.Sprintf("~ \"^%s\"", path)
+	case "case_insensitive":
+		return fmt.Sprintf("~* \"^%s\"", path)
+	case "exact":
+		return fmt.Sprintf("= \"%s\"", path)
+	default:
+		return path
+	}
+}
+
 var helperFunctions = template.FuncMap{
-	"split": split,
-	"trim":  trim,
+	"split":         split,
+	"trim":          trim,
+	"makePathRegex": makePathRegex,
 }