How to use Ingress with cert-manager on OpenShift

Prerequisites

• cert-manager installed
• DNS for ${HOST} points to your OpenShift router
• Service ${SVC_NAME} exposes HTTPS inside the cluster

Create the ClusterIssuer (once)

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: ${ISSUER_NAME}
spec:
  acme:
    email: you@example.com
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: acme-account-key
    solvers:
    - http01:
        ingress:
          class: openshift-default

Apply:

oc apply -f clusterissuer.yaml

Apply your Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-ingress
  namespace: ${NS}
  annotations:
    cert-manager.io/cluster-issuer: ${ISSUER_NAME}
    acme.cert-manager.io/http01-ingress-class: openshift-default
    route.openshift.io/termination: "edge" # default is edge
spec:
  ingressClassName: openshift-default
  tls:
    - hosts: ["${HOST}"]
      secretName: ${TLS_SECRET}
  rules:
    - host: ${HOST}
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: ${SVC_NAME}
                port:
                  name: https

Apply:

oc apply -f ingress.yaml

What happens

• cert-manager solves HTTP-01 on /.well-known/acme-challenge
• Let’s Encrypt issues a cert to secret ${TLS_SECRET}
• The router terminates TLS, then reencrypts traffic to ${SVC_NAME}

Verify

oc -n ${NS} get certificate,challenge,order
oc -n ${NS} describe ingress app-ingress

Common pitfalls

• Port 80 to the router must reach the cluster for HTTP-01
• ingressClassName and acme.cert-manager.io/http01-ingress-class must match openshift-default
• The backend service must accept TLS on the named port https