Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 37 ยท Networking and Routes

Ingress and Ingress Controllers in OpenShift

Understand the OpenShift Ingress Operator, the default IngressController, how Kubernetes Ingress becomes a Route, router sharding and when to pick Ingress or Route.

Kubernetes defines an Ingress object for HTTP routing, but it needs a controller to do any work. OpenShift ships one by default: the Ingress Operator manages one or more IngressController objects, each running a set of HAProxy router pods. Routes and Ingress objects are both served by that same router, so you can use either one.

This lesson explains how the pieces fit, how an Ingress is translated into a Route, how to give different teams or traffic classes their own routers (sharding), and how to decide between Route and Ingress. Commands are read-only here; the runnable parts are Python stand-ins.

The default IngressController

Terminal
oc get ingresscontroller -n openshift-ingress-operator
oc get pods -n openshift-ingress
oc get ingresses.config/cluster -o yaml   # cluster-wide ingress config, incl. apps domain

The default controller is named default. Its main knobs live in spec:

YAML
apiVersion: operator.openshift.io/v1
kind: IngressController
metadata:
  name: default
  namespace: openshift-ingress-operator
spec:
  replicas: 3
  domain: apps.mycluster.example.com
  endpointPublishingStrategy:
    type: LoadBalancerService
  nodePlacement:
    nodeSelector:
      matchLabels:
        node-role.kubernetes.io/worker: ""

Scale the router by changing replicas, for example oc patch ingresscontroller/default -n openshift-ingress-operator --type=merge -p '{"spec":{"replicas":4}}'. The operator creates a Deployment, a Service of type LoadBalancer (cloud platforms) or uses HostNetwork/NodePort on bare metal, and keeps them in line with the spec.

Using Kubernetes Ingress

You may write a standard Ingress, and OpenShift's ingress-to-route controller creates a Route for each rule:

YAML
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop
  annotations:
    route.openshift.io/termination: edge
spec:
  rules:
    - host: shop.apps.mycluster.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: shop-web
                port:
                  number: 80

After applying it, oc get routes shows an auto-generated route owned by the Ingress. Edit the Ingress, not the generated route; manual changes to the route are overwritten. Only a subset of Ingress features is honored: path types and TLS secrets work, while controller-specific annotations of other ingress products (for example NGINX annotations) do not.

Python Stand-in: Ingress rules to Routes

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.

The real controller names routes differently (it uses a generated suffix), but the idea is the same: one Route per rule path, owned by the Ingress.

Route or Ingress?

Need Better choice
Weighted backends, passthrough and re-encrypt, per-route timeouts Route
Portability to other Kubernetes platforms, GitOps with generic charts Ingress
One object type for helm charts from the community Ingress
Fine control of HAProxy via haproxy.router.openshift.io/* annotations Route

Many charts expose an ingress toggle; enabling it on OpenShift works through the translation above. For platform-specific features, write a Route directly. The newer Gateway API is also being adopted in OpenShift, but Routes remain the stable core.

Sharding: several routers

One router fleet serving everything is simple, but you may want to separate internal and public traffic, or give a busy team its own router. Create an extra IngressController with its own domain and selectors that decide which routes it admits:

YAML
apiVersion: operator.openshift.io/v1
kind: IngressController
metadata:
  name: internal
  namespace: openshift-ingress-operator
spec:
  domain: internal.mycluster.example.com
  replicas: 2
  endpointPublishingStrategy:
    type: LoadBalancerService
    loadBalancer:
      scope: Internal
  routeSelector:
    matchLabels:
      type: internal

Label a route to place it on that shard:

Terminal
oc label route shop-admin type=internal

You can also use namespaceSelector to admit all routes from labeled projects. The default controller then needs a matching exclusion, or it will serve the route too.

Python Stand-in: which router admits a route?

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.

Checking what the router sees

Terminal
oc get route -A                       # all routes, hosts and admission
oc describe route shop-web            # status shows which router admitted it
oc logs -n openshift-ingress deploy/router-default   # HAProxy logs

oc describe route lists Admitted per router. A route stuck without admission usually has a host that another namespace already owns, or labels that no controller selects.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What manages the router pods in OpenShift?

    The Ingress Operator watches IngressController resources and deploys HAProxy routers for them.
  2. 2. What happens when you create a standard Kubernetes Ingress on OpenShift?

    OpenShift translates Ingress rules into Routes owned by the Ingress.
  3. 3. How do you place a route on a separate sharded router?

    Controllers admit routes whose labels match routeSelector or whose namespace matches namespaceSelector.
  4. 4. Which feature needs a Route rather than Ingress?

    Passthrough, re-encrypt and alternateBackends weights are Route features.

Summary

  • The Ingress Operator runs HAProxy routers defined by IngressController objects.
  • Ingress objects are converted into Routes; edit the Ingress, not the generated route.
  • Choose Routes for OpenShift-specific features and Ingress for portability.
  • Sharding uses extra controllers with routeSelector or namespaceSelector.
  • oc describe route shows which router admitted it.

Next: Security Context Constraints