nginx · sjberman · Nov 29, 2023 · Nov 2, 2023 · Nov 6, 2023 · Nov 6, 2023
diff --git a/docs/developer/branching-and-workflow.md → docs-developer/branching-and-workflow.md b/docs/developer/branching-and-workflow.md → docs-developer/branching-and-workflow.md
diff --git a/docs/developer/design-principles.md → docs-developer/design-principles.md b/docs/developer/design-principles.md → docs-developer/design-principles.md
diff --git a/docs/developer/go-style-guide.md → docs-developer/go-style-guide.md b/docs/developer/go-style-guide.md → docs-developer/go-style-guide.md
diff --git a/docs/developer/implementing-a-feature.md → docs-developer/implementing-a-feature.md b/docs/developer/implementing-a-feature.md → docs-developer/implementing-a-feature.md
diff --git a/docs/developer/logging-guidelines.md → docs-developer/logging-guidelines.md b/docs/developer/logging-guidelines.md → docs-developer/logging-guidelines.md
diff --git a/docs/developer/pull-request.md → docs-developer/pull-request.md b/docs/developer/pull-request.md → docs-developer/pull-request.md
diff --git a/docs/developer/quickstart.md → docs-developer/quickstart.md b/docs/developer/quickstart.md → docs-developer/quickstart.md
diff --git a/docs/developer/release-process.md → docs-developer/release-process.md b/docs/developer/release-process.md → docs-developer/release-process.md
diff --git a/docs/developer/testing.md → docs-developer/testing.md b/docs/developer/testing.md → docs-developer/testing.md
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,3 @@
+public
+.hugo_build.lock
+resources
diff --git a/docs/config/_default/config.toml b/docs/config/_default/config.toml
@@ -0,0 +1,68 @@
+title = "NGINX Gateway Fabric"
+enableGitInfo = false
+baseURL = "/"
+publishDir = "public/nginx-gateway-fabric"
+staticDir = ["static"]
+languageCode = "en-us"
+description = "NGINX Gateway Fabric."
+refLinksErrorLevel = "ERROR"
+enableRobotsTXT = "true"
+#canonifyURLs = true
+pluralizeListTitles = false
+pygmentsCodeFences = true
+pygmentsUseClasses = true
+
+[caches]
+  [caches.modules]
+    maxAge = -1
+
+[module]
+[[module.imports]]
+  path="github.com/nginxinc/nginx-hugo-theme"
+
+[markup]
+  [markup.highlight]
+    codeFences = true
+    guessSyntax = true
+    hl_Lines = ""
+    lineNoStart = 1
+    lineNos = false
+    lineNumbersInTable = true
+    noClasses = true
+    style = "monokai"
+    tabWidth = 4
+  [markup.goldmark]
+    [markup.goldmark.extensions]
+      definitionList = true
+      footnote = true
+      linkify = true
+      strikethrough = true
+      table = true
+      taskList = true
+      typographer = true
+    [markup.goldmark.parser]
+      attribute = true
+      autoHeadingID = true
+      autoHeadingIDType = "gitlab"
+    [markup.goldmark.renderer]
+      hardWraps = false
+      unsafe = true
+      xhtml = false
+
+[params]
+  useSectionPageLists = "false"
+  buildtype = "webdocs"
+  RSSLink = "/index.xml"
+  author = "NGINX Inc." # add your company name
+  github = "nginxinc" # add your github profile name
+  twitter = "@nginx" # add your twitter profile
+  #email = ""
+  noindex_kinds = [
+    "taxonomy",
+    "taxonomyTerm"
+  ]
+  logo = "NGINX-product-icon.svg"
+
+sectionPagesMenu = "docs"
+
+ignoreFiles = [ "\\.sh$", "\\.DS_Store$", "\\.git.*$", "\\.txt$", "\\/config\\/.*", "README\\.*"]
diff --git a/docs/config/development/config.toml b/docs/config/development/config.toml
@@ -0,0 +1,4 @@
+baseURL = "https://docs-dev.nginx.com/nginx-gateway-fabric"
+title = "DEV -- NGINX Gateway Fabric"
+publishDir = "public/nginx-gateway-fabric"
+canonifyURLs = false
diff --git a/docs/config/production/config.toml b/docs/config/production/config.toml
@@ -0,0 +1,4 @@
+baseURL = "https://docs.nginx.com/nginx-gateway-fabric"
+title = "NGINX Gateway Fabric"
+publishDir = "public/nginx-gateway-fabric"
+canonifyURLs = false
diff --git a/docs/config/staging/config.toml b/docs/config/staging/config.toml
@@ -0,0 +1,4 @@
+baseURL = "https://docs-staging.nginx.com/nginx-gateway-fabric"
+title = "STAGING -- NGINX Gateway Fabric"
+publishDir = "public/nginx-gateway-fabric"
+canonifyURLs = false
diff --git a/docs/README.md → docs/content/README.md b/docs/README.md → docs/content/README.md
diff --git a/docs/content/_index.md b/docs/content/_index.md
@@ -0,0 +1,6 @@
+---
+title: "Welcome to the NGINX Gateway Fabric documentation"
+description: 
+linkTitle: "NGINX Gateway Fabric"
+menu: docs
+---
diff --git a/docs/architecture.md → docs/content/architecture.md b/docs/architecture.md → docs/content/architecture.md
diff --git a/docs/building-the-images.md → docs/content/building-the-images.md b/docs/building-the-images.md → docs/content/building-the-images.md
diff --git a/docs/cli-help.md → docs/content/cli-help.md b/docs/cli-help.md → docs/content/cli-help.md
diff --git a/docs/control-plane-configuration.md → docs/content/control-plane-configuration.md b/docs/control-plane-configuration.md → docs/content/control-plane-configuration.md
diff --git a/docs/gateway-api-compatibility.md → docs/content/gateway-api-compatibility.md b/docs/gateway-api-compatibility.md → docs/content/gateway-api-compatibility.md
diff --git a/docs/guides/README.md → docs/content/guides/README.md b/docs/guides/README.md → docs/content/guides/README.md
diff --git a/docs/content/guides/_index.md b/docs/content/guides/_index.md
@@ -0,0 +1,8 @@
+---
+title: "Guides"
+description: 
+linkTitle: "Guides"
+menu: 
+  docs:
+    parent: NGINX Gateway Fabric
+---
diff --git a/docs/guides/advanced-routing.md → docs/content/guides/advanced-routing.md b/docs/guides/advanced-routing.md → docs/content/guides/advanced-routing.md
@@ -1,12 +1,18 @@
-# Routing to Applications Using HTTP Matching Conditions
+---
+title: "Routing to Applications Using HTTP Matching Conditions"
+description: "Learn how to deploy multiple applications and HTTPRoutes with request conditions such as paths, methods, headers, and query parameters"
+weight: 100
+toc: true
+docs: "DOCS-000"
+---
 
 In this guide we will configure advanced routing rules for multiple applications. These rules will showcase request
 matching by path, headers, query parameters, and method. For an introduction to exposing your application, it is
