Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 37 ยท Networking and Routes

TLS on OpenShift Routes: Edge, Passthrough and Re-encrypt

Compare the three TLS termination modes of OpenShift routes, create secure routes with oc, set insecure edge redirects, use custom certificates and check expiry dates.

Plain HTTP is not acceptable for real applications. OpenShift routes can handle TLS in three ways, called termination types. They differ in where the encrypted connection ends: at the router, at the pod, or at both. Choosing correctly decides who holds the certificate, whether the router can read the traffic, and how much work your app does.

Everything shown with oc and YAML is read-only here. The runnable code is a Python stand-in that checks certificate dates and decides what each mode allows.

The three termination types

flowchart LR
  subgraph Edge
    B1["Browser"] -- "TLS" --> R1["Router"]
    R1 -- "plain HTTP" --> P1["Pod"]
  end
  subgraph Passthrough
    B2["Browser"] -- "TLS" --> R2["Router (TCP only)"]
    R2 -- "same TLS" --> P2["Pod terminates TLS"]
  end
  subgraph Reencrypt
    B3["Browser"] -- "TLS" --> R3["Router"]
    R3 -- "new TLS" --> P3["Pod"]
  end

Where each mode ends and starts encryption.

Mode Certificate lives in Router sees plain text Typical use
edge The route (or the router default) Yes Most web apps; app speaks plain HTTP
passthrough The pod No Apps needing end-to-end TLS, client certificates, non-HTTP over TLS
reencrypt Route (public) and pod (internal) Yes Compliance needs encryption inside the cluster too

Edge

The router decrypts and forwards plain HTTP to the pod. Without a certificate in the route, the router uses its default wildcard certificate, so https://shop-api-shop.apps.mycluster.example.com works immediately.

Terminal
oc create route edge shop-api --service=shop-api

With your own certificate:

Terminal
oc create route edge shop-api --service=shop-api \
  --hostname=api.example.com \
  --cert=api.crt --key=api.key --ca-cert=ca.crt

Passthrough

The router can only see the TLS handshake's SNI hostname, then relays bytes. The pod must hold the certificate and speak TLS itself. Path-based routing and annotations such as rewrite do not work because the request is never decrypted.

Terminal
oc create route passthrough shop-db-admin --service=shop-db --port=8443

Re-encrypt

The router terminates the public TLS, then opens a new TLS connection to the pod and verifies the pod's certificate against destinationCACertificate. Clusters can generate service certificates for you: annotate a service with service.beta.openshift.io/serving-cert-secret-name=shop-tls and OpenShift creates a secret with a certificate signed by the cluster's service CA.

Terminal
oc annotate service shop-api service.beta.openshift.io/serving-cert-secret-name=shop-tls
oc create route reencrypt shop-api --service=shop-api --dest-ca-cert=service-ca.crt

The YAML form

YAML
apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: shop-api
spec:
  host: api.example.com
  to:
    kind: Service
    name: shop-api
  tls:
    termination: edge                      # edge | passthrough | reencrypt
    insecureEdgeTerminationPolicy: Redirect # None | Allow | Redirect
    certificate: |
      -----BEGIN CERTIFICATE-----
      ...
    key: |
      -----BEGIN PRIVATE KEY-----
      ...

insecureEdgeTerminationPolicy decides what happens to plain HTTP requests: Redirect sends them to HTTPS (the usual choice), Allow serves both, None blocks HTTP. Passthrough routes support only None and Redirect.

Private keys placed directly in a Route are visible to anyone who can read that object. For stricter handling, newer OpenShift versions let a route reference a secret with externalCertificate, so the key stays in a Secret protected by RBAC.

Python Stand-in: which mode fits?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Certificates expire

An expired certificate breaks every visitor at once. You inspect a certificate's dates with OpenSSL, for example openssl x509 -noout -enddate -in api.crt or against a live host with openssl s_client. The stand-in checks expiry windows from dates you supply, the way a monitoring script would.

Python Stand-in: expiry check

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

In practice you rarely renew by hand. The cert-manager Operator for Red Hat OpenShift (installed through operators) can request and renew certificates automatically and keep route secrets fresh.

Common mistakes

  • Using edge while the pod itself expects HTTPS: the router sends plain HTTP, the pod rejects it, and you see 502 or 503.
  • Using passthrough and then expecting path routing or cookies to work.
  • Forgetting the full chain in --ca-cert, so some clients reject the site.
  • Letting a certificate for api.example.com front a route with another host.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which termination type lets the router read and modify the HTTP request, and uses plain HTTP to the pod?

    Edge terminates TLS at the router and forwards unencrypted traffic to the pod.
  2. 2. You need mutual TLS where the pod verifies client certificates itself. Which mode?

    Only passthrough keeps the client's TLS session intact up to the pod.
  3. 3. What does insecureEdgeTerminationPolicy: Redirect do?

    Redirect answers plain HTTP with a redirect to the HTTPS URL.
  4. 4. Which annotation asks OpenShift to generate a serving certificate for a service?

    The service CA operator creates a secret with a signed certificate when that annotation is set.

Summary

  • Edge: router holds the certificate, plain HTTP to the pod.
  • Passthrough: pod holds the certificate, router only relays bytes.
  • Re-encrypt: TLS on both legs, verified with a destination CA.
  • Use Redirect so HTTP users reach HTTPS.
  • Monitor expiry; automate renewal where possible.

Next: Ingress and Ingress Controllers