When deploying applications in OpenShift, one of the key challenges is exposing services to external clients. This is where OpenShift Routes come into play. Unlike Kubernetes Ingress, OpenShift provides a native routing solution that integrates directly with the platform’s networking stack, offering features like built-in TLS termination, sticky sessions, and custom certificates.

This article will take you through the complete lifecycle of an OpenShift Route—from creation and configuration to advanced debugging and security best practices.

1. What is an OpenShift Route?

An OpenShift Route is a way to expose a service running in an OpenShift cluster to external users. The OpenShift Router (based on HAProxy) acts as an entry point, forwarding traffic to the correct service based on defined Routes.

A basic Route definition looks like this:

apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: my-app-route
  namespace: my-app-namespace
spec:
  host: my-app.example.com
  to:
    kind: Service
    name: my-app-service
  port:
    targetPort: 8080
  tls:
    termination: edge
  wildcardPolicy: None

Key Components of a Route:

  • host: Specifies the external hostname for the application.
  • to.kind & to.name: Determines the backend service receiving traffic.
  • port.targetPort: Defines which service port should handle the traffic.
  • tls.termination: Configures how TLS is handled (Edge, Passthrough, or Re-encrypt).
  • wildcardPolicy: Controls whether wildcard subdomains are allowed.

How Does Routing Work Internally?

  1. The user accesses https://my-app.example.com.
  2. The request is resolved via DNS, pointing to the OpenShift Router.
  3. The Router looks up the correct Route based on the host field.
  4. HAProxy forwards the request to the specified backend service.
  5. The service processes the request and sends the response back to the client.

2. Types of OpenShift Routes

OpenShift supports different types of TLS termination, each suited for different security and performance requirements.

a) Edge Termination (TLS ends at the router)

With Edge termination, the OpenShift Router terminates the TLS connection and forwards unencrypted traffic to the backend service.

spec:
  tls:
    termination: edge

Use Case:

  • Ideal when the backend service does not need to handle encryption.
  • Reduces computational overhead on backend pods.

b) Passthrough Termination (TLS remains encrypted)

With Passthrough termination, TLS traffic is sent directly to the backend without decryption.

spec:
  tls:
    termination: passthrough

Use Case:

  • Required when the backend service must handle its own TLS certificates.
  • Used for applications requiring mutual TLS (mTLS) authentication.

c) Re-encrypt Termination (TLS is re-encrypted)

With Re-encrypt termination, the router decrypts the incoming request and re-encrypts it before forwarding it to the backend.

spec:
  tls:
    termination: reencrypt

Use Case:

  • Used when communication between the router and the backend service must also be encrypted.
  • Useful for compliance with security policies.

3. Customizing OpenShift Routes

a) Using Custom Certificates

By default, OpenShift provides a wildcard certificate for Routes, but you can specify a custom certificate:

spec:
  tls:
    termination: edge
    certificate: |-
      -----BEGIN CERTIFICATE-----
      YOUR_CERT_HERE
      -----END CERTIFICATE-----
    key: |-
      -----BEGIN PRIVATE KEY-----
      YOUR_KEY_HERE
      -----END PRIVATE KEY-----
    caCertificate: |-
      -----BEGIN CERTIFICATE-----
      YOUR_CA_CERT_HERE
      -----END CERTIFICATE-----

b) Enabling Sticky Sessions

For applications requiring session persistence, use the haproxy.router.openshift.io/balance annotation:

metadata:
  annotations:
    haproxy.router.openshift.io/balance: source

This ensures that subsequent requests from the same client are routed to the same backend pod.

4. Debugging and Troubleshooting OpenShift Routes

a) Checking Route Status

To view Route details and ensure it is properly configured:

oc get route my-app-route -o yaml

b) Inspecting Router Logs

If requests are not being processed correctly, check the HAProxy logs:

oc logs -n openshift-ingress $(oc get pods -n openshift-ingress -l app=router -o jsonpath='{.items[0].metadata.name}')

c) Testing DNS Resolution

Ensure that your domain resolves correctly to the OpenShift Router:

dig my-app.example.com

d) Validating TLS Configuration

If TLS is not working as expected, inspect the certificate details:

openssl s_client -connect my-app.example.com:443 -showcerts

5. Security Best Practices for OpenShift Routes

  • Use Re-encrypt Termination whenever backend encryption is required.
  • Implement Network Policies to restrict internal communication.
  • Rotate TLS Certificates Regularly to maintain security.
  • Enable HSTS (HTTP Strict Transport Security) to enforce HTTPS connections.

To enable HSTS, add the following annotation to your Route:

metadata:
  annotations:
    haproxy.router.openshift.io/hsts_header: max-age=31536000;includeSubDomains

Conclusion

OpenShift Routes are a robust mechanism for exposing applications externally, offering built-in TLS, load balancing, and flexible routing policies. Understanding their nuances—from termination types to advanced security configurations—ensures that your applications remain accessible, secure, and performant.

Key Takeaways:

  • ✔ OpenShift Routes provide more flexibility than Kubernetes Ingress
  • ✔ TLS termination modes (Edge, Passthrough, Re-encrypt) should be chosen based on security needs.
  • ✔ Custom TLS certificates enhance security and trust.
  • ✔ Debugging tools like oc logs, dig and opensll help diagnose Route issues.

Would you like to see additional real-world examples? Share your thoughts below!

Further Reading