diff --git a/examples/snippets-filter/README.md b/examples/snippets-filter/README.md index c523ec2c3..bd5865616 100644 --- a/examples/snippets-filter/README.md +++ b/examples/snippets-filter/README.md @@ -1,3 +1,3 @@ # SnippetsFilter -This directory contains the YAML files used in the [SnippetsFilter](https://docs.nginx.com/nginx-gateway-fabric/how-to/traffic-management/snippets-filters/) guide. +This directory contains the YAML files used in the [Use the SnippetsFilter API](https://docs.nginx.com/nginx-gateway-fabric/how-to/traffic-management/snippets-filters/) guide. diff --git a/site/content/how-to/traffic-management/snippets-filters.md b/site/content/how-to/traffic-management/snippets-filters.md index e0aa8ec25..b4fd0aa51 100644 --- a/site/content/how-to/traffic-management/snippets-filters.md +++ b/site/content/how-to/traffic-management/snippets-filters.md @@ -1,11 +1,13 @@ --- -title: "Snippets Filters" +title: "Use the SnippetsFilter API" weight: 800 toc: true docs: "DOCS-000" --- -Learn how to use Snippets with the `SnippetsFilter` API. +This topic introduces Snippets and how to implement them using the `SnippetsFilter` API. It provides an example of how to use a Snippet for rate limiting, and how to investigate errors caused by misconfiguration. + +--- ## Overview @@ -15,6 +17,8 @@ NGINX configurations that NGINX Gateway Fabric generates. Snippets are for advanced NGINX users who need more control over the generated NGINX configuration, and can be used in cases where Gateway API resources or NGINX extensions don't apply. +--- + ## Disadvantages of Snippets Snippets are configured using the `SnippetsFilter` API, but are disabled by default due to their complexity and security implications. @@ -23,11 +27,11 @@ To use Snippets, set the `nginxGateway.snippetsFilters.enable` command line argu Snippets have the following disadvantages: -- *Complexity*. Snippets require you to: - - Understand NGINX Configuration primitives and implement a correct NGINX configuration. +- _Complexity_. Snippets require you to: + - Understand NGINX configuration primitives to implement correct NGINX configuration. - Understand how NGINX Gateway Fabric generates NGINX configuration so that a Snippet doesn’t interfere with the other features in the configuration. -- *Decreased robustness*. An incorrect Snippet can invalidate NGINX configuration, causing reload failures. Until the snippet is fixed, it will prevent any new configuration updates, including updates for the other Gateway resources. -- *Security implications*. Snippets give access to NGINX configuration primitives, which are not validated by NGINX Gateway Fabric. For example, a Snippet can configure NGINX to serve the TLS certificates and keys used for TLS termination for Gateway resources. +- _Decreased robustness_. An incorrect Snippet can invalidate NGINX configuration, causing reload failures. Until the snippet is fixed, it will prevent any new configuration updates, including updates for the other Gateway resources. +- _Security implications_. Snippets give access to NGINX configuration primitives, which are not validated by NGINX Gateway Fabric. For example, a Snippet can configure NGINX to serve the TLS certificates and keys used for TLS termination for Gateway resources. {{< note >}} If the NGINX configuration includes an invalid Snippet, NGINX will continue to operate with the last valid configuration. {{< /note >}} @@ -47,7 +51,7 @@ Due to the described disadvantages of Snippets, we recommend exhausting all othe GW_PORT= ``` - {{< note >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for.{{< /note >}} + {{< note >}} In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for. {{< /note >}} - Create the coffee and tea example applications: @@ -77,7 +81,7 @@ Due to the described disadvantages of Snippets, we recommend exhausting all othe curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee ``` - Send a request to tea + Send a request to tea: ```shell curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea @@ -95,7 +99,7 @@ Due to the described disadvantages of Snippets, we recommend exhausting all othe ``` - Lets check out our HTTPRoutes to see what's causing this error: + Use `kubectl describe` to investigate HTTPRoutes for the error: ```shell kubectl describe httproutes.gateway.networking.k8s.io @@ -135,13 +139,15 @@ Due to the described disadvantages of Snippets, we recommend exhausting all othe Type: ResolvedRefs ``` - This is because in the HTTPRoutes we created earlier, they both reference `SnippetsFilter` resources that do not currently - exist, and thus a 500 error code response will be returned on requests that are processed by these HTTPRoutes. - We will solve this in the next section when we add SnippetsFilters. + The HTTPRoutes created earlier both reference `SnippetsFilter` resources that do not currently + exist, creating a 500 error code response returned on requests that are processed by these HTTPRoutes. + This issue will be resolved using SnippetsFilters. + +--- ## Configure rate limiting to the coffee application -Lets configure rate limiting to our coffee application by adding the following `SnippetsFilter`: +Configure rate limiting to the coffee application by adding the following `SnippetsFilter`: ```yaml kubectl apply -f - <