Skip to content

Commit fa0da61

Browse files
bjee19bjee19
committed
Add deploy data plane doc
1 parent 6644bf2 commit fa0da61

File tree

1 file changed

+244
-0
lines changed

1 file changed

+244
-0
lines changed

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

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

0 commit comments

Comments
 (0)