Add certificates for secure authentication

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, we recommend a solution such as cert-manager 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.

These steps should be completed before you install NGINX Gateway Fabric.

Before you begin

To complete this guide, you will need the following prerequisites:

  • Administrator access to a Kubernetes cluster.
  • Helm and kubectl must be installed locally.

Install cert-manager

Add the Helm repository:

helm repo add jetstack https://charts.jetstack.io
helm repo update

Install cert-manager:

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.

Create the CA issuer

The first step is to create the CA (certificate authority) issuer.

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.

Create the namespace:

kubectl create namespace nginx-gateway
kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: selfsigned-issuer
  namespace: nginx-gateway
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: nginx-gateway-ca
  namespace: nginx-gateway
spec:
  isCA: true
  commonName: nginx-gateway
  secretName: nginx-gateway-ca
  privateKey:
    algorithm: RSA
    size: 2048
  issuerRef:
    name: selfsigned-issuer
    kind: Issuer
    group: cert-manager.io
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: nginx-gateway-issuer
  namespace: nginx-gateway
spec:
  ca:
    secretName: nginx-gateway-ca
EOF

Create server and client certificates

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.

The full service name is of the format: <helm-release-name>-nginx-gateway-fabric.<namespace>.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 full service name is of the format: <service-name>.<namespace>.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.

kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: nginx-gateway
  namespace: nginx-gateway
spec:
  secretName: server-tls
  usages:
  - digital signature
  - key encipherment
  dnsNames:
  - ngf-nginx-gateway-fabric.nginx-gateway.svc # this value may need to be updated
  issuerRef:
    name: nginx-gateway-issuer
EOF
kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: nginx
  namespace: nginx-gateway
spec:
  secretName: agent-tls
  usages:
  - "digital signature"
  - "key encipherment"
  dnsNames:
  - "*.cluster.local"
  issuerRef:
    name: nginx-gateway-issuer
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.

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:

Specify the Secret name using the certGenerator.agentTLSSecretName helm value.

Specify the Secret name using the agent-tls-secret command-line argument.

Confirm the Secrets have been created

You should see the Secrets created in the nginx-gateway namespace:

kubectl -n nginx-gateway get secrets
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.

Next steps