Kubernetes TLS Ingress Configuration: Nginx, Traefik & Gateway API with cert-manager

Gateway API is the successor to the Ingress resource, providing more expressive routing and better separation of concerns between cluster operators and application developers.

Gateway with TLS

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: production-gateway
  namespace: gateway-system
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  gatewayClassName: nginx  # or istio, traefik, envoy
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "*.company.com"
      tls:
        mode: Terminate
        certificateRefs:
          - name: wildcard-tls-secret
            namespace: gateway-system
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              gateway-access: "true"
    - name: http
      protocol: HTTP
      port: 80
      hostname: "*.company.com"
      allowedRoutes:
        namespaces:
          from: Same

HTTPRoute Attached to Gateway

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: app-route
  namespace: production
spec:
  parentRefs:
    - name: production-gateway
      namespace: gateway-system
  hostnames:
    - "app.company.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: api-svc
          port: 8080
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: frontend-svc
          port: 80

Gateway API with cert-manager (Automatic)

cert-manager 1.14+ supports Gateway API natively:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: auto-tls-gateway
  namespace: gateway-system
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  gatewayClassName: nginx
  listeners:
    - name: https-app
      protocol: HTTPS
      port: 443
      hostname: "app.company.com"
      tls:
        mode: Terminate
        certificateRefs:
          - name: app-tls-gateway  # cert-manager creates this

cert-manager watches Gateway resources with the annotation and automatically creates Certificate resources for each listener hostname.

mTLS at Ingress

For services requiring client certificate authentication:

Nginx Ingress mTLS

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: mtls-ingress
  namespace: production
  annotations:
    nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
    nginx.ingress.kubernetes.io/auth-tls-secret: "production/client-ca-secret"
    nginx.ingress.kubernetes.io/auth-tls-verify-depth: "2"
    nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - secure-api.company.com
      secretName: secure-api-tls
  rules:
    - host: secure-api.company.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: secure-api-svc
                port:
                  number: 8080

Create the client CA secret:

# The secret contains the CA certificate(s) that signed client certificates
kubectl create secret generic client-ca-secret \
  --from-file=ca.crt=client-ca-chain.pem \
  -n production

Traefik mTLS

apiVersion: traefik.io/v1alpha1
kind: TLSOption
metadata:
  name: mtls-strict
  namespace: production
spec:
  minVersion: VersionTLS12
  clientAuth:
    secretNames:
      - client-ca-secret
    clientAuthType: RequireAndVerifyClientCert
---
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: mtls-route
  namespace: production
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`secure-api.company.com`)
      kind: Rule
      services:
        - name: secure-api-svc
          port: 8080
  tls:
    secretName: secure-api-tls
    options:
      name: mtls-strict
      namespace: production

Wildcard Certificates

Wildcard certificates (*.company.com) reduce the number of certificates to manage but require DNS-01 challenges (HTTP-01 can’t validate wildcards).

cert-manager Wildcard with DNS-01

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod-dns
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: pki-team@company.com
    privateKeySecretRef:
      name: letsencrypt-prod-dns-key
    solvers:
      - dns01:
          route53:
            region: us-east-1
            hostedZoneID: Z1234567890
            accessKeyIDSecretRef:
              name: route53-credentials
              key: access-key-id
            secretAccessKeySecretRef:
              name: route53-credentials
              key: secret-access-key
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: wildcard-cert
  namespace: gateway-system
spec:
  secretName: wildcard-tls-secret
  issuerRef:
    name: letsencrypt-prod-dns
    kind: ClusterIssuer
  dnsNames:
    - "*.company.com"
    - "company.com"
  duration: 2160h
  renewBefore: 720h

Share Wildcard Secret Across Namespaces

# Option 1: Use kubernetes-reflector to sync secrets
apiVersion: v1
kind: Secret
metadata:
  name: wildcard-tls-secret
  namespace: gateway-system
  annotations:
    reflector.v1.k8s.emberstack.com/reflection-allowed: "true"
    reflector.v1.k8s.emberstack.com/reflection-allowed-namespaces: "production,staging"
    reflector.v1.k8s.emberstack.com/reflection-auto-enabled: "true"
type: kubernetes.io/tls

# Option 2: cert-manager Certificate per namespace (cleaner RBAC)
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: wildcard-cert
  namespace: production  # Each namespace gets its own copy
spec:
  secretName: wildcard-tls-secret
  issuerRef:
    name: letsencrypt-prod-dns
    kind: ClusterIssuer
  dnsNames:
    - "*.company.com"

Troubleshooting TLS Ingress Issues

Certificate Not Applied to Ingress

# 1. Check if the secret exists and has data
kubectl get secret app-tls-secret -n production -o yaml | grep "tls.crt"

# 2. Check if cert-manager Certificate is Ready
kubectl get certificate -n production
kubectl describe certificate app-cert -n production

# 3. Check cert-manager events
kubectl get events -n production --field-selector reason=Issuing

# 4. Check ingress controller logs
kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx --tail=50 | grep -i "ssl\|tls\|cert"

# 5. Verify the ingress references the correct secret
kubectl get ingress app-ingress -n production -o jsonpath='{.spec.tls[*].secretName}'

Wrong Certificate Served

# Check what certificate the ingress is actually serving
openssl s_client -connect app.company.com:443 -servername app.company.com < /dev/null 2>/dev/null | \
  openssl x509 -noout -subject -issuer -dates -ext subjectAltName

# Common causes:
# 1. SNI mismatch - hostname in request doesn't match any tls[].hosts
# 2. Default certificate being served - check default-ssl-certificate setting
# 3. Secret in wrong namespace
# 4. Ingress controller cache - restart controller pods

# Force ingress controller to reload
kubectl rollout restart deployment -n ingress-nginx ingress-nginx-controller

Mixed HTTP/HTTPS (Redirect Loop)

# Symptom: ERR_TOO_MANY_REDIRECTS

# Cause 1: Load balancer terminates TLS, ingress also redirects to HTTPS
# Fix: Tell ingress the original protocol via headers
metadata:
  annotations:
    nginx.ingress.kubernetes.io/use-forwarded-headers: "true"
    nginx.ingress.kubernetes.io/forwarded-for-header: "X-Forwarded-For"

# Cause 2: Backend app redirects to HTTPS but ingress already handles TLS
# Fix: Configure backend to trust X-Forwarded-Proto header

# Cause 3: HSTS cached in browser from previous config
# Fix: Clear browser HSTS cache or wait for max-age to expire

cert-manager Certificate Stuck in “Not Ready”

# Full diagnostic chain
kubectl get certificate,certificaterequest,order,challenge -n production

# Check the Order status
kubectl describe order -n production $(kubectl get order -n production -o name | head -1)

# Check Challenge status (for ACME)
kubectl describe challenge -n production $(kubectl get challenge -n production -o name | head -1)

# Common fixes:
# DNS-01: Verify DNS credentials, check propagation
dig _acme-challenge.app.company.com TXT

# HTTP-01: Verify ingress controller can serve /.well-known/acme-challenge/
curl -v http://app.company.com/.well-known/acme-challenge/test