Skip to content

Commit 5b3ac4f

Browse files
ADubhlaoichADubhlaoich
authored
Update documentation for style consistency (#2256)
This commit updates most of the documentation set to adhere to some contemporary documentation style standards: - Sentence case for titles and headings - Initial headings for how-to guides as "Overview" and "Before you begin" - Moving any frontmatter descriptions to the body of text - Removing unnecessary frontmatter data altogether - Removing unnecessary custom style tag (Incorporated into the theme by default) It also collapses a few single document directories (Adding an unnecessary "hop" for users) and re-orders some sections.
1 parent d76d8eb commit 5b3ac4f

38 files changed

+148
-159
lines changed

‎site/config/api/pkg.tpl

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,14 @@
11
{{ define "packages" }}
22
---
3-
title: "API Reference"
4-
description: "NGINX Gateway API Reference"
3+
title: "API reference"
54
weight: 100
65
toc: false
76
---
87

8+
## Overview
9+
10+
NGINX Gateway API Reference
11+
912
{{ with .packages}}
1013
<p>Packages:</p>
1114
<ul>

‎site/content/how-to/_index.md

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,4 @@
11
---
2-
title: "How-To Guides"
3-
description:
2+
title: "How-to guides"
43
weight: 300
5-
linkTitle: "Guides"
6-
menu:
7-
docs:
8-
parent: NGINX Gateway Fabric
94
---

‎site/content/how-to/configuration/_index.md

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎site/content/how-to/configuration/control-plane-configuration.md renamed to ‎site/content/how-to/control-plane-configuration.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
---
2-
title: "Control Plane Configuration"
3-
description: "Learn how to dynamically update the Gateway Fabric control plane configuration."
4-
weight: 100
2+
title: "Control plane configuration"
3+
weight: 300
54
toc: true
65
docs: "DOCS-1416"
76
---
87

8+
Learn how to dynamically update the Gateway Fabric control plane configuration.
9+
910
## Overview
1011

1112
NGINX Gateway Fabric can dynamically update the control plane configuration without restarting. The control plane configuration is stored in the NginxGateway custom resource, created during the installation of NGINX Gateway Fabric.

‎site/content/how-to/maintenance/_index.md

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎site/content/how-to/monitoring/_index.md

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,4 @@
11
---
2-
title: "Monitoring and Troubleshooting"
3-
description:
4-
weight: 400
5-
linkTitle: "Monitoring and Troubleshooting"
6-
menu:
7-
docs:
8-
parent: How-To Guides
2+
title: "Monitoring and troubleshooting"
3+
weight: 200
94
---

‎site/content/how-to/monitoring/dashboard.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,11 @@
11
---
2-
title: "NGINX Plus Dashboard"
3-
description: "Learn how to view the NGINX Plus dashboard to see real-time metrics."
2+
title: "NGINX Plus dashboard"
43
weight: 300
54
toc: true
65
docs: "DOCS-1417"
76
---
87

9-
{{<custom-styles>}}
8+
Learn how to view the NGINX Plus dashboard to see real-time metrics.
109

1110
## Overview
1211

‎site/content/how-to/monitoring/prometheus.md

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,14 @@
11
---
2-
title: "Prometheus Metrics"
3-
description: "This document describes how to monitor NGINX Gateway Fabric using Prometheus and Grafana. It explains installation and configuration, as well as what metrics are available."
2+
title: "Prometheus metrics"
43
weight: 100
54
toc: true
65
docs: "DOCS-1418"
76
---
87

9-
{{<custom-styles>}}
8+
This document describes how to monitor NGINX Gateway Fabric using Prometheus and Grafana. It explains installation and configuration, as well as what metrics are available.
109

1110
## Overview
1211

13-
1412
NGINX Gateway Fabric metrics are displayed in [Prometheus](https://prometheus.io/) format. These metrics are served through a metrics server orchestrated by the controller-runtime package on HTTP port `9113`. When installed, Prometheus automatically scrapes this port and collects metrics. [Grafana](https://grafana.com/) can be used for rich visualization of these metrics.
1513

1614
{{<call-out "important" "Security note for metrics">}}
@@ -98,7 +96,7 @@ Provided by the [controller-runtime](https://github.com/kubernetes-sigs/controll
9896
- Go runtime metrics such as the number of Go routines, garbage collection duration, and Go version.
9997
- Controller-specific metrics, including reconciliation errors per controller, length of the reconcile queue, and reconciliation latency.
10098

101-
## How to change the default metrics configuration
99+
## Change the default metrics configuration
102100

103101
You can configure monitoring metrics for NGINX Gateway Fabric using Helm or Manifests.
104102

‎site/content/how-to/monitoring/tracing.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ This guide explains how to enable tracing on HTTPRoutes using NGINX Gateway Fabr
1717
Tracing cannot be enabled for [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.
1818
{{< /important >}}
1919

20-
## Install the Collectors
20+
## Install the collectors
2121

2222
The first step is to install the collectors. NGINX Gateway Fabric will be configured to export to the OpenTelemetry Collector, which is configured to export to Jaeger. This model allows the visualization collector (Jaeger) to be swapped with something else, or to add more collectors without needing to reconfigure NGINX Gateway Fabric. It is also possible to configure NGINX Gateway Fabric to export directly to Jaeger.
2323

@@ -333,7 +333,7 @@ Select a trace to view the attributes.
333333

334334
The trace includes the attribute from the global NginxProxy resource as well as the attribute from the ObservabilityPolicy.
335335

336-
## Further Reading
336+
## Further reading
337337

338338
- [Custom policies]({{< relref "overview/custom-policies.md" >}}): learn about how NGINX Gateway Fabric custom policies work.
339339
- [API reference]({{< relref "reference/api.md" >}}): all configuration fields for the policies mentioned in this guide

‎site/content/how-to/monitoring/troubleshooting.md

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,8 @@ toc: true
55
docs: "DOCS-1419"
66
---
77

8-
{{< custom-styles >}}
9-
108
This topic describes possible issues when using NGINX Gateway Fabric and general troubleshooting techniques. When possible, suggested workarounds are provided.
119

12-
1310
### General troubleshooting
1411

1512
When investigating a problem or requesting help, there are important data points that can be collected to help understand what issues may exist.

‎site/content/how-to/traffic-management/_index.md

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,4 @@
11
---
2-
title: "Traffic Management"
3-
description:
4-
weight: 300
5-
linkTitle: "Traffic Management"
6-
menu:
7-
docs:
8-
parent: How-To Guides
2+
title: "Traffic management"
3+
weight: 100
94
---

‎site/content/how-to/traffic-management/advanced-routing.md

Lines changed: 16 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,23 @@
11
---
2-
title: "Routing to Applications Using HTTP Matching Conditions"
3-
description: "Learn how to deploy multiple applications and HTTPRoutes with request conditions such as paths, methods, headers, and query parameters"
2+
title: "Application routes using HTTP matching conditions"
43
weight: 200
54
toc: true
65
docs: "DOCS-1422"
76
---
87

8+
Learn how to deploy multiple applications and HTTPRoutes with request conditions such as paths, methods, headers, and query parameters
9+
10+
## Overview
11+
912
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, we recommend that you follow the [basic guide]({{< relref "/how-to/traffic-management/routing-traffic-to-your-app.md" >}}) first.
1013

1114
The following image shows the traffic flow that we will be creating with these rules.
1215

13-
{{<img src="img/advanced-routing.png" alt="Traffic Flow Diagram">}}
16+
{{<img src="img/advanced-routing.png" alt="">}}
1417

1518
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 directed to the old application, while traffic for v2 needs to be directed towards the new application. We also have two `tea` services, one that handles GET operations and one that handles POST operations. Both the `tea` and `coffee` applications share the same Gateway.
1619

17-
## Prerequisites
20+
## Before you begin
1821

1922
- [Install]({{< relref "/installation/" >}}) NGINX Gateway Fabric.
2023
- [Expose NGINX Gateway Fabric]({{< relref "installation/expose-nginx-gateway-fabric.md" >}}) and save the public IP
@@ -27,17 +30,17 @@ The goal is to create a set of rules that will result in client requests being s
2730

2831
{{< 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 >}}
2932

30-
## Coffee Applications
33+
## Coffee applications
3134

32-
### Deploy the Coffee Applications
35+
### Deploy the Coffee applications
3336

3437
Begin by deploying the `coffee-v1` and `coffee-v2` applications:
3538

3639
```shell
3740
kubectl apply -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/v1.3.0/examples/advanced-routing/coffee.yaml
3841
```
3942

40-
### Deploy the Gateway API Resources for the Coffee Applications
43+
### Deploy the Gateway API Resources for the Coffee applications
4144

4245
The [gateway](https://gateway-api.sigs.k8s.io/api-types/gateway/) resource is typically deployed by the [cluster operator](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#roles-and-personas_1). To deploy the gateway:
4346

@@ -111,7 +114,7 @@ This HTTPRoute has a few important properties:
111114

112115
If you want both conditions to be required, you can define headers and queryParams in the same match object.
113116

114-
### Send Traffic to Coffee
117+
### Send traffic to Coffee
115118

116119
Using the external IP address and port for NGINX Gateway Fabric, we can send traffic to our coffee applications.
117120

@@ -147,17 +150,17 @@ Server address: 10.244.0.9:8080
147150
Server name: coffee-v2-68bd55f798-s9z5q
148151
```
149152

150-
## Tea Applications
153+
## Tea applications
151154

152155
Let's deploy a different set of applications now called `tea` and `tea-post`. These applications will have their own set of rules, but will still attach to the same gateway listener as the `coffee` apps.
153156

154-
### Deploy the Tea Applications
157+
### Deploy the Tea applications
155158

156159
```shell
157160
kubectl apply -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/v1.3.0/examples/advanced-routing/tea.yaml
158161
```
159162

160-
### Deploy the HTTPRoute for the Tea Services
163+
### Deploy the HTTPRoute for the Tea services
161164

162165
We are reusing the previous gateway for these applications, so all we need to create is the HTTPRoute.
163166

@@ -199,7 +202,7 @@ The properties of this HTTPRoute include:
199202
- The first rule defines that a POST request to the `/tea` path is routed to the `tea-post` Service.
200203
- The second rule defines that a GET request to the `/tea` path is routed to the `tea` Service.
201204

202-
### Send Traffic to Tea
205+
### Send traffic to Tea
203206

204207
Using the external IP address and port for NGINX Gateway Fabric, we can send traffic to our tea applications.
205208

@@ -332,7 +335,7 @@ If you have any issues while sending traffic, try the following to debug your co
332335

333336
Check for any error messages in the conditions.
334337

335-
## Further Reading
338+
## Further reading
336339

337340
To learn more about the Gateway API and the resources we created in this guide, check out the following Kubernetes documentation resources:
338341

‎site/content/how-to/traffic-management/client-settings.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: "Client Settings Policy"
2+
title: "Client Settings Policy API"
33
weight: 800
44
toc: true
55
docs: "DOCS-000"
@@ -148,7 +148,6 @@ Events: <none>
148148

149149
Next, test that the policy is configured by sending a POST request to the coffee and tea applications exceeding the client's max body size of 50 bytes.
150150

151-
152151
```shell
153152
curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee -X POST --data "this payload is greater than fifty bytes by four bytes"
154153
```
@@ -279,7 +278,7 @@ spec:
279278
EOF
280279
```
281280

282-
## Further Reading
281+
## Further reading
283282

284283
- [Custom policies]({{< relref "overview/custom-policies.md" >}}): learn about how NGINX Gateway Fabric custom policies work.
285284
- [API reference]({{< relref "reference/api.md" >}}): all configuration fields for the `ClientSettingsPolicy` API.

‎site/content/how-to/traffic-management/https-termination.md

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,17 @@
11
---
2-
title: "HTTPS Termination"
3-
description: "Learn how to terminate HTTPS traffic using NGINX Gateway Fabric."
4-
weight: 500
2+
title: "HTTPS termination"
3+
weight: 600
54
toc: true
65
docs: "DOCS-1421"
76
---
87

8+
Learn how to terminate HTTPS traffic using NGINX Gateway Fabric.
9+
10+
## Overview
11+
912
In this guide, we will show how to configure HTTPS termination for your application, using an [HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/) redirect filter, secret, and [ReferenceGrant](https://gateway-api.sigs.k8s.io/api-types/referencegrant/).
1013

11-
## Prerequisites
14+
## Before you begin
1215

1316
- [Install]({{< relref "installation/" >}}) NGINX Gateway Fabric.
1417
- [Expose NGINX Gateway Fabric]({{< relref "installation/expose-nginx-gateway-fabric.md" >}}) and save the public IP address and port of NGINX Gateway Fabric into shell variables:
@@ -85,7 +88,7 @@ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
8588
service/coffee ClusterIP 10.96.189.37 <none> 80/TCP 40s
8689
```
8790

88-
## Configure HTTPS Termination and Routing
91+
## Configure HTTPS termination and routing
8992

9093
For the HTTPS, we need a certificate and key that are stored in a secret. This secret will live in a separate namespace, so we will need a ReferenceGrant in order to access it.
9194

@@ -238,7 +241,7 @@ Server address: 10.244.0.6:80
238241
Server name: coffee-6b8b6d6486-7fc78
239242
```
240243

241-
## Further Reading
244+
## Further reading
242245

243246
To learn more about redirects using the Gateway API, see the following resource:
244247

‎site/content/how-to/traffic-management/integrating-cert-manager.md

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,14 @@
11
---
2-
title: "Securing Traffic using Let's Encrypt and Cert-Manager"
3-
description: "Learn how to issue and mange certificates using Let's Encrypt and cert-manager."
2+
title: "Secure traffic using Let's Encrypt and cert-manager"
43
weight: 300
54
toc: true
65
docs: "DOCS-1425"
76
---
87

8+
Learn how to issue and mange certificates using Let's Encrypt and cert-manager.
9+
10+
## Overview
11+
912
Securing client server communication is a crucial part of modern application architectures. One of the most important steps in this process is implementing HTTPS (HTTP over TLS/SSL) for all communications. This encrypts the data transmitted between the client and server, preventing eavesdropping and tampering. To do this, you need an SSL/TLS certificate from a trusted Certificate Authority (CA). However, issuing and managing certificates can be a complicated manual process. Luckily, there are many services and tools available to simplify and automate certificate issuance and management.
1013

1114
Follow the steps in this guide to:
@@ -14,14 +17,14 @@ Follow the steps in this guide to:
1417
- Use [Let’s Encrypt](https://letsencrypt.org) as the Certificate Authority (CA) issuing the TLS certificate.
1518
- Use [cert-manager](https://cert-manager.io) to automate the provisioning and management of the certificate.
1619

17-
## Prerequisities
20+
## Before you begin
1821

1922
- Administrator access to a Kubernetes cluster.
2023
- [Helm](https://helm.sh) and [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) must be installed locally.
2124
- [NGINX Gateway Fabric deployed]({{< relref "/installation/" >}}) in the Kubernetes cluster.
2225
- A DNS-resolvable domain name is required. It must resolve to the public endpoint of the NGINX Gateway Fabric deployment, and this public endpoint must be an external IP address or alias accessible over the internet. The process here will depend on your DNS provider. This DNS name will need to be resolvable from the Let’s Encrypt servers, which may require that you wait for the record to propagate before it will work.
2326

24-
## Overview
27+
## Secure traffic using Let's Encrypt and cert-manage
2528

2629
{{<img src="img/cert-manager-gateway-workflow.png" alt="cert-manager ACME challenge and certificate management with Gateway API">}}
2730

@@ -37,7 +40,7 @@ At a high level, the process looks like this:
3740
1. When the client connects to `https://cafe.example.com/coffee`, the request is routed to the coffee-app application and the communication is secured using the signed keypair contained in the cafe-secret secret.
3841
1. The certificate will be automatically renewed when it is close to expiry, the secret will be updated using the new certificate, and NGINX Gateway Fabric will dynamically update the keypair on the filesystem used by NGINX for HTTPS termination once the secret is updated.
3942

40-
## Securing Traffic
43+
## Securing traffic
4144

4245
### Deploy cert-manager
4346

0 commit comments

Comments
 (0)