Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 37 ยท Networking and Routes

Routes in OpenShift: Exposing Apps with the Router

Learn OpenShift Routes: oc expose, hostnames, path-based routing, weighted blue-green traffic, annotations, the default router and how to troubleshoot a 503.

A service is only reachable inside the cluster. To let users reach your app from a browser, OpenShift uses a Route. A route maps a public hostname (and optionally a path) to a service. It is an OpenShift object that predates Kubernetes Ingress and is still the preferred way to publish applications on the platform.

Routes are served by the router, an HAProxy-based ingress controller running in the openshift-ingress project. The router watches Route objects, writes HAProxy configuration, and sends traffic to the pod IPs directly (not through the service IP), which lets it keep sticky sessions and balance per pod.

You cannot run a cluster here. The oc commands and YAML are read-only, and the runnable code is a Python stand-in that models how a router picks a backend.

Creating a route

The quickest way is oc expose:

Terminal
oc expose service/shop-api
oc get route shop-api

OpenShift generates a hostname from the route name, the project and the cluster's apps domain:

TEXT
shop-api-shop.apps.mycluster.example.com

To choose the host yourself:

Terminal
oc expose service/shop-api --hostname=api.example.com

The matching YAML:

YAML
apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: shop-api
spec:
  host: api.example.com
  to:
    kind: Service
    name: shop-api
    weight: 100
  port:
    targetPort: http      # a named service port

A custom host needs a DNS record (a wildcard *.apps... or a CNAME) pointing at the router's load balancer. The generated hosts work out of the box because the cluster owns the wildcard record.

Path-based routing

Several routes can share one host when they use different paths:

Terminal
oc create route edge api   --service=shop-api --hostname=shop.example.com --path=/api
oc create route edge web   --service=shop-web --hostname=shop.example.com --path=/

The router chooses the route with the longest matching path. Paths are prefix matches, so /api also matches /api/orders. Remember that the path is passed unchanged to the pod unless you add a rewrite annotation.

Python Stand-in: pick a route by longest path

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.

Weighted routes and blue-green releases

A route can send traffic to up to four services with weights, which makes canary and blue-green releases simple:

YAML
spec:
  to:
    kind: Service
    name: shop-api-v1
    weight: 90
  alternateBackends:
    - kind: Service
      name: shop-api-v2
      weight: 10

Or from the command line:

Terminal
oc set route-backends shop-api shop-api-v1=90 shop-api-v2=10
oc set route-backends shop-api shop-api-v1=0 shop-api-v2=100   # finish the cutover

Weights are shares of the total, not percentages, so 1 and 3 means 25% and 75%. A weight of 0 keeps the backend registered but sends no new traffic.

Python Stand-in: weighted backends

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.

Useful route annotations

Annotations tune the router without changing the app:

Annotation Effect
haproxy.router.openshift.io/timeout Server-side timeout, for example 60s
haproxy.router.openshift.io/balance roundrobin, leastconn or source
haproxy.router.openshift.io/rewrite-target Rewrite the path sent to the pod
haproxy.router.openshift.io/ip_whitelist Allow only listed client IPs/CIDRs
router.openshift.io/cookie_name Name of the sticky session cookie
Terminal
oc annotate route shop-api haproxy.router.openshift.io/timeout=120s

Troubleshooting the dreaded 503

"Application is not available" comes from the router when it has no healthy backend for the host. Check in this order:

  1. oc get route shop-api shows an Admitted condition? A route can be rejected for a host conflict.
  2. oc get endpoints shop-api is not empty (see the service lesson).
  3. The route's targetPort matches a real port of the service.
  4. For TLS routes, the certificate or termination type matches what the pod serves (TLS termination).
  5. oc get pods -n openshift-ingress to confirm the router pods are running.
flowchart LR
  U["Browser"] -->|"api.example.com"| LB["Load balancer"]
  LB --> R["Router (HAProxy)"]
  R -->|"/api"| A["shop-api pods"]
  R -->|"/"| W["shop-web pods"]

The router chooses the backend by host and path, then talks to pod IPs directly.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which component serves OpenShift routes?

    Routes are implemented by the default Ingress Controller, which runs HAProxy router pods in openshift-ingress.
  2. 2. Two routes share a host: one with path / and one with /api. A request for /api/items goes to

    The router picks the route with the longest matching path prefix.
  3. 3. A route has backends with weights 1 and 3. What share goes to the second backend?

    Weights are relative shares: 3 out of a total of 4 is 75%.
  4. 4. You see 'Application is not available'. What do you check first?

    The page means the router found no healthy backend, so verify admission, endpoints and the target port.

Summary

  • A route publishes a service under a hostname through the HAProxy router.
  • oc expose service/NAME creates one with a generated host.
  • Longest path wins when several routes share a host.
  • alternateBackends and oc set route-backends give weighted releases.
  • Annotations tune timeouts, balancing and access.

Next: TLS termination on routes