From d0ddb8aafbe9506b2ea9cc1374c6ec9af30ac0c8 Mon Sep 17 00:00:00 2001 From: Saylor Berman Date: Fri, 2 May 2025 08:16:21 -0600 Subject: [PATCH 1/3] 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. --- .../integrating-cert-manager.md | 2 + .../installing-ngf/control-plane-certs.md | 195 ++++++++++++++++++ .../ngf/installation/installing-ngf/helm.md | 1 + .../installation/installing-ngf/manifests.md | 1 + 4 files changed, 199 insertions(+) create mode 100644 content/ngf/installation/installing-ngf/control-plane-certs.md diff --git a/content/ngf/how-to/traffic-security/integrating-cert-manager.md b/content/ngf/how-to/traffic-security/integrating-cert-manager.md index ec46560e9..6c17cd145 100644 --- a/content/ngf/how-to/traffic-security/integrating-cert-manager.md +++ b/content/ngf/how-to/traffic-security/integrating-cert-manager.md @@ -23,6 +23,8 @@ Follow the steps in this guide to: ## Before you begin +You need: + - Administrator access to a Kubernetes cluster. - [Helm](https://helm.sh) and [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) must be installed locally. - [NGINX Gateway Fabric deployed]({{< ref "/ngf/installation/" >}}) in the Kubernetes cluster. diff --git a/content/ngf/installation/installing-ngf/control-plane-certs.md b/content/ngf/installation/installing-ngf/control-plane-certs.md new file mode 100644 index 000000000..3ff2b8683 --- /dev/null +++ b/content/ngf/installation/installing-ngf/control-plane-certs.md @@ -0,0 +1,195 @@ +--- +title: Control Plane and Data Plane Authentication +weight: 300 +toc: true +type: how-to +product: NGF +docs: DOCS-0000 +--- + +## Overview + +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. + +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.** + +## Before you begin + +You need: + +- Administrator access to a Kubernetes cluster. +- [Helm](https://helm.sh) and [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) must be installed locally. + +## Install cert-manager + +- Add the Helm repository. + + ```shell + helm repo add jetstack https://charts.jetstack.io + helm repo update + ``` + +- Install cert-manager: + + ```shell + helm install \ + cert-manager jetstack/cert-manager \ + --namespace cert-manager \ + --create-namespace \ + --set config.apiVersion="controller.config.cert-manager.io/v1alpha1" \ + --set config.kind="ControllerConfiguration" \ + --set config.enableGatewayAPI=true \ + --set crds.enabled=true + ``` + + 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" >}}). + +## Create CA Issuer + +The first step is to create the CA Issuer. + +{{< 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 >}} + +Create the namespace: + +```shell +kubectl create namespace nginx-gateway +``` + +```yaml +kubectl apply -f - <}} + +{{%tab name="Helm"%}} + +The full service name is of the format: `-nginx-gateway-fabric..svc`. + +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`. + +{{% /tab %}} + +{{%tab name="Manifests"%}} + +The full service name is of the format: `..svc`. + +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`. + +{{% /tab %}} + +{{}} + +```yaml +kubectl apply -f - <}} + +{{%tab name="Helm"%}} + +Specify the Secret name using the `certGenerator.agentTLSSecretName` helm value. + +{{% /tab %}} + +{{%tab name="Manifests"%}} + +Specify the Secret name using the `agent-tls-secret` command-line argument. + +{{% /tab %}} + +{{}} + +## Final steps + +You should see the Secrets created in the `nginx-gateway` namespace: + +```shell +kubectl -n nginx-gateway get secrets +``` + +```text +agent-tls kubernetes.io/tls 3 3s +nginx-gateway-ca kubernetes.io/tls 3 15s +server-tls kubernetes.io/tls 3 8s +``` + +**You can now [install NGINX Gateway Fabric]({{< ref "/ngf/installation/installing-ngf" >}}).** diff --git a/content/ngf/installation/installing-ngf/helm.md b/content/ngf/installation/installing-ngf/helm.md index dd859a459..e5d432432 100644 --- a/content/ngf/installation/installing-ngf/helm.md +++ b/content/ngf/installation/installing-ngf/helm.md @@ -19,6 +19,7 @@ To complete this guide, you'll need to install: - [kubectl](https://kubernetes.io/docs/tasks/tools/), a command-line tool for managing Kubernetes clusters. - [Helm 3.0 or later](https://helm.sh/docs/intro/install/), for deploying and managing applications on Kubernetes. +- 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. {{< important >}} If you’d like to use NGINX Plus, some additional setup is also required: {{}} diff --git a/content/ngf/installation/installing-ngf/manifests.md b/content/ngf/installation/installing-ngf/manifests.md index a42ea9bd0..173ad5d41 100644 --- a/content/ngf/installation/installing-ngf/manifests.md +++ b/content/ngf/installation/installing-ngf/manifests.md @@ -18,6 +18,7 @@ Learn how to install, upgrade, and uninstall NGINX Gateway Fabric using Kubernet To complete this guide, you'll need to install: - [kubectl](https://kubernetes.io/docs/tasks/tools/), a command-line interface for managing Kubernetes clusters. +- 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. {{< important >}} If you’d like to use NGINX Plus, some additional setup is also required: {{}} From 3595107a02b3f4d00bf50cadfb4a739d28ba9bfc Mon Sep 17 00:00:00 2001 From: Saylor Berman Date: Tue, 6 May 2025 12:13:55 -0600 Subject: [PATCH 2/3] Fix capitalization --- .../ngf/installation/installing-ngf/control-plane-certs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/ngf/installation/installing-ngf/control-plane-certs.md b/content/ngf/installation/installing-ngf/control-plane-certs.md index 3ff2b8683..da385d8cd 100644 --- a/content/ngf/installation/installing-ngf/control-plane-certs.md +++ b/content/ngf/installation/installing-ngf/control-plane-certs.md @@ -9,7 +9,7 @@ docs: DOCS-0000 ## Overview -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. +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. 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.** @@ -158,7 +158,7 @@ spec: EOF ``` -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. +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. 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: From 07e091e85a250652231baf91af06a09400728cd6 Mon Sep 17 00:00:00 2001 From: Saylor Berman Date: Wed, 7 May 2025 08:14:42 -0600 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Alan Dooley --- .../installing-ngf/control-plane-certs.md | 42 +++++++++---------- 1 file changed, 20 insertions(+), 22 deletions(-) diff --git a/content/ngf/installation/installing-ngf/control-plane-certs.md b/content/ngf/installation/installing-ngf/control-plane-certs.md index da385d8cd..4a34e24d9 100644 --- a/content/ngf/installation/installing-ngf/control-plane-certs.md +++ b/content/ngf/installation/installing-ngf/control-plane-certs.md @@ -1,5 +1,5 @@ --- -title: Control Plane and Data Plane Authentication +title: Add secure authentication to the control and data planes weight: 300 toc: true type: how-to @@ -22,31 +22,29 @@ You need: ## Install cert-manager -- Add the Helm repository. +Add the Helm repository: - ```shell - helm repo add jetstack https://charts.jetstack.io - helm repo update - ``` +```shell +helm repo add jetstack https://charts.jetstack.io +helm repo update -- Install cert-manager: +Install cert-manager: - ```shell - helm install \ - cert-manager jetstack/cert-manager \ - --namespace cert-manager \ - --create-namespace \ - --set config.apiVersion="controller.config.cert-manager.io/v1alpha1" \ - --set config.kind="ControllerConfiguration" \ - --set config.enableGatewayAPI=true \ - --set crds.enabled=true - ``` +```shell +helm install \ + cert-manager jetstack/cert-manager \ + --namespace cert-manager \ + --create-namespace \ + --set config.apiVersion="controller.config.cert-manager.io/v1alpha1" \ + --set config.kind="ControllerConfiguration" \ + --set config.enableGatewayAPI=true \ + --set crds.enabled=true 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" >}}). -## Create CA Issuer +## Create the CA issuer -The first step is to create the CA Issuer. +The first step is to create the CA (certificate authority) issuer. {{< 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 >}} @@ -94,9 +92,9 @@ spec: EOF ``` -## Create Server and Client Certificates +## Create server and client certificates -Now we can create the Certificate resources for the NGINX Gateway Fabric control plane (server) and the NGINX agent (client). +Create the Certificate resources for the NGINX Gateway Fabric control plane (server) and the NGINX agent (client). 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. @@ -106,7 +104,7 @@ The `dnsName` field in the server Certificate represents the name that the NGINX The full service name is of the format: `-nginx-gateway-fabric..svc`. -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`. +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`. {{% /tab %}}