Post cover image

September 4, 2026

Red Hat Cert Manager: Certificates with Let’s Encrypt

This runbook shows how to use cert-manager and Let’s Encrypt to manage TLS certificates for an OpenShift cluster.

By Fabio Reis

5 min read

The main endpoints are:

API:     api.ocp.example.com
OAuth:   oauth-openshift.apps.ocp.example.com
Console: console-openshift-console.apps.ocp.example.com
Apps:    *.apps.ocp.example.com

Let's Encrypt issues publicly trusted certificates. There is no Custom CA to create, distribute, or configure in the OpenShift trust bundle.

The only requirement is that cert-manager can create DNS TXT records in the public DNS zone.

For Custom CA try this medium post :

Red Hat Cert-Manager with Custom CA In this lab, I want OpenShift to use certificates signed by my own Custom CA.

Why DNS-01?

DNS-01 validation is used in this lab because:

  • Wildcard certificates require DNS-01.
  • The API uses port 6443, not standard HTTPS port 443.
  • Validation does not require exposing an HTTP endpoint to Let's Encrypt.
  • The API can remain private while DNS remains publicly authoritative.

The flow is:

cert-manager
    ↓
DNS provider creates _acme-challenge TXT records
    ↓
Let’s Encrypt validates domain ownership
    ↓
cert-manager creates or renews TLS Secrets
    ↓
OpenShift API Server and Ingress Controller consume the Secrets

Prerequisites

Before starting, make sure you have:

  • Cluster administrator access.
  • The Red Hat build of cert-manager installed.
  • A public DNS zone for ocp.example.com.
  • A DNS provider supported by cert-manager.
  • An API token that allows cert-manager to edit DNS TXT records.
  • oc and OpenSSL installed on your workstation.

Check cert-manager:

oc get pods -n cert-manager
oc get crd | grep cert-manager.io

This example uses Cloudflare as the DNS provider. The same design works with Route 53, Azure DNS, Google Cloud DNS, and other supported DNS providers.

1. Create the DNS API token Secret

Create a Cloudflare API token with these permissions:

Zone / DNS / Edit
Zone / Zone / Read

Restrict the token to the DNS zone that contains ocp.example.com.

Create the Secret in the cert-manager namespace:

apiVersion: v1
kind: Secret
metadata:
  name: cloudflare-api-token-secret
  namespace: cert-manager
type: Opaque
stringData:
  api-token: <YOUR-CLOUDFLARE-API-TOKEN>

Apply it:

oc apply -f cloudflare-api-token-secret.yaml

Do not commit the API token to Git. In a GitOps workflow, use External Secrets, Sealed Secrets, or SOPS.

2. Create a Let's Encrypt ClusterIssuer

Start with the staging endpoint while testing. It prevents production rate-limit issues.

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    email: your-email@example.com
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt-staging-account-key
    solvers:
      - dns01:
          cloudflare:
            apiTokenSecretRef:
              name: cloudflare-api-token-secret
              key: api-token
        selector:
          dnsZones:
            - "ocp.example.com"

Apply and validate it:

oc apply -f letsencrypt-staging-issuer.yaml
oc get clusterissuer letsencrypt-staging

After validation, create the production issuer:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    email: your-email@example.com
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt-prod-account-key
    solvers:
      - dns01:
          cloudflare:
            apiTokenSecretRef:
              name: cloudflare-api-token-secret
              key: api-token
        selector:
          dnsZones:
            - "ocp.example.com"
oc apply -f letsencrypt-prod-issuer.yaml
oc get clusterissuer letsencrypt-prod

Expected result:

NAME               READY   AGE
letsencrypt-prod   True    1m

3. Create the API certificate

The API Server expects its custom serving certificate Secret in openshift-config.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: api-letsencrypt-cert
  namespace: openshift-config
spec:
  secretName: api-letsencrypt-cert
  renewBefore: 360h
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - api.ocp.example.com

Apply it:

oc apply -f api-letsencrypt-cert.yaml

Monitor the request:

oc get certificate api-letsencrypt-cert \
  -n openshift-config -w

During validation, cert-manager creates an ACME Order and Challenge:

oc get order -n openshift-config
oc get challenge -n openshift-config

4. Configure the API Server

First, check whether named API certificates already exist:

oc get apiserver cluster \
  -o jsonpath='{.spec.servingCerts.namedCertificates}{"\n"}'

For a lab without existing named certificates, apply this patch:

oc patch apiserver cluster \
  --type=merge \
  -p '{
    "spec": {
      "servingCerts": {
        "namedCertificates": [
          {
            "names": [
              "api.ocp.example.com"
            ],
            "servingCertificate": {
              "name": "api-letsencrypt-cert"
            }
          }
        ]
      }
    }
  }'

This patch replaces the complete namedCertificates list. If entries already exist, use oc edit apiserver cluster and append the new certificate.

Check the API Server Operator:

oc get co kube-apiserver

Validate the API certificate:

openssl s_client \
  -connect api.ocp.example.com:6443 \
  -servername api.ocp.example.com </dev/null

The certificate chain should be trusted without providing a custom CA file.

5. Create the wildcard certificate for Apps

