Add overview of custom NGF policies

nginxinc · Jun 4, 2024 · 5af1dec · 5af1dec
1 parent 212c0f6
commit 5af1dec
Show file tree

Hide file tree

Showing 5 changed files with 164 additions and 4 deletions.
diff --git a/site/content/overview/custom-policies.md b/site/content/overview/custom-policies.md
@@ -0,0 +1,159 @@
+---
+title: "Custom Policies"
+weight: 600
+toc: true
+docs: "DOCS-000"
+---
+
+## Overview
+
+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.
+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.
+
+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)).
+The following table summarizes NGINX Gateway Fabric custom policies:
+
+{{< bootstrap-table "table table-striped table-bordered" >}}
+
+| Policy                                                               | Description                                             | Attachment Type | Supported Target Object(s)    | Supports Multiple Target Refs | Mergeable | API Version |
+|----------------------------------------------------------------------|---------------------------------------------------------|-----------------|-------------------------------|-------------------------------|-----------|-------------|
+| ClientSettingsPolicy                                                 | Configure connection behavior between client and NGINX  | Inherited       | Gateway, HTTPRoute, GRPCRoute | No                            | Yes       | v1alpha1    |
+| [ObservabilityPolicy]({{<relref "/how-to/monitoring/tracing.md" >}}) | Define settings related to tracing, metrics, or logging | Direct          | HTTPRoute, GRPCRoute          | Yes                           | No        | v1alpha1    |
+
+
+{{< important >}}
+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.
+{{< /important >}}
+
+## Terminology
+
+- _Attachment Type_. How the policy attaches to an object. Attachment type can be "direct" or "inherited".
+- _Supported Target Object(s)_. API objects the policy can be applied to.
+- _Supports Multiple Target Refs_. Whether a single policy can target multiple objects.
+- _Mergeable_. Whether policies that target the same object can be merged.
+
+## Direct Policy Attachment
+
+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.
+
+This diagram uses a fictional retry policy to show how Direct Policy Attachment works:
+
+{{<img src="img/direct-policy-attachment.png" alt="Direct Policy Attachment">}}
+
+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.
+
+## Inherited Policy Attachment
+
+Inherited Policy Attachment is designed to allow settings to flow down a hierarchy. The hierarchy for Gateway API resources looks like this:
+
+{{<img src="img/hierarchy.png" alt="Hierarchy">}}
+
+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.
+
+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.
+All settings in NGINX Gateway Fabric Inherited Policies are Defaults.
+
+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.
+
+The following diagram shows how Inherited Policies work in NGINX Gateway Fabric using a fictional retry policy:
+
+{{<img src="img/inherited-policy-attachment.png" alt="Inherited Policy Attachment">}}
+
+There are three policies defined:
+
+- Blue policy that targets the `dev` Gateway
+- Orange policy that targets the `baz` HTTPRoute
+- Pink policy that targets the `foo` HTTPRoute
+
+The settings in the blue policy affect the `dev` Gateway and are inherited by all the HTTPRoutes attached to `dev`.
+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.
+Since the pink policy only defines the `retries` setting, it still inherits the `timeout` setting from the blue policy.
+The `bar` HTTPRoute has no policy attached to it and inherits all the settings from the blue policy.
+
+## Merging Policies
+
+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.
+
+For example, consider the following fictional policies:
+
+```yaml
+apiVersion: gateway.nginx.org/v1alpha1
+kind: ExamplePolicy
+metadata:
+  name: retries
+spec:
+  targetRef:
+    group: gateway.networking.k8s.io
+    kind: HTTPRoute
+    name: foo
+  retries: 10
+```
+
+
+```yaml
+apiVersion: gateway.nginx.org/v1alpha1
+kind: ExamplePolicy
+metadata:
+  name: timeout
+spec:
+  targetRef:
+    kind: HTTPRoute
+    name: foo
+  timeout: 60s
+```
+
+The `retries` ExamplePolicy defines the number of retries for the `foo` HTTPRoute, and the `timeout` ExamplePolicy defines the timeout for the `foo` HTTPRoute.
+NGINX Gateway Fabric will merge the fields defined in the policies and apply the following settings to the `foo` HTTPRoute:
+
+```yaml
+retries: 10
+timeout: 60s
+```
+
+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):
+
+1. The oldest policy by creation timestamp
+2. The policy appearing first in alphabetical order by "{namespace}/{name}"
+
+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.
+
+## Policy Status
+
+NGINX Gateway Fabric sets the [PolicyStatus](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.PolicyStatus) on all policies.
+
+`PolicyStatus` fields:
+
+- `ancestors`: describes the status of a route with respect to the ancestor.
+  - `ancestorRef`: the object that the policy targets in `spec.targetRef`
+  - `controllerName`: the controller name of NGINX Gateway Fabric.
+  - `conditions`: (Condition/Status/Reason):
+    - `Accepted/True/Accepted`: the policy is accepted by the ancestor.
+    - `Accepted/False/Invalid`: the policy is not accepted because it is semantically or syntactically invalid.
+    - `Accepted/False/Conflicted`: the policy is not accepted because it conflicts with another policy.
+    - `Accepted/False/TargetNotFound`: the policy is not accepted because it targets a resource that is invalid or does not exist.
+    - `Accepted/False/NginxProxyNotSet`: the policy is not accepted because it relies on the NginxProxy configuration which is missing or invalid.
+
+
+To check the status of a policy, use `kubectl describe`. This example checks the status of the `foo` ObservabilityPolicy, which is accepted:
+
+```shell
+kubectl describe observabilitypolicies.gateway.nginx.org foo -n default
+```
+
+```text
+Status:
+  Ancestors:
+    Ancestor Ref:
+      Group:      gateway.networking.k8s.io
+      Kind:       HTTPRoute
+      Name:       foo
+      Namespace:  default
+    Conditions:
+      Last Transition Time:  2024-05-23T18:13:03Z
+      Message:               Policy is accepted
+      Observed Generation:   1
+      Reason:                Accepted
+      Status:                True
+      Type:                  Accepted
+    Controller Name:         gateway.nginx.org/nginx-gateway-controller
+```
diff --git a/site/content/overview/gateway-api-compatibility.md b/site/content/overview/gateway-api-compatibility.md
@@ -20,7 +20,7 @@ docs: "DOCS-1412"
 | [TCPRoute](#tcproute)                 | Not supported       | Not supported          | Not supported                         | N/A         |
 | [UDPRoute](#udproute)                 | Not supported       | Not supported          | Not supported                         | N/A         |
 | [BackendTLSPolicy](#backendtlspolicy) | Supported           | Supported              | Not supported                         | v1alpha3    |
-| [Custom policies](#custom-policies)   | Not supported       | N/A                    | Not supported                         | N/A         |
+| [Custom policies](#custom-policies)   | N/A                 | N/A                    | Supported                             | N/A         |
 {{< /bootstrap-table >}}
 
 ---
@@ -315,9 +315,10 @@ Fields:
 {{< bootstrap-table "table table-striped table-bordered" >}}
 | Resource        | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version |
 | --------------- | ------------------ | ---------------------- | ------------------------------------- | ----------- |
-| Custom policies | Not supported      | N/A                    | Not supported                         | N/A         |
+| Custom policies | N/A                | N/A                    | Supported                             | N/A         |
 {{< /bootstrap-table >}}
 
-Custom policies will be NGINX Gateway Fabric-specific CRDs (Custom Resource Definitions) that will support features such as timeouts, load-balancing methods, authentication, etc. These important data-plane features are not part of the Gateway API specifications.
-
+Custom policies are NGINX Gateway Fabric-specific CRDs (Custom Resource Definitions) that support features such as tracing, and client connection settings. These important data-plane features are not part of the Gateway API specifications.
 While these CRDs are not part of the Gateway API, the mechanism to attach them to Gateway API resources is part of the Gateway API. See the [Policy Attachment documentation](https://gateway-api.sigs.k8s.io/references/policy-attachment/).
+
+See the [custom policies]({{< relref "overview/custom-policies.md" >}}) document for more information.
diff --git a/site/static/img/direct-policy-attachment.png b/site/static/img/direct-policy-attachment.png
diff --git a/site/static/img/hierarchy.png b/site/static/img/hierarchy.png
diff --git a/site/static/img/inherited-policy-attachment.png b/site/static/img/inherited-policy-attachment.png