From 0727f6038ab5755d73a0211c978c7f31c933dbd1 Mon Sep 17 00:00:00 2001 From: Michael Pleshakov Date: Fri, 2 Oct 2020 14:00:20 -0700 Subject: [PATCH 1/2] Document how policies are applied and validated --- docs-web/configuration/policy-resource.md | 84 ++++++++++++++++++- ...server-and-virtualserverroute-resources.md | 4 +- 2 files changed, 85 insertions(+), 3 deletions(-) diff --git a/docs-web/configuration/policy-resource.md b/docs-web/configuration/policy-resource.md index 02ef727a05..0c1334dd0c 100644 --- a/docs-web/configuration/policy-resource.md +++ b/docs-web/configuration/policy-resource.md @@ -23,6 +23,8 @@ This document is the reference documentation for the Policy resource. An example - [IngressMTLS](#ingressmtls) - [IngressMTLS Merging Behavior](#ingressmtls-merging-behavior) - [Using Policy](#using-policy) + - [Applying Policies](#applying-policies) + - [Invalid Policies](#invalid-policies) - [Validation](#validation) - [Structural Validation](#structural-validation) - [Comprehensive Validation](#comprehensive-validation) @@ -283,7 +285,7 @@ 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. +If the conditions above are not met, NGINX will send the `500` status code to clients. You can pass the client certificate details, including the certificate, to the upstream servers. For example: ```yaml @@ -352,6 +354,86 @@ webapp-policy 27m For `kubectl get` and similar commands, you can also use the short name `pol` instead of `policy`. +### Applying Policies + +You can apply policies to both VirtualServer and VirtualServerRoute resources. For example: + * VirtualServer: + ```yaml + apiVersion: k8s.nginx.org/v1 + kind: VirtualServer + metadata: + name: cafe + namespace: cafe + spec: + host: cafe.example.com + tls: + secret: cafe-secret + policies: # spec policies + - policy1 + upstreams: + - name: coffee + service: coffee-svc + port: 80 + routes: + - path: /tea + policies: # route policies + - policy2 + route: tea/tea + - path: /coffee + policies: # route policies + - policy3 + action: + pass: coffee + ``` + + For VirtualServer, you can apply a policy: + - to all routes (spec policies) + - to a specific route (route policies) + + Route policies of the *same type* override spec policies. In the example above, if the type of the policies `policy-1` and `policy-3` is `accessControl`, then for requests to `cafe.example.com/coffee`, NGINX will apply `policy-3`. + + The overriding is enforced by NGINX: the spec policies are implemented in the `server` context of the config, the route policies -- the `location` context. As a result, the route policies of the same type win. + * VirtualServerRoute, which is referenced by the VirtualServer above: + ```yaml + apiVersion: k8s.nginx.org/v1 + kind: VirtualServerRoute + metadata: + name: tea + namespace: tea + spec: + host: cafe.example.com + upstreams: + - name: tea + service: tea-svc + port: 80 + subroutes: # subroute policies + - path: /tea + policies: + - policy4 + action: + pass: tea + ``` + + For VirtualServerRoute, you can apply a policy to a subroute (subroute policies). + + Subroute policies of the same type override spec policies. In the example above, if the type of the policies `policy-1` (in the VirtualServer) and `policy-4` is `accessControl`, then for requests to `cafe.example.com/tea`, NGINX will apply `policy-4`. As with the VirtualServer, the overriding is enforced by NGINX. + + Subroute policies always override route policies no matter the types. For example, the policy `policy-2` in the VirtualServer route will be ignored for the subroute `/tea`, because the subroute has its own policies (in our case, only one policy `policy4`). If the subroute didn't have any policies, then the `policy-2` would be applied. This overriding is enforced by the Ingress Controller -- the `location` context for the subroute will either have route policies or subroute policies, but not both. + +### Invalid Policies + +NGINX will treat a policy as invalid if one of the following conditions is met: +* The policy doesn't pass the [comprehensive validation](#comprehensive-validation). +* The policy isn't present in the cluster. +* The policy doesn't meet its type-specific requirements. For example, an `ingressMTLS` policy requires TLS termination enabled in the VirtualServer. + + +For an invalid policy, NGINX returns the 500 status code for client requests with the following rules: +* If a policy is referenced in a VirtualServer `route` or a VirtualServerRoute `subroute`, then NGINX will return the 500 status code for requests for the URIs of that route/subroute. +* If a policy is referenced in the VirtualServer `spec`, then NGINX will return the 500 status code for requests for all URIs of that VirtualServer. + +If a policy is invalid, the VirtualServer or VirtualServerRoute will have the [status](/nginx-ingress-controller/configuration/global-configuration/reporting-resources-status#virtualserver-and-virtualserverroute-resources) with the state `Warning` and the message explaining why the policy wasn't considered invalid. + ### Validation Two types of validation are available for the Policy resource: diff --git a/docs-web/configuration/virtualserver-and-virtualserverroute-resources.md b/docs-web/configuration/virtualserver-and-virtualserverroute-resources.md index ed7869324e..adb7de0f8d 100644 --- a/docs-web/configuration/virtualserver-and-virtualserverroute-resources.md +++ b/docs-web/configuration/virtualserver-and-virtualserverroute-resources.md @@ -218,7 +218,7 @@ The route defines rules for matching client requests to actions like passing a r - ``string`` - Yes * - ``policies`` - - A list of policies. The policies override the policies of the same type defined in the ``spec`` of the VirtualServer. The overriding is done by NGINX: the route policies are configured in the ``location`` context, which overrides the spec policies of the same type defined in the ``server`` context. + - A list of policies. The policies override the policies of the same type defined in the ``spec`` of the VirtualServer. See `Applying Policies `_ for more details. - `[]policy <#virtualserver-policy>`_ - No * - ``action`` @@ -351,7 +351,7 @@ action: - ``string`` - Yes * - ``policies`` - - A list of policies. The policies override *all* policies defined in the route of the VirtualServer that references this resource. This is done by the Ingress Controller: the route policies of the VirtualServer will not be present in the generated configuration. The policies also override the policies of the same type defined in the ``spec`` of the VirtualServer. This overriding is done by NGINX: the subroute policies are configured in the ``location`` context, which overrides the spec policies of the same type defined in the ``server`` context. + - A list of policies. The policies override *all* policies defined in the route of the VirtualServer that references this resource. The policies also override the policies of the same type defined in the ``spec`` of the VirtualServer. See `Applying Policies `_ for more details. - `[]policy <#virtualserver-policy>`_ - No * - ``action`` From 6bcd5ede32b9edcff345c1b3fdf0080f0ae5fd0f Mon Sep 17 00:00:00 2001 From: Michael Pleshakov Date: Tue, 6 Oct 2020 17:58:37 +0100 Subject: [PATCH 2/2] Update docs-web/configuration/policy-resource.md Co-authored-by: Jodie Putrino --- docs-web/configuration/policy-resource.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-web/configuration/policy-resource.md b/docs-web/configuration/policy-resource.md index 0c1334dd0c..c99db2c28c 100644 --- a/docs-web/configuration/policy-resource.md +++ b/docs-web/configuration/policy-resource.md @@ -392,7 +392,7 @@ You can apply policies to both VirtualServer and VirtualServerRoute resources. F Route policies of the *same type* override spec policies. In the example above, if the type of the policies `policy-1` and `policy-3` is `accessControl`, then for requests to `cafe.example.com/coffee`, NGINX will apply `policy-3`. - The overriding is enforced by NGINX: the spec policies are implemented in the `server` context of the config, the route policies -- the `location` context. As a result, the route policies of the same type win. + The overriding is enforced by NGINX: the spec policies are implemented in the `server` context of the config, and the route policies are implemented in the `location` context. As a result, the route policies of the same type win. * VirtualServerRoute, which is referenced by the VirtualServer above: ```yaml apiVersion: k8s.nginx.org/v1