-
Notifications
You must be signed in to change notification settings - Fork 118
Add overview of custom NGF policies #2088
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
5678025
Add overview of custom NGF policies
7296623
Change example policy names
c0b402c
Docs code review
kate-osborn ecb27e8
Add links
0ad4562
Update compat tables and fix link
80ab03c
Add future reading section to client settings doc
ae38235
Add future reading section to tracing doc
ca56fd6
Add period
kate-osborn File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,160 @@ | ||
| --- | ||
| 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 [Policy Attachment](https://gateway-api.sigs.k8s.io/reference/policy-attachment/) pattern, 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]({{<relref "/how-to/traffic-management/client-settings.md" >}}) | 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 | | ||
|
|
||
| {{</bootstrap-table>}} | ||
|
|
||
kate-osborn marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| {{< 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. It will be added 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="">}} | ||
|
|
||
| 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 allows settings to cascade down a hierarchy. The hierarchy for Gateway API resources looks like this: | ||
|
|
||
| {{<img src="img/hierarchy.png" alt="">}} | ||
|
|
||
| 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="">}} | ||
|
|
||
| There are three policies defined: | ||
|
|
||
| - `dev-policy` that targets the `dev` Gateway | ||
| - `baz-policy` that targets the `baz` HTTPRoute | ||
| - `foo-policy` that targets the `foo` HTTPRoute | ||
|
|
||
| The settings in `dev-policy` affect the `dev` Gateway and are inherited by all the HTTPRoutes attached to `dev`. | ||
| The `baz-policy` and `foo-policy` are attached to the `baz` and `foo` HTTPRoutes. Since HTTPRoutes are lower than Gateways in the hierarchy, the settings defined in them override those in the `dev` policy. | ||
| Since the `foo-policy` only defines the `retries` setting, it still inherits the `timeout` setting from `dev-policy`. | ||
| The `bar` HTTPRoute has no policy attached to it and inherits all the settings from `dev-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 | ||
| 1. 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 | ||
| ``` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.