Add IngressMTLS policy support

deployments/helm-chart/crds/policy.yaml

@@ -56,7 +56,7 @@ spec:
                   items:
                     type: string
             ingressMTLS:
-              description: IngressMTLS defines an mTLS policy for the ingress side.
+              description: IngressMTLS defines an Ingress MTLS policy.
               type: object
               properties:
                 clientCertSecret:

docs-web/configuration/policy-resource.md

@@ -61,12 +61,12 @@ spec:
      - The rate limit policy controls the rate of processing requests per a defined key.
      - `rateLimit <#ratelimit>`_
      - No*
-   * - ``JWT``
+   * - ``jwt``
      - The JWT policy configures NGINX Plus to authenticate client requests using JSON Web Tokens.
      - `jwt <#jwt>`_
      - No*
-   * - ``IngressMTLS``
-     - The IngressMTLS policy controls client verification.
+   * - ``ingressMTLS``
+     - The IngressMTLS policy configures client certificate verification.
      - `ingressMTLS <#ingressmtls>`_
      - No*
 ```
@@ -252,16 +252,22 @@ In this example the Ingress Controller will use the configuration from the first
 
 ### IngressMTLS
 
-The IngressMTLS policy controls client validation.
+The IngressMTLS policy configures client certificate verification.
 
-For example, the following policy will verify a client using the CA certificate specified in the `ingress-mtls-secret`:
+For example, the following policy will verify a client certificate using the CA certificate specified in the `ingress-mtls-secret`:
 ```yaml
 ingressMTLS:
   clientCertSecret: ingress-mtls-secret
-  verifyClient: "on"
+  verifyClient: on
   verifyDepth: 1
 ```
 
+A VirtualServer that references an IngressMTLS policy must:
+* Enable [TLS termination](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/#virtualserver-tls).
+* Reference the policy in the VirtualServer [`spec`](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/#virtualserver-specification). It is not allowed to reference an IngressMTLS policy in a [`route `](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/#virtualserver-route) or in a VirtualServerRoute [`subroute`](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/#virtualserverroute-subroute).
+
+If the conditions above are not met, NGINX will send `500` error response to clients.
+
 > Note: The feature is implemented using the NGINX [ngx_http_ssl_module](https://nginx.org/en/docs/http/ngx_http_ssl_module.html).
 
 ```eval_rst
@@ -277,18 +283,18 @@ ingressMTLS:
      - ``string``
      - Yes
    * - ``verifyClient``
-     - Verification for the client. Possible values are ``on``, ``off``, ``optional``, ``optional_no_ca``
+     - Verification for the client. Possible values are ``on``, ``off``, ``optional``, ``optional_no_ca``. The default is ``on``.
      - ``string``
      - No
    * - ``verifyDepth``
-     - Sets the verification depth in the client certificates chain.
+     - Sets the verification depth in the client certificates chain. The default is ``1``.
      - ``int``
      - No
 ```
 
 #### IngressMTLS Merging Behavior
 
-A VirtualServer/VirtualServerRoute can reference multiple IngressMTLS policies. However, only one can be applied. Every subsequent reference will be ignored. For example, here we reference two policies:
+A VirtualServer can reference only a single IngressMTLS policy. Every subsequent reference will be ignored. For example, here we reference two policies:
 ```yaml
 policies:
 - name: ingress-mtls-policy-one

examples-of-custom-resources/ingress-mtls/README.md

@@ -11,7 +11,7 @@ In this example, we deploy a web application, configure load balancing for it vi
     ```
 1. Save the HTTP port of the Ingress Controller into a shell variable:
     ```
