|
| 1 | +--- |
| 2 | +title: "Custom Policies" |
| 3 | +weight: 600 |
| 4 | +toc: true |
| 5 | +docs: "DOCS-000" |
| 6 | +--- |
| 7 | + |
| 8 | +## Overview |
| 9 | + |
| 10 | +Custom policies are NGINX Gateway Fabric CRDs (Custom Resource Definitions) that allow users to configure NGINX data plane features that are unavailable in the Gateway API. |
| 11 | +These custom policies follow the Gateway API's pattern of [Policy Attachment](https://gateway-api.sigs.k8s.io/reference/policy-attachment/), which allows users to extend the Gateway API functionality by creating implementation-specific policies and attaching them to Kubernetes objects such as HTTPRoutes, Gateways, and Services. |
| 12 | + |
| 13 | +Policies are a Kubernetes object that augments the behavior of an object in a standard way. Policies can be attached to one object ([Direct Policy Attachment](#direct-policy-attachment)) or objects in a hierarchy ([Inherited Policy Attachment](#inherited-policy-attachment)). |
| 14 | +The following table summarizes NGINX Gateway Fabric custom policies: |
| 15 | + |
| 16 | +{{< bootstrap-table "table table-striped table-bordered" >}} |
| 17 | + |
| 18 | +| Policy | Description | Attachment Type | Supported Target Object(s) | Supports Multiple Target Refs | Mergeable | API Version | |
| 19 | +|----------------------------------------------------------------------|---------------------------------------------------------|-----------------|-------------------------------|-------------------------------|-----------|-------------| |
| 20 | +| ClientSettingsPolicy | Configure connection behavior between client and NGINX | Inherited | Gateway, HTTPRoute, GRPCRoute | No | Yes | v1alpha1 | |
| 21 | +| [ObservabilityPolicy]({{<relref "/how-to/monitoring/tracing.md" >}}) | Define settings related to tracing, metrics, or logging | Direct | HTTPRoute, GRPCRoute | Yes | No | v1alpha1 | |
| 22 | + |
| 23 | + |
| 24 | +{{< important >}} |
| 25 | +NGINX Gateway Fabric policies do not work with [HTTPRoute matches](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRouteMatch) with `headers`, `params`, or `method` matchers defined. This will be addressed in a future release. |
| 26 | +{{< /important >}} |
| 27 | + |
| 28 | +## Terminology |
| 29 | + |
| 30 | +- _Attachment Type_. How the policy attaches to an object. Attachment type can be "direct" or "inherited". |
| 31 | +- _Supported Target Object(s)_. API objects the policy can be applied to. |
| 32 | +- _Supports Multiple Target Refs_. Whether a single policy can target multiple objects. |
| 33 | +- _Mergeable_. Whether policies that target the same object can be merged. |
| 34 | + |
| 35 | +## Direct Policy Attachment |
| 36 | + |
| 37 | +A Direct Policy Attachment is a policy that references a single object -- such as a Gateway or HTTPRoute. It is tightly bound to one instance of a particular Kind within a single Namespace or an instance of a single Kind at the cluster-scope. It affects _only_ the object specified in its TargetRef. |
| 38 | + |
| 39 | +This diagram uses a fictional retry policy to show how Direct Policy Attachment works: |
| 40 | + |
| 41 | +{{<img src="img/direct-policy-attachment.png" alt="Direct Policy Attachment">}} |
| 42 | + |
| 43 | +The policy targets the HTTPRoute `baz` and sets `retries` to `3` and `timeout` to `60s`. Since this policy is a Direct Policy Attachment, its settings are only applied to the `baz` HTTPRoute. |
| 44 | + |
| 45 | +## Inherited Policy Attachment |
| 46 | + |
| 47 | +Inherited Policy Attachment is designed to allow settings to flow down a hierarchy. The hierarchy for Gateway API resources looks like this: |
| 48 | + |
| 49 | +{{<img src="img/hierarchy.png" alt="Hierarchy">}} |
| 50 | + |
| 51 | +Settings defined in a policy attached to an object in this hierarchy may be inherited by the resources below it. For example, the settings defined in a policy attached to a Gateway may be inherited by all the HTTPRoutes attached to that Gateway. |
| 52 | + |
| 53 | +Settings in an Inherited Policy can be Defaults or Overrides. Defaults set the default value for something and can be overridden by policies on a lower object. Overrides cannot be overridden by lower objects. |
| 54 | +All settings in NGINX Gateway Fabric Inherited Policies are Defaults. |
| 55 | + |
| 56 | +Default values are given precedence from the bottom up. Therefore, a policy setting attached to a Backend will have the highest precedence over the one attached to higher objects. |
| 57 | + |
| 58 | +The following diagram shows how Inherited Policies work in NGINX Gateway Fabric using a fictional retry policy: |
| 59 | + |
| 60 | +{{<img src="img/inherited-policy-attachment.png" alt="Inherited Policy Attachment">}} |
| 61 | + |
| 62 | +There are three policies defined: |
| 63 | + |
| 64 | +- Blue policy that targets the `dev` Gateway |
| 65 | +- Orange policy that targets the `baz` HTTPRoute |
| 66 | +- Pink policy that targets the `foo` HTTPRoute |
| 67 | + |
| 68 | +The settings in the blue policy affect the `dev` Gateway and are inherited by all the HTTPRoutes attached to `dev`. |
| 69 | +The orange and pink policies are attached to the `baz` and `foo` HTTPRoutes. Since HTTPRoutes are lower than Gateways in the hierarchy, the settings defined in the orange and pink policies override those in the blue policy. |
| 70 | +Since the pink policy only defines the `retries` setting, it still inherits the `timeout` setting from the blue policy. |
| 71 | +The `bar` HTTPRoute has no policy attached to it and inherits all the settings from the blue policy. |
| 72 | + |
| 73 | +## Merging Policies |
| 74 | + |
| 75 | +With some NGINX Gateway Fabric Policies, it is possible to create multiple policies that target the same resource as long as the fields in those policies do not conflict. |
| 76 | + |
| 77 | +For example, consider the following fictional policies: |
| 78 | + |
| 79 | +```yaml |
| 80 | +apiVersion: gateway.nginx.org/v1alpha1 |
| 81 | +kind: ExamplePolicy |
| 82 | +metadata: |
| 83 | + name: retries |
| 84 | +spec: |
| 85 | + targetRef: |
| 86 | + group: gateway.networking.k8s.io |
| 87 | + kind: HTTPRoute |
| 88 | + name: foo |
| 89 | + retries: 10 |
| 90 | +``` |
| 91 | +
|
| 92 | +
|
| 93 | +```yaml |
| 94 | +apiVersion: gateway.nginx.org/v1alpha1 |
| 95 | +kind: ExamplePolicy |
| 96 | +metadata: |
| 97 | + name: timeout |
| 98 | +spec: |
| 99 | + targetRef: |
| 100 | + kind: HTTPRoute |
| 101 | + name: foo |
| 102 | + timeout: 60s |
| 103 | +``` |
| 104 | +
|
| 105 | +The `retries` ExamplePolicy defines the number of retries for the `foo` HTTPRoute, and the `timeout` ExamplePolicy defines the timeout for the `foo` HTTPRoute. |
| 106 | +NGINX Gateway Fabric will merge the fields defined in the policies and apply the following settings to the `foo` HTTPRoute: |
| 107 | + |
| 108 | +```yaml |
| 109 | +retries: 10 |
| 110 | +timeout: 60s |
| 111 | +``` |
| 112 | + |
| 113 | +However, if both policies had the `retries` field set, then the policies cannot be merged. In this case, NGINX Gateway Fabric will choose which policy to configure based on the following criteria (continuing on ties): |
| 114 | + |
| 115 | +1. The oldest policy by creation timestamp |
| 116 | +2. The policy appearing first in alphabetical order by "{namespace}/{name}" |
| 117 | + |
| 118 | +If a policy conflicts with a configured policy, NGINX Gateway Fabric will set the policy `Accepted` status to false with a reason of `Conflicted`. See [Policy Status](#policy-status) for more details. |
| 119 | + |
| 120 | +## Policy Status |
| 121 | + |
| 122 | +NGINX Gateway Fabric sets the [PolicyStatus](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.PolicyStatus) on all policies. |
| 123 | + |
| 124 | +`PolicyStatus` fields: |
| 125 | + |
| 126 | +- `ancestors`: describes the status of a route with respect to the ancestor. |
| 127 | + - `ancestorRef`: the object that the policy targets in `spec.targetRef` |
| 128 | + - `controllerName`: the controller name of NGINX Gateway Fabric. |
| 129 | + - `conditions`: (Condition/Status/Reason): |
| 130 | + - `Accepted/True/Accepted`: the policy is accepted by the ancestor. |
| 131 | + - `Accepted/False/Invalid`: the policy is not accepted because it is semantically or syntactically invalid. |
| 132 | + - `Accepted/False/Conflicted`: the policy is not accepted because it conflicts with another policy. |
| 133 | + - `Accepted/False/TargetNotFound`: the policy is not accepted because it targets a resource that is invalid or does not exist. |
| 134 | + - `Accepted/False/NginxProxyNotSet`: the policy is not accepted because it relies on the NginxProxy configuration which is missing or invalid. |
| 135 | + |
| 136 | + |
| 137 | +To check the status of a policy, use `kubectl describe`. This example checks the status of the `foo` ObservabilityPolicy, which is accepted: |
| 138 | + |
| 139 | +```shell |
| 140 | +kubectl describe observabilitypolicies.gateway.nginx.org foo -n default |
| 141 | +``` |
| 142 | + |
| 143 | +```text |
| 144 | +Status: |
| 145 | + Ancestors: |
| 146 | + Ancestor Ref: |
| 147 | + Group: gateway.networking.k8s.io |
| 148 | + Kind: HTTPRoute |
| 149 | + Name: foo |
| 150 | + Namespace: default |
| 151 | + Conditions: |
| 152 | + Last Transition Time: 2024-05-23T18:13:03Z |
| 153 | + Message: Policy is accepted |
| 154 | + Observed Generation: 1 |
| 155 | + Reason: Accepted |
| 156 | + Status: True |
| 157 | + Type: Accepted |
| 158 | + Controller Name: gateway.nginx.org/nginx-gateway-controller |
| 159 | +``` |
0 commit comments