Skip to content

Commit 4c391ca

Browse files
sjbermansjberman
committed
NGF: add control plane/data plane TLS doc
With the control plane and data plane split in NGF, a secure connection is necessary for communication between the two entities. We secure this by default, but for production environments, users should use an official solution to secure this communication channel. This doc describes how to do that.
1 parent b15d47e commit 4c391ca

File tree

4 files changed

+199
-0
lines changed

4 files changed

+199
-0
lines changed

‎content/ngf/how-to/traffic-security/integrating-cert-manager.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ Follow the steps in this guide to:
2323

2424
## Before you begin
2525

26+
You need:
27+
2628
- Administrator access to a Kubernetes cluster.
2729
- [Helm](https://helm.sh) and [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) must be installed locally.
2830
- [NGINX Gateway Fabric deployed]({{< ref "/ngf/installation/" >}}) in the Kubernetes cluster.

‎content/ngf/installation/installing-ngf/control-plane-certs.md

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
---
2+
title: Control Plane and Data Plane Authentication
3+
weight: 300
4+
toc: true
5+
type: how-to
6+
product: NGF
7+
docs: DOCS-0000
8+
---
9+
10+
## Overview
11+
12+
By default, NGINX Gateway Fabric installs self-signed certificates to secure the connection between the NGINX Gateway Fabric control plane and the NGINX data plane Pods. These certificates are created by a `cert-generator` Job when NGINX Gateway Fabric is first installed. However, because these certificates are self-signed and will expire after 3 years, it is recommended to use a solution such as [cert-manager](https://cert-manager.io) to create and manage these certificates in a production environment.
13+
14+
This guide will step through how to install and use `cert-manager` to secure this connection. **This should be done _before_ you install NGINX Gateway Fabric.**
15+
16+
## Before you begin
17+
18+
You need:
19+
20+
- Administrator access to a Kubernetes cluster.
21+
- [Helm](https://helm.sh) and [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) must be installed locally.
22+
23+
## Install cert-manager
24+
25+
- Add the Helm repository.
26+
27+
```shell
28+
helm repo add jetstack https://charts.jetstack.io
29+
helm repo update
30+
```
31+
32+
- Install cert-manager:
33+
34+
```shell
35+
helm install \
36+
cert-manager jetstack/cert-manager \
37+
--namespace cert-manager \
38+
--create-namespace \
39+
--set config.apiVersion="controller.config.cert-manager.io/v1alpha1" \
40+
--set config.kind="ControllerConfiguration" \
41+
--set config.enableGatewayAPI=true \
42+
--set crds.enabled=true
43+
```
44+
45+
This also enables Gateway API features for cert-manager, which can be useful for [securing your workload traffic]({{< ref "/ngf/how-to/traffic-security/integrating-cert-manager.md" >}}).
46+
47+
## Create CA Issuer
48+
49+
The first step is to create the CA Issuer.
50+
51+
{{< note >}} This example uses a self-signed Issuer, which should not be used in production environments. For production environments, you should use a real [CA issuer](https://cert-manager.io/docs/configuration/ca/). {{< /note >}}
52+
53+
Create the namespace:
54+
55+
```shell
56+
kubectl create namespace nginx-gateway
57+
```
58+
59+
```yaml
60+
kubectl apply -f - <<EOF
61+
apiVersion: cert-manager.io/v1
62+
kind: Issuer
63+
metadata:
64+
name: selfsigned-issuer
65+
namespace: nginx-gateway
66+
spec:
67+
selfSigned: {}
68+
---
69+
apiVersion: cert-manager.io/v1
70+
kind: Certificate
71+
metadata:
72+
name: nginx-gateway-ca
73+
namespace: nginx-gateway
74+
spec:
75+
isCA: true
76+
commonName: nginx-gateway
77+
secretName: nginx-gateway-ca
78+
privateKey:
79+
algorithm: RSA
80+
size: 2048
81+
issuerRef:
82+
name: selfsigned-issuer
83+
kind: Issuer
84+
group: cert-manager.io
85+
---
86+
apiVersion: cert-manager.io/v1
87+
kind: Issuer
88+
metadata:
89+
name: nginx-gateway-issuer
90+
namespace: nginx-gateway
91+
spec:
92+
ca:
93+
secretName: nginx-gateway-ca
94+
EOF
95+
```
96+
97+
## Create Server and Client Certificates
98+
99+
Now we can create the Certificate resources for the NGINX Gateway Fabric control plane (server) and the NGINX agent (client).
100+
101+
The `dnsName` field in the server Certificate represents the name that the NGINX Gateway Fabric control plane service will have once you install it. This name depends on your method of installation.
102+
103+
{{<tabs name="ngf-name">}}
104+
105+
{{%tab name="Helm"%}}
106+
107+
The full service name is of the format: `<helm-release-name>-nginx-gateway-fabric.<namespace>.svc`.
108+
109+
The default helm release name used in our installation docs is `ngf`, and the default namespace is `nginx-gateway`, so the `dnsName` should be `ngf-nginx-gateway-fabric.nginx-gateway.svc`.
110+
111+
{{% /tab %}}
112+
113+
{{%tab name="Manifests"%}}
114+
115+
The full service name is of the format: `<service-name>.<namespace>.svc`.
116+
117+
By default, the base service name is `nginx-gateway`, and the namespace is `nginx-gateway`, so the `dnsName` should be `nginx-gateway.nginx-gateway.svc`.
118+
119+
{{% /tab %}}
120+
121+
{{</tabs>}}
122+
123+
```yaml
124+
kubectl apply -f - <<EOF
125+
apiVersion: cert-manager.io/v1
126+
kind: Certificate
127+
metadata:
128+
name: nginx-gateway
129+
namespace: nginx-gateway
130+
spec:
131+
secretName: server-tls
132+
usages:
133+
- digital signature
134+
- key encipherment
135+
dnsNames:
136+
- ngf-nginx-gateway-fabric.nginx-gateway.svc # this value may need to be updated
137+
issuerRef:
138+
name: nginx-gateway-issuer
139+
EOF
140+
```
141+
142+
```yaml
143+
kubectl apply -f - <<EOF
144+
apiVersion: cert-manager.io/v1
145+
kind: Certificate
146+
metadata:
147+
name: nginx
148+
namespace: nginx-gateway
149+
spec:
150+
secretName: agent-tls
151+
usages:
152+
- "digital signature"
153+
- "key encipherment"
154+
dnsNames:
155+
- "*.cluster.local"
156+
issuerRef:
157+
name: nginx-gateway-issuer
158+
EOF
159+
```
160+
161+
Since the TLS Secrets are mounted into each Pod that uses them, the NGINX agent (client) Secret is duplicated by the NGINX Gateway Fabric control plane into whichever namespace NGINX is deployed into. All updates to the source Secret are propagated to the duplicate Secrets.
162+
163+
The name of the agent Secret is provided to the NGINX Gateway Fabric control plane via the command-line. `agent-tls` is the default name, but if you wish to use a different name, you can provide it when installing NGINX Gateway Fabric:
164+
165+
{{<tabs name="tls-secret-names">}}
166+
167+
{{%tab name="Helm"%}}
168+
169+
Specify the Secret name using the `certGenerator.agentTLSSecretName` helm value.
170+
171+
{{% /tab %}}
172+
173+
{{%tab name="Manifests"%}}
174+
175+
Specify the Secret name using the `agent-tls-secret` command-line argument.
176+
177+
{{% /tab %}}
178+
179+
{{</tabs>}}
180+
181+
## Final steps
182+
183+
You should see the Secrets created in the `nginx-gateway` namespace:
184+
185+
```shell
186+
kubectl -n nginx-gateway get secrets
187+
```
188+
189+
```text
190+
agent-tls kubernetes.io/tls 3 3s
191+
nginx-gateway-ca kubernetes.io/tls 3 15s
192+
server-tls kubernetes.io/tls 3 8s
193+
```
194+
195+
**You can now [install NGINX Gateway Fabric]({{< ref "/ngf/installation/installing-ngf" >}}).**

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ To complete this guide, you'll need to install:
1919

2020
- [kubectl](https://kubernetes.io/docs/tasks/tools/), a command-line tool for managing Kubernetes clusters.
2121
- [Helm 3.0 or later](https://helm.sh/docs/intro/install/), for deploying and managing applications on Kubernetes.
22+
- If deploying into a production environment, we highly recommend [installing custom certificates]({{< ref "/ngf/installation/installing-ngf/control-plane-certs.md" >}}) for securing the connection between the NGINX Gateway Fabric control plane and NGINX data plane Pods. **This should be done _before_ you install NGINX Gateway Fabric.** The default certificates are self-signed and will expire after 3 years.
2223

2324
{{< important >}} If you’d like to use NGINX Plus, some additional setup is also required: {{</ important >}}
2425

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ Learn how to install, upgrade, and uninstall NGINX Gateway Fabric using Kubernet
1818
To complete this guide, you'll need to install:
1919

2020
- [kubectl](https://kubernetes.io/docs/tasks/tools/), a command-line interface for managing Kubernetes clusters.
21+
- If deploying into a production environment, we highly recommend [installing custom certificates]({{< ref "/ngf/installation/installing-ngf/control-plane-certs.md" >}}) for securing the connection between the NGINX Gateway Fabric control plane and NGINX data plane Pods. **This should be done _before_ you install NGINX Gateway Fabric.** The default certificates are self-signed and will expire after 3 years.
2122

2223
{{< important >}} If you’d like to use NGINX Plus, some additional setup is also required: {{</ important >}}
2324

0 commit comments

Comments
 (0)