-recommended to go through the [basic guide](/docs/guides/routing-traffic-to-your-app.md) first.
+recommended to go through the [basic guide]({{< relref "/guides/routing-traffic-to-your-app.md" >}}) first.
 
 The following image shows the traffic flow that we will be creating with these rules.
 
-![Traffic Flow Diagram](/docs/images/advanced-routing.png)
+![Traffic Flow Diagram](/img/advanced-routing.png)
 
 The goal is to create a set of rules that will result in client requests being sent to specific backends based on
 the request attributes. In this diagram, we have two versions of the `coffee` service. Traffic for v1 needs to be
@@ -16,18 +22,16 @@ and `coffee` applications share the same Gateway.
 
 ## Prerequisites
 
-- [Install](/docs/installation.md) NGINX Gateway Fabric.
-- [Expose NGINX Gateway Fabric](/docs/installation.md#expose-nginx-gateway-fabric) and save the public IP
+- [Install]({{< relref "/installation.md" >}}) NGINX Gateway Fabric.
+- [Expose NGINX Gateway Fabric]({{< relref "/installation.md#expose-nginx-gateway-fabric" >}}) and save the public IP
   address and port of NGINX Gateway Fabric into shell variables:
 
    ```text
    GW_IP=XXX.YYY.ZZZ.III
    GW_PORT=<port number>
    ```
 
-> **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 >}}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 >}}
 
 ## Coffee Applications
 
