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..4a34e24d9 --- /dev/null +++ b/content/ngf/installation/installing-ngf/control-plane-certs.md @@ -0,0 +1,193 @@ +--- +title: Add secure authentication to the control and data planes +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 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 >}} + +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: {{}}