Expose apps with OpenShift Routes: edge, passthrough and re-encrypt TLS

A Route is OpenShift’s way to make a service reachable from outside the cluster under a host name. The router, run by the Ingress Controller, receives requests for that host and forwards them to the pods behind the service. Each cluster has an application domain with a wildcard DNS record and certificate, so a route gets a working host name even if you do not choose one.

oc get ingresses.config/cluster -o jsonpath='{.spec.domain}{"\n"}'

Plain HTTP

oc expose service/web
oc expose service/web --hostname=www.example.com
oc get route web

Fine for a quick test; anything real should use TLS. The hostname must resolve to the router: names under the application domain already do, other names need a DNS record.

The three TLS termination types

• Edge: TLS ends at the router, which forwards plain HTTP to the pod. The simplest option; certificates live on the route or come from the router’s default certificate.
• Passthrough: the router does not decrypt anything. It forwards the encrypted TCP stream to the pod based on the TLS SNI host name, so the application serves its own certificate. The router cannot look at paths or set cookies.
• Re-encrypt: TLS ends at the router, then the router opens a new TLS connection to the pod. Use it when traffic must be encrypted inside the cluster but you still want the router to present the public certificate.

Edge

# Router's default certificate
oc create route edge web --service=web --insecure-policy=Redirect

# Your own certificate for a custom host name
oc create route edge web-public --service=web \
  --hostname=www.example.com \
  --cert=tls.crt --key=tls.key --ca-cert=ca.crt

--insecure-policy sets insecureEdgeTerminationPolicy: Redirect sends plain HTTP visitors to HTTPS, None refuses plain HTTP, and Allow serves both.

Passthrough

oc create route passthrough web-tls --service=web --port=8443 --hostname=secure.example.com

No certificate goes on the route. The pod must listen for TLS on the target port and present a certificate valid for the host name.

Re-encrypt

# Pod certificate signed by the cluster's service CA
oc annotate service web service.beta.openshift.io/serving-cert-secret-name=web-tls
oc set volume deployment/web --add --name=tls --type=secret --secret-name=web-tls --mount-path=/etc/tls
oc create route reencrypt web-secure --service=web --port=8443

# Pod certificate from another CA
oc create route reencrypt web-secure --service=web --dest-ca-cert=destca.crt

The router must trust the pod’s certificate. When you leave out --dest-ca-cert, it defaults to the cluster’s service CA. Annotating a service with service.beta.openshift.io/serving-cert-secret-name makes OpenShift generate a matching certificate and key (tls.crt and tls.key) in that secret, which you mount into the pod and configure your server to use.

The same route as YAML

apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: web
spec:
  host: www.example.com
  to:
    kind: Service
    name: web
  port:
    targetPort: 8080
  tls:
    termination: edge
    insecureEdgeTerminationPolicy: Redirect

For termination: reencrypt add destinationCACertificate when the pod uses a non service-CA certificate; for edge and re-encrypt with your own certificate add certificate, key and optionally caCertificate. Recent versions can also reference a TLS secret through spec.tls.externalCertificate instead of pasting PEM data into the route.

HSTS

To tell browsers to always use HTTPS, add the haproxy.router.openshift.io/hsts_header annotation to an edge or re-encrypt route. It has no effect on plain HTTP or passthrough routes.

oc annotate route web --overwrite haproxy.router.openshift.io/hsts_header="max-age=31536000"

Troubleshooting routes

• oc describe route NAME shows whether the router admitted the route; a host name already claimed by a route in another namespace is normally rejected.
• A router 503 page usually means the service has no ready endpoints: check oc get endpoints SERVICE and the pods’ readiness.
• For passthrough, an error at the TLS handshake usually comes from the pod’s certificate, not the route.

Official documentation

• Securing routes
• Creating basic routes
• Securing service traffic using service serving certificate secrets