@@ -42,7 +46,7 @@ kubectl apply -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric
 ### Deploy the Gateway API Resources for the Coffee Applications
 
 The [Gateway](https://gateway-api.sigs.k8s.io/api-types/gateway/) resource is typically deployed by the
-[cluster operator][roles-and-personas]. To deploy the Gateway:
+[cluster operator](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#roles-and-personas_1). To deploy the Gateway:
 
 ```yaml
 kubectl apply -f - <<EOF
@@ -62,7 +66,7 @@ EOF
 This Gateway defines a single listener on port 80. Since no hostname is specified, this listener matches on all hostnames.
 
 The [HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/) is typically deployed by the
-[application developer][roles-and-personas]. To deploy the `coffee` HTTPRoute:
+[application developer](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#roles-and-personas_1). To deploy the `coffee` HTTPRoute:
 
 ```yaml
 kubectl apply -f - <<EOF
@@ -116,16 +120,12 @@ the `coffee-v2` Service:
   - Request with the path prefix `/coffee` and the query parameter `TEST=v2`
     If you want both conditions to be required, you can define headers and queryParams in the same match object.
 
-[roles-and-personas]: https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#roles-and-personas_1
-
 ### Send Traffic to Coffee
 
 Using the external IP address and port for NGINX Gateway Fabric, we can send traffic to our coffee
 applications.
 
-> **Note**
-> If you have a DNS record allocated for `cafe.example.com`, you can send the request directly to that
-> hostname, without needing to resolve.
+{{< note >}}If you have a DNS record allocated for `cafe.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /note >}}
 
 ```shell
 curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee
@@ -216,9 +216,7 @@ The properties of this HTTPRoute include:
 Using the external IP address and port for NGINX Gateway Fabric, we can send traffic to our tea
 applications.
 
-> **Note**
-> If you have a DNS record allocated for `cafe.example.com`, you can send the request directly to that
-> hostname, without needing to resolve.
+{{< note >}}If you have a DNS record allocated for `cafe.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /note >}}
 
 ```shell
 curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea
@@ -352,7 +350,7 @@ If you have any issues while sending traffic, try the following to debug your co
 
 ## Further Reading
 
-To learn more about the Gateway API and the resources we created in this guide, check out the following resources:
+To learn more about the Gateway API and the resources we created in this guide, check out the following Kubernetes documentation resources:
 
 - [Gateway API Overview](https://gateway-api.sigs.k8s.io/concepts/api-overview/)
 - [Deploying a simple Gateway](https://gateway-api.sigs.k8s.io/guides/simple-gateway/)

diff --git a/docs/guides/integrating-cert-manager.md → ...ontent/guides/integrating-cert-manager.md b/docs/guides/integrating-cert-manager.md → ...ontent/guides/integrating-cert-manager.md
diff --git a/docs/guides/routing-traffic-to-your-app.md → ...ent/guides/routing-traffic-to-your-app.md b/docs/guides/routing-traffic-to-your-app.md → ...ent/guides/routing-traffic-to-your-app.md
diff --git a/docs/guides/upgrade-apps-without-downtime.md → ...t/guides/upgrade-apps-without-downtime.md b/docs/guides/upgrade-apps-without-downtime.md → ...t/guides/upgrade-apps-without-downtime.md
diff --git a/docs/installation.md → docs/content/installation.md b/docs/installation.md → docs/content/installation.md
diff --git a/docs/monitoring.md → docs/content/monitoring.md b/docs/monitoring.md → docs/content/monitoring.md
diff --git a/docs/proposals/README.md → docs/content/proposals/README.md b/docs/proposals/README.md → docs/content/proposals/README.md
diff --git a/docs/proposals/control-plane-config.md → ...content/proposals/control-plane-config.md b/docs/proposals/control-plane-config.md → ...content/proposals/control-plane-config.md
diff --git a/docs/content/proposals/data-plane-config.md b/docs/content/proposals/data-plane-config.md
@@ -0,0 +1,136 @@
+# Enhancement Proposal-929: Data Plane Configuration
+
+- Issue: https://github.com/nginxinc/nginx-kubernetes-gateway/issues/929
+- Status: Implementable
+
+## Summary
+
+This proposal is intended to contain the design for how to configure global settings for the data plane
+of the NGINX Gateway Fabric (NGF) product. Similar to control plane configuration, we should be able to leverage
+a custom resource definition to define data plane configuration, considering fields such as telemetry and
+upstream zone size.
+
+## Goals
+
+Define a CRD to configure various global settings for the NGF data plane. The initial configurable
+options will be for telemetry (tracing) and upstream zone size.
+
+## Non-Goals
+
+ 1. This proposal is not defining every setting that needs to be present in the configuration.
+ 2. This proposal is not for any configuration related to control plane.
+
+## Introduction
+
+The NGF data plane will evolve to have various user-configurable options. These could include, but are not
+limited to, tracing, logging, or metrics. For the best user experience, these options should be able to be
+changed at runtime, to avoid having to restart NGF. The first set of options that we will allow users to
+configure are tracing and upstream zone size. The easiest and most intuitive way to implement a Kubernetes-native
+API is through a CRD.
+
+The purpose of this CRD is to contain "global" configuration options for the data plane, and not focused on policy
+per route or backend.
+
+NGF will reload NGINX when configuration changes are made.
+
+In this doc, the term "user" will refer to the cluster operator (the person who installs and manages NGF). The
+cluster operator owns this CRD resource.
+
+## API, Customer Driven Interfaces, and User Experience
+
+The API would be provided in a CRD. An authorized user would interact with this CRD using `kubectl` to `get`
+or `edit` the configuration.
+
+Proposed configuration CRD example:
+
+```yaml
+apiVersion: gateway.nginx.org/v1alpha1
+kind: NginxProxy
+metadata:
+    name: nginx-proxy-config
+    namespace: nginx-gateway
+spec:
+    http:
+        upstreamZoneSize: 512k # default
+        telemetry:
+            tracing:
+                enabled: true # default false
+                endpoint: my-otel-collector.svc:4317 # required
+                interval: 5s # default
+                batchSize: 512 # default
+                batchCount: 4 # default
+status:
+    conditions:
+    ...
+```
+
+- The CRD would be Namespace-scoped.
+- CRD is initialized and created when NGF is deployed, in the `nginx-gateway` Namespace.
+- CRD would be referenced in the [ParametersReference][ref] of the NGF GatewayClass.
+- Conditions include `Accepted` if the CRD config is valid, and `Programmed` to determine if an nginx
+reload was successful.
+
+[ref]:https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.ParametersReference
+
+## Use Cases
+
+The high level use case is to configure options in the NGF data plane that are not currently configurable. The
+CRD also allows for these to change without the need to restart the NGF Pod.
+
+### Tracing
+
+Users may want to observe how traffic is flowing through their applications. Tracing is a great way to achieve
+this. By taking advantage of the OpenTelemetry standards, a user can deploy any OTLP-compliant tracing collector
+to receive and visualize tracing data. Allowing a user to configure a tracing backend for NGF will forward
+nginx tracing data to that backend for visualization.
+
+For future considerations, a user may want to disable tracing for certain routes (or only enable it for certain
+routes), in order to reduce the amount of data being collected. We would likely be able to implement a [per-route
+Policy](https://gateway-api.sigs.k8s.io/geps/gep-713/#direct-policy-attachment)
+that would include this switch. The proposed "global" CRD in this document would remain unchanged, though
+could include an additional field to enable or disable tracing globally.
+
+### Upstream Zone Size
+
+As the number of servers within an upstream increases (in other words, Pod replicas for a Service), the
+shared memory zone size needs to increase to accomodate this. A user can fine-tune this number to fit their
+environment.
+
+## Testing
+
+Unit tests can be leveraged for verifying that NGF properly watches and acts on CRD changes. These tests would
+be similar in behavior as the current unit tests that verify the control plane CRD resource processing.
+
+We would need system level tests to ensure that tracing works as expected.
+
+## Security Considerations
+
+We need to ensure that any configurable fields that are exposed to a user are:
+
+- Properly validated. This means that the fields should be the correct type (integer, string, etc.), have appropriate
+length, and use regex patterns or enums to prevent any unwanted input. This will initially be done through
+OpenAPI schema validation. If necessary as the CRD evolves, CEL or control plane validation could be used.
+- Have a valid use case. The more fields we expose, the more attack vectors we create. We should only be exposing
+fields that are genuinely useful for a user to change dynamically.
+
+RBAC via the Kubernetes API server will ensure that only authorized users can update the CRD containing NGF data
+plane configuration.
+
+## Alternatives
+
+- ConfigMap
+A ConfigMap is another type of resource that a user can provide configuration options within, however it lacks the
+benefits of a CRD, specifically built-in schema validation, versioning, and conversion webhooks.
+
+- Custom API server
+The NGF control plane could implement its own custom API server. However the overhead of implementing this, which
+would include auth, validation, endpoints, and so on, would not be worth it due to the fact that the Kubernetes
+API server already does all of these things for us.
+
+- Policies CRD for granular control
+Being that these are global settings, a user may have a need for more granular control, in other words, changing
+the settings at a per-route or per-backend basis. A new Policy CRD could accomplish this in future work.
+
+## References
+
+- [Kubernetes Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
diff --git a/docs/proposals/template.md → docs/content/proposals/template.md b/docs/proposals/template.md → docs/content/proposals/template.md
diff --git a/docs/resource-validation.md → docs/content/resource-validation.md b/docs/resource-validation.md → docs/content/resource-validation.md
diff --git a/docs/running-on-kind.md → docs/content/running-on-kind.md b/docs/running-on-kind.md → docs/content/running-on-kind.md
diff --git a/docs/troubleshooting.md → docs/content/troubleshooting.md b/docs/troubleshooting.md → docs/content/troubleshooting.md
diff --git a/docs/go.mod b/docs/go.mod
@@ -0,0 +1,5 @@
+module github.com/nginxinc/nalb-shared/docs
+
+go 1.18
+
+require github.com/nginxinc/nginx-hugo-theme v0.39.0 // indirect
diff --git a/docs/go.sum b/docs/go.sum
@@ -0,0 +1,4 @@
+github.com/nginxinc/nginx-hugo-theme v0.35.0 h1:7XB2GMy6qeJgKEJy9wOS3SYKYpfvLW3/H+UHRPLM4FU=
+github.com/nginxinc/nginx-hugo-theme v0.35.0/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M=
+github.com/nginxinc/nginx-hugo-theme v0.39.0 h1:P1hOPpityVUOM5OyIpQZa1UJyuUunGSmz0oZh/GYSJM=
+github.com/nginxinc/nginx-hugo-theme v0.39.0/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M=