-    $ IC_HTTP_PORTS=<port number>
+    $ IC_HTTPS_PORT=<port number>
     ```
 
 ## Step 1 - Deploy a Web Application

examples-of-custom-resources/ingress-mtls/ingress-mtls.yaml

@@ -5,5 +5,5 @@ metadata:
 spec:
   ingressMTLS:
     clientCertSecret: ingress-mtls-secret
-    verifyClient: "on"
+    verifyClient: on
     verifyDepth: 1

internal/configs/virtualserver.go

@@ -16,9 +16,14 @@ import (
 	conf_v1 "github.com/nginxinc/kubernetes-ingress/pkg/apis/configuration/v1"
 )
 
-const nginx502Server = "unix:/var/lib/nginx/nginx-502-server.sock"
-const internalLocationPrefix = "internal_location_"
-const nginx418Server = "unix:/var/lib/nginx/nginx-418-server.sock"
+const (
+	nginx502Server         = "unix:/var/lib/nginx/nginx-502-server.sock"
+	internalLocationPrefix = "internal_location_"
+	nginx418Server         = "unix:/var/lib/nginx/nginx-418-server.sock"
+	specContext            = "spec"
+	routeContext           = "route"
+	subRouteContext        = "subroute"
+)
 
 var incompatibleLBMethodsForSlowStart = map[string]bool{
 	"random":                          true,
@@ -213,7 +218,7 @@ func (vsc *virtualServerConfigurator) GenerateVirtualServerConfig(vsEx *VirtualS
 	vsc.clearWarnings()
 
 	policiesCfg := vsc.generatePolicies(vsEx.VirtualServer, vsEx.VirtualServer.Namespace, vsEx.VirtualServer.Namespace,
-		vsEx.VirtualServer.Name, vsEx.VirtualServer.Spec.Policies, vsEx.Policies, jwtKeys, ingressMTLSPemFileName, "server", tlsPemFileName)
+		vsEx.VirtualServer.Name, vsEx.VirtualServer.Spec.Policies, vsEx.Policies, jwtKeys, ingressMTLSPemFileName, specContext, tlsPemFileName)
 
 	// crUpstreams maps an UpstreamName to its conf_v1.Upstream as they are generated
 	// necessary for generateLocation to know what Upstream each Location references
@@ -320,7 +325,7 @@ func (vsc *virtualServerConfigurator) GenerateVirtualServerConfig(vsEx *VirtualS
 		vsLocSnippets := r.LocationSnippets
 		// ingressMTLSPemFileName argument is always empty for route policies
 		routePoliciesCfg := vsc.generatePolicies(vsEx.VirtualServer, vsEx.VirtualServer.Namespace, vsEx.VirtualServer.Namespace, vsEx.VirtualServer.Name,
-			r.Policies, vsEx.Policies, jwtKeys, "", "route", tlsPemFileName)
+			r.Policies, vsEx.Policies, jwtKeys, "", routeContext, tlsPemFileName)
 		limitReqZones = append(limitReqZones, routePoliciesCfg.LimitReqZones...)
 
 		if len(r.Matches) > 0 {
@@ -382,11 +387,11 @@ func (vsc *virtualServerConfigurator) GenerateVirtualServerConfig(vsEx *VirtualS
 			}
 			// ingressMTLSPemFileName argument is always empty for route policies
 			routePoliciesCfg := vsc.generatePolicies(vsr, vsr.Namespace, vsEx.VirtualServer.Namespace, vsEx.VirtualServer.Name,
-				r.Policies, vsEx.Policies, jwtKeys, "", "route", tlsPemFileName)
+				r.Policies, vsEx.Policies, jwtKeys, "", subRouteContext, tlsPemFileName)
 			// use the VirtualServer route policies if the route does not define any
 			if len(r.Policies) == 0 {
 				routePoliciesCfg = vsc.generatePolicies(vsEx.VirtualServer, vsEx.VirtualServer.Namespace, vsEx.VirtualServer.Namespace,
-					vsEx.VirtualServer.Name, vsrPoliciesFromVs[vsrNamespaceName], vsEx.Policies, jwtKeys, "", "route", tlsPemFileName)
+					vsEx.VirtualServer.Name, vsrPoliciesFromVs[vsrNamespaceName], vsEx.Policies, jwtKeys, "", subRouteContext, tlsPemFileName)
 			}
 			limitReqZones = append(limitReqZones, routePoliciesCfg.LimitReqZones...)
 
@@ -550,7 +555,7 @@ func (vsc *virtualServerConfigurator) generatePolicies(owner runtime.Object, own
 					policyError = true
 					break
 				}
-				if context != "server" {
+				if context != specContext {
 					vsc.addWarningf(owner, `IngressMTLS policy is not allowed in the %v context`, context)
 					policyError = true
 					break

internal/configs/virtualserver_test.go

@@ -1999,7 +1999,7 @@ func TestGeneratePolicies(t *testing.T) {
 				},
 			},
 			jwtKeys: nil,
-			context: "server",
+			context: "spec",
 			expected: policiesCfg{
 				IngressMTLS: &version2.IngressMTLS{
 					ClientCert:   ingressMTLSCertPath,
@@ -2268,7 +2268,7 @@ func TestGeneratePoliciesFails(t *testing.T) {
 				},
 			},
 			jwtKeys:        nil,
-			context:        "server",
+			context:        "spec",
 			tlsPemFileName: "/etc/nginx/secrets/default-tls-secret",
 			expected: policiesCfg{
 				ErrorReturn: &version2.Return{
@@ -2310,7 +2310,7 @@ func TestGeneratePoliciesFails(t *testing.T) {
 				},
 			},
 			jwtKeys:             nil,
-			context:             "server",
+			context:             "spec",
 			ingressMTLSFileName: "/etc/nginx/secrets/default-ingress-mtls-secret",
 			tlsPemFileName:      "/etc/nginx/secrets/default-tls-secret",
 			expected: policiesCfg{