Ingress TLS termination — the cluster HTTPS gateway

Ingress TLS termination is the cluster HTTPS gateway. The Ingress controller reads the TLS secret, terminates TLS, and forwards HTTPS traffic to the backend. The cert-manager automates the certificate lifecycle. This lesson walks the TLS termination, the cert-manager, and the operational discipline.

The TLS termination

The Ingress can terminate TLS:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: billing
spec:
  tls:
    - hosts:
        - billing.example.com
      secretName: billing-tls
  rules:
    - host: billing.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: billing
                port:
                  number: 80

The tls field specifies the hosts and the secret name. The Ingress controller reads the secret and terminates TLS.

sequenceDiagram
    autonumber
    participant EC as External client
    participant IC as Ingress controller
    participant S as Service
    EC->>IC: TLS handshake
    IC->>IC: read TLS secret
    IC->>IC: terminate TLS
    IC->>S: forward HTTP
    S->>EC: response

The Ingress controller terminates TLS; the backend Service receives HTTP.

The TLS secret

The TLS secret holds the certificate and the key:

kubectl create secret tls billing-tls \
  --cert=path/to/cert.pem \
  --key=path/to/key.pem

The secret is in the same namespace as the Ingress. The secret’s type is kubernetes.io/tls.

The cert-manager

The cert-manager automates the certificate lifecycle:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: billing-cert
  namespace: prod-app
spec:
  secretName: billing-tls
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - billing.example.com

The cert-manager generates the certificate, stores it in the secret, and renews the certificate before expiry. The cluster operator can use Let’s Encrypt or an internal CA.

sequenceDiagram
    autonumber
    participant CM as cert-manager
    participant LE as Let's Encrypt
    participant S as Secret
    participant IC as Ingress controller
    CM->>LE: request certificate
    LE-->>CM: certificate
    CM->>S: store certificate
    CM->>IC: certificate is available
    CM->>CM: renew certificate

The cert-manager is the production pattern for TLS certificates.

The TLS options

The Ingress controller supports TLS options:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: billing
  annotations:
    nginx.ingress.kubernetes.io/ssl-protocols: "TLSv1.2 TLSv1.3"
    nginx.ingress.kubernetes.io/ssl-ciphers: "EECDH+AESGCM:EDH+AESGCM"
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
    nginx.ingress.kubernetes.io/hsts: "true"
    nginx.ingress.kubernetes.io/hsts-max-age: "31536000"
spec:
  tls:
    - hosts:
        - billing.example.com
      secretName: billing-tls
  rules:
    - host: billing.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: billing
                port:
                  number: 80

The options include:

• ssl-protocols: the TLS versions allowed.
• ssl-ciphers: the ciphers allowed.
• force-ssl-redirect: redirect HTTP to HTTPS.
• hsts: enable HTTP Strict Transport Security.
• hsts-max-age: the HSTS max-age.

The failure modes

The Ingress TLS’s failure modes:

• Certificate expired: the TLS certificate has expired. The fix is to renew the certificate.
• Secret missing: the TLS secret is missing. The fix is to create the secret.
• Wrong host: the certificate does not match the host. The fix is to regenerate the certificate.
• cert-manager down: the cert-manager is not running. The fix is to restart the cert-manager.
• Issuer credentials wrong: the issuer’s credentials are wrong. The fix is to update the credentials.

The operational discipline

The Ingress TLS’s operational discipline:

• Document the TLS configuration. The TLS configuration is the cluster’s HTTPS gateway.
• Monitor the certificates. The certificates must be valid.
• Use cert-manager for automation. The cert-manager is the production pattern.
• Test the TLS in staging. The TLS must work for the workload.
• Plan the TLS’s evolution. The TLS options can be hardened over time.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.

Quiz

Production discipline

• The Ingress controller is the cluster’s HTTPS gateway. The cluster operator must treat it as critical infrastructure.
• Document the TLS configuration. The TLS configuration is the cluster’s HTTPS gateway.
• Monitor the certificates. The certificates must be valid.
• Use cert-manager for automation. The cert-manager is the production pattern.
• Test the TLS in staging. The TLS must work for the workload.
• Plan the TLS’s evolution. The TLS options can be hardened over time.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.
• Train the operations team on the TLS diagnostics. The diagnostics are the team’s tools.
• Set up alerts on the certificate’s expiry. The alerts are the leading indicator of outages.