The wildcard certificate covers every default application Route, including OAuth and the standard Console route.

Create the Certificate in openshift-ingress:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: apps-letsencrypt-wildcard
  namespace: openshift-ingress
spec:
  secretName: apps-letsencrypt-wildcard
  renewBefore: 360h
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - "*.apps.ocp.example.com"

Apply it:

oc apply -f apps-letsencrypt-wildcard.yaml

Wait until it is ready:

oc get certificate apps-letsencrypt-wildcard \
  -n openshift-ingress -w

Check the DNS-01 resources if the certificate does not become ready:

oc get order -n openshift-ingress
oc get challenge -n openshift-ingress

6. Configure the default Ingress Controller

Configure only the default certificate field, preserving the existing Ingress Controller settings:

oc patch ingresscontroller default \
  -n openshift-ingress-operator \
  --type=merge \
  -p '{"spec":{"defaultCertificate":{"name":"apps-letsencrypt-wildcard"}}}'

Confirm the configured Secret:

oc get ingresscontroller default \
  -n openshift-ingress-operator \
  -o jsonpath='{.spec.defaultCertificate.name}{"\n"}'

Expected result:

apps-letsencrypt-wildcard

The Ingress Controller automatically observes Secret updates. No router restart is required.

7. Validate OAuth, Console, and application Routes

Check the OAuth Route hostname:

oc get route oauth-openshift \
  -n openshift-authentication \
  -o jsonpath='{.spec.host}{"\n"}'

Validate OAuth:

openssl s_client \
  -connect oauth-openshift.apps.ocp.example.com:443 \
  -servername oauth-openshift.apps.ocp.example.com </dev/null

Validate the Console:

openssl s_client \
  -connect console-openshift-console.apps.ocp.example.com:443 \
  -servername console-openshift-console.apps.ocp.example.com </dev/null

Validate an application Route:

openssl s_client \
  -connect myapp.apps.ocp.example.com:443 \
  -servername myapp.apps.ocp.example.com </dev/null

All endpoints should return:

Verify return code: 0 (ok)

The default Console hostname is already covered by *.apps.ocp.example.com. No separate Console certificate or Console resource patch is required.

8. Log in with oc

Because Let's Encrypt is publicly trusted, no --certificate-authority argument is required:

oc login \
  --server=https://api.ocp.example.com:6443 \
  -u kubeadmin

During login, oc redirects authentication to:

oauth-openshift.apps.ocp.example.com

This is why the API certificate and the application wildcard certificate must both be correctly configured.

Troubleshooting

The Certificate remains READY=False

Check the Certificate, Order, and Challenge resources:

oc describe certificate api-letsencrypt-cert \
  -n openshift-config
oc get order -n openshift-config
oc get challenge -n openshift-config

For the wildcard certificate:

oc describe certificate apps-letsencrypt-wildcard \
  -n openshift-ingress
oc get order -n openshift-ingress
oc get challenge -n openshift-ingress

The usual causes are:

  • Invalid DNS provider API token.
  • Missing permissions to edit TXT records.
  • The wrong DNS zone in dnsZones.
  • DNS propagation delay.
  • Let's Encrypt rate limits.

The API certificate works, but oc login fails

Validate the API certificate first:

openssl s_client \
  -connect api.ocp.example.com:6443 \
  -servername api.ocp.example.com </dev/null

Then validate the OAuth Route:

openssl s_client \
  -connect oauth-openshift.apps.ocp.example.com:443 \
  -servername oauth-openshift.apps.ocp.example.com </dev/null

If OAuth still presents an issuer similar to this:

issuer=CN=ingress-operator@...

the default Ingress Controller is still using the OpenShift-generated certificate.

Confirm the configured Secret:

oc get ingresscontroller default \
  -n openshift-ingress-operator \
  -o jsonpath='{.spec.defaultCertificate.name}{"\n"}'

It must return:

apps-letsencrypt-wildcard

The Authentication Operator becomes degraded

Check its status:

oc get co authentication

If the error contains RouterCertsDegraded, inspect the certificate chain stored in the wildcard Secret:

oc -n openshift-ingress extract secret/apps-letsencrypt-wildcard \
  --to=/tmp/apps-letsencrypt-cert
openssl crl2pkcs7 -nocrl \
  -certfile /tmp/apps-letsencrypt-cert/tls.crt \
  | openssl pkcs7 -print_certs -noout

The output must contain the endpoint certificate and its intermediate CA certificate.

Do not add a Custom CA ConfigMap or configure Proxy.spec.trustedCA for Let's Encrypt. Let's Encrypt is already trusted by OpenShift and standard client trust stores.

Final result

cert-manager now manages the lifecycle of two Let's Encrypt certificates:

Let’s Encrypt
    ↓
DNS-01 validation
    ↓
cert-manager ClusterIssuer
    ↓
TLS Secrets
    ├── openshift-config / api-letsencrypt-cert
    └── openshift-ingress / apps-letsencrypt-wildcard
             ↓
OpenShift API, OAuth, Console, and application Routes

The certificates renew automatically before expiration. The API, OAuth endpoint, Console, and application Routes use publicly trusted certificates, eliminating the need for a Custom CA on user workstations.