Skip to content

Commit c029fd2

Browse files
bjee19bjee19
authored
NGF: Add Deploy data plane doc (#530)
Add "Deploy Data plane document" to guide users on how to create and modify the NGINX Data Plane. Problem: Users want a guide on how to create and modify the NGINX Data Plane. Solution: Added the guide.
1 parent 6644bf2 commit c029fd2

File tree

2 files changed

+248
-3
lines changed

2 files changed

+248
-3
lines changed

‎content/ngf/installation/installing-ngf/deploy-data-plane.md

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
---
2+
title: Deploy a Gateway for data plane instances
3+
weight: 500
4+
toc: true
5+
type: how-to
6+
product: NGF
7+
docs: DOCS-000
8+
---
9+
10+
## Overview
11+
12+
This document describes how to use a Gateway to deploy the NGINX data plane, and how to modify it using an NGINX custom resource.
13+
14+
[A Gateway](https://gateway-api.sigs.k8s.io/concepts/api-overview/#gateway) is used to manage all inbound requests, and is a key Gateway API resource.
15+
16+
When a Gateway is attached to a GatewayClass associated with NGINX Gateway Fabric, it creates a Service and an NGINX deployment. This forms the NGINX data plane, handling requests.
17+
18+
A single GatewayClass can have multiple Gateways: each Gateway will create a separate Service and NGINX deployment.
19+
20+
## Before you begin
21+
22+
- [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric.
23+
24+
## Create a Gateway
25+
26+
To deploy a Gateway, run the following command:
27+
28+
```yaml
29+
kubectl apply -f - <<EOF
30+
apiVersion: gateway.networking.k8s.io/v1
31+
kind: Gateway
32+
metadata:
33+
name: cafe
34+
spec:
35+
gatewayClassName: nginx
36+
listeners:
37+
- name: http
38+
port: 80
39+
protocol: HTTP
40+
EOF
41+
```
42+
43+
To check that the Gateway has deployed correctly, use `kubectl describe` to check its status:
44+
45+
```shell
46+
kubectl describe gateway
47+
```
48+
49+
You should see these conditions:
50+
51+
```text
52+
Conditions:
53+
Last Transition Time: 2025-05-05T23:49:33Z
54+
Message: Listener is accepted
55+
Observed Generation: 1
56+
Reason: Accepted
57+
Status: True
58+
Type: Accepted
59+
Last Transition Time: 2025-05-05T23:49:33Z
60+
Message: Listener is programmed
61+
Observed Generation: 1
62+
Reason: Programmed
63+
Status: True
64+
Type: Programmed
65+
Last Transition Time: 2025-05-05T23:49:33Z
66+
Message: All references are resolved
67+
Observed Generation: 1
68+
Reason: ResolvedRefs
69+
Status: True
70+
Type: ResolvedRefs
71+
Last Transition Time: 2025-05-05T23:49:33Z
72+
Message: No conflicts
73+
Observed Generation: 1
74+
Reason: NoConflicts
75+
Status: False
76+
Type: Conflicted
77+
```
78+
79+
Using `kubectl get` you can see the NGINX Deployment:
80+
81+
```shell
82+
kubectl get deployments
83+
```
84+
```text
85+
NAME READY UP-TO-DATE AVAILABLE AGE
86+
cafe-nginx 1/1 1 1 3m18s
87+
```
88+
89+
You can also see the Service fronting it:
90+
91+
```shell
92+
kubectl get services
93+
```
94+
```text
95+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
96+
cafe-nginx LoadBalancer 10.96.125.117 <pending> 80:30180/TCP 5m2s
97+
```
98+
99+
The Service type can be changed, as explained in the next section.
100+
101+
## How to modify provisioned NGINX instances
102+
103+
The NginxProxy custom resource can modify the provisioning of the Service object and NGINX deployment when a Gateway is created.
104+
105+
{{< note >}} Updating most Kubernetes related fields in NginxProxy will trigger a restart of the related resources. {{< /note >}}
106+
107+
An NginxProxy resource is created by default after deploying NGINX Gateway Fabric. This NginxProxy resource is attached to the GatewayClass (created on NGINX Gateway Fabric installation), and
108+
its settings are applied globally to all Gateways.
109+
110+
Use `kubectl get` and `kubectl describe` to get some more information on the resource:
111+
112+
```shell
113+
kubectl get nginxproxies -A
114+
```
115+
```text
116+
NAMESPACE NAME AGE
117+
nginx-gateway ngf-proxy-config 19h
118+
```
119+
120+
```shell
121+
kubectl describe nginxproxy -n nginx-gateway ngf-proxy-config
122+
```
123+
```text
124+
Name: ngf-proxy-config
125+
Namespace: nginx-gateway
126+
Labels: app.kubernetes.io/instance=ngf
127+
app.kubernetes.io/managed-by=Helm
128+
app.kubernetes.io/name=nginx-gateway-fabric
129+
app.kubernetes.io/version=edge
130+
helm.sh/chart=nginx-gateway-fabric-1.6.2
131+
Annotations: meta.helm.sh/release-name: ngf
132+
meta.helm.sh/release-namespace: nginx-gateway
133+
API Version: gateway.nginx.org/v1alpha2
134+
Kind: NginxProxy
135+
Metadata:
136+
Creation Timestamp: 2025-05-05T23:01:28Z
137+
Generation: 1
138+
Resource Version: 2245
139+
UID: b545aa9e-74f8-45c0-b472-f14d3cab936f
140+
Spec:
141+
Ip Family: dual
142+
Kubernetes:
143+
Deployment:
144+
Container:
145+
Image:
146+
Pull Policy: IfNotPresent
147+
Repository: nginx-gateway-fabric/nginx
148+
Tag: edge
149+
Replicas: 1
150+
Service:
151+
External Traffic Policy: Local
152+
Type: LoadBalancer
153+
Events: <none>
154+
```
155+
156+
From the information obtained with `kubectl describe` you can see the default settings for the provisioned NGINX Deployment and Service.
157+
Under `Spec.Kubernetes` you can see a few things:
158+
- The NGINX container image settings
159+
- How many NGINX Deployment replicas are specified
160+
- The type of Service and external traffic policy
161+
162+
{{< note >}} Depending on installation configuration, the default NginxProxy settings may be slightly different from what is shown in the example.
163+
For more information on NginxProxy and its configurable fields, see the [API reference]({{< ref "/ngf/reference/api.md" >}}). {{< /note >}}
164+
165+
Modify the NginxProxy resource to change the type of Service.
166+
167+
Use `kubectl edit` to modify the default NginxProxy and insert the following under `spec.kubernetes.service`:
168+
169+
```yaml
170+
type: NodePort
171+
```
172+
173+
After saving the changes, use `kubectl get` on the service, and you should see the service type has changed to `LoadBalancer`.
174+
175+
```shell
176+
kubectl get service cafe-nginx
177+
```
178+
```text
179+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
180+
cafe-nginx NodePort 10.96.172.204 <none> 80:32615/TCP 3h5m
181+
```
182+
183+
### How to set annotations and labels on provisioned resources
184+
185+
While the majority of configuration will happen on the NginxProxy resource, that is not always the case. Uniquely, if
186+
you want to set any annotations or labels on the NGINX Deployment or Service, you need to set those annotations on the Gateway which
187+
provisioned them.
188+
189+
You can use `kubectl edit` on the Gateway and add the following to the `spec`:
190+
191+
```yaml
192+
infrastructure:
193+
annotations:
194+
annotationKey: annotationValue
195+
labels:
196+
labelKey: labelValue
197+
```
198+
199+
After saving the changes, check the Service and NGINX deployment with `kubectl describe`.
200+
201+
```shell
202+
kubectl describe deployment cafe
203+
```
204+
```text
205+
Name: cafe-nginx
206+
Namespace: default
207+
CreationTimestamp: Mon, 05 May 2025 16:49:33 -0700
208+
...
209+
Pod Template:
210+
Labels: app.kubernetes.io/instance=ngf
211+
app.kubernetes.io/managed-by=ngf-nginx
212+
app.kubernetes.io/name=cafe-nginx
213+
gateway.networking.k8s.io/gateway-name=cafe
214+
labelKey=labelValue
215+
Annotations: annotationKey: annotationValue
216+
prometheus.io/port: 9113
217+
prometheus.io/scrape: true
218+
...
219+
```
220+
221+
```shell
222+
kubectl describe service cafe-nginx
223+
```
224+
```text
225+
Name: cafe-nginx
226+
Namespace: default
227+
Labels: app.kubernetes.io/instance=ngf
228+
app.kubernetes.io/managed-by=ngf-nginx
229+
app.kubernetes.io/name=cafe-nginx
230+
gateway.networking.k8s.io/gateway-name=cafe
231+
labelKey=labelValue
232+
Annotations: annotationKey: annotationValue
233+
```
234+
235+
## See also
236+
237+
For more guides on routing traffic to applications and more information on Data Plane configuration, check out the following resources:
238+
239+
- [Routing traffic to applications]({{< ref "/ngf/how-to/traffic-management/routing-traffic-to-your-app.md" >}})
240+
- [Application routes using HTTP matching conditions]({{< ref "/ngf/how-to/traffic-management/advanced-routing.md" >}})
241+
- [Data plane configuration]({{< ref "/ngf/how-to/data-plane-configuration.md" >}})
242+
- [API reference]({{< ref "/ngf/reference/api.md" >}})

‎content/ngf/installation/installing-ngf/manifests.md

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -97,11 +97,14 @@ Deploys NGINX Gateway Fabric with NGINX OSS.
9797
kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/default/deploy.yaml
9898
```
9999

100-
To set up an AWS Network Load Balancer service, add these annotations to your Gateway infrastructure fields:
100+
To set up an AWS Network Load Balancer service, add these annotations to your Gateway infrastructure field:
101101

102102
```yaml
103-
service.beta.kubernetes.io/aws-load-balancer-type: "external"
104-
service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: "ip"
103+
spec:
104+
infrastructure:
105+
annotations:
106+
service.beta.kubernetes.io/aws-load-balancer-type: "external"
107+
service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: "ip"
105108
```
106109
107110
{{% /tab %}}

0 commit comments

Comments
 (0)