Skip to content

Commit 27babac

Browse files
sjbermansjberman
authored
NGF: add control plane/data plane TLS doc (#488)
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 707e7df commit 27babac

File tree

4 files changed

+197
-0
lines changed

4 files changed

+197
-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: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
title: Add secure authentication to the control and data planes
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+
Install cert-manager:
32+
33+
```shell
34+
helm install \
35+
cert-manager jetstack/cert-manager \
36+
--namespace cert-manager \
37+
--create-namespace \
38+
--set config.apiVersion="controller.config.cert-manager.io/v1alpha1" \
39+
--set config.kind="ControllerConfiguration" \
40+
--set config.enableGatewayAPI=true \
41+
--set crds.enabled=true
42+
43+
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" >}}).
44+
45+
## Create the CA issuer
46+
47+
The first step is to create the CA (certificate authority) issuer.
48+
49+
{{< 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 >}}
50+
51+
Create the namespace:
52+
53+
```shell
54+
kubectl create namespace nginx-gateway
55+
```
56+
57+
```yaml
58+
kubectl apply -f - <<EOF
59+
apiVersion: cert-manager.io/v1
60+
kind: Issuer
61+
metadata:
62+
name: selfsigned-issuer
63+
namespace: nginx-gateway
64+
spec:
65+
selfSigned: {}
66+
---
67+
apiVersion: cert-manager.io/v1
68+
kind: Certificate
69+
metadata:
70+
name: nginx-gateway-ca
71+
namespace: nginx-gateway
72+
spec:
73+
isCA: true
74+
commonName: nginx-gateway
75+
secretName: nginx-gateway-ca
76+
privateKey:
77+
algorithm: RSA
78+
size: 2048
79+
issuerRef:
80+
name: selfsigned-issuer
81+
kind: Issuer
82+
group: cert-manager.io
83+
---
84+
apiVersion: cert-manager.io/v1
85+
kind: Issuer
86+
metadata:
87+
name: nginx-gateway-issuer
88+
namespace: nginx-gateway
89+
spec:
90+
ca:
91+
secretName: nginx-gateway-ca
92+
EOF
93+
```
94+
95+
## Create server and client certificates
96+
97+
Create the Certificate resources for the NGINX Gateway Fabric control plane (server) and the NGINX agent (client).
98+
99+
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.
100+
101+
{{<tabs name="ngf-name">}}
102+
103+
{{%tab name="Helm"%}}
104+
105+
The full service name is of the format: `<helm-release-name>-nginx-gateway-fabric.<namespace>.svc`.
106+
107+
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`.
108+
109+
{{% /tab %}}
110+
111+
{{%tab name="Manifests"%}}
112+
113+
The full service name is of the format: `<service-name>.<namespace>.svc`.
114+
115+
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`.
116+
117+
{{% /tab %}}
118+
119+
{{</tabs>}}
120+
121+
```yaml
122+
kubectl apply -f - <<EOF
123+
apiVersion: cert-manager.io/v1
124+
kind: Certificate
125+
metadata:
126+
name: nginx-gateway
127+
namespace: nginx-gateway
128+
spec:
129+
secretName: server-tls
130+
usages:
131+
- digital signature
132+
- key encipherment
133+
dnsNames:
134+
- ngf-nginx-gateway-fabric.nginx-gateway.svc # this value may need to be updated
135+
issuerRef:
136+
name: nginx-gateway-issuer
137+
EOF
138+
```
139+
140+
```yaml
141+
kubectl apply -f - <<EOF
142+
apiVersion: cert-manager.io/v1
143+
kind: Certificate
144+
metadata:
145+
name: nginx
146+
namespace: nginx-gateway
147+
spec:
148+
secretName: agent-tls
149+
usages:
150+
- "digital signature"
151+
- "key encipherment"
152+
dnsNames:
153+
- "*.cluster.local"
154+
issuerRef:
155+
name: nginx-gateway-issuer
156+
EOF
157+
```
158+
159+
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.
160+
161+
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:
162+
163+
{{<tabs name="tls-secret-names">}}
164+
165+
{{%tab name="Helm"%}}
166+
167+
Specify the Secret name using the `certGenerator.agentTLSSecretName` helm value.
168+
169+
{{% /tab %}}
170+
171+
{{%tab name="Manifests"%}}
172+
173+
Specify the Secret name using the `agent-tls-secret` command-line argument.
174+
175+
{{% /tab %}}
176+
177+
{{</tabs>}}
178+
179+
## Final steps
180+
181+
You should see the Secrets created in the `nginx-gateway` namespace:
182+
183+
```shell
184+
kubectl -n nginx-gateway get secrets
185+
```
186+
187+
```text
188+
agent-tls kubernetes.io/tls 3 3s
189+
nginx-gateway-ca kubernetes.io/tls 3 15s
190+
server-tls kubernetes.io/tls 3 8s
191+
```
192+
193+
**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)