Chapter 15. Configuring Routes

15.1. Route configuration
Copy link

15.1.1. Creating an HTTP-based route
Copy link

A route allows you to host your application at a public URL. It can either be secure or unsecured, depending on the network security configuration of your application. An HTTP-based route is an unsecured route that uses the basic HTTP routing protocol and exposes a service on an unsecured application port.

The following procedure describes how to create a simple HTTP-based route to a web application, using the hello-openshift application as an example.

Prerequisites

You installed the OpenShift CLI (oc).
You are logged in as an administrator.
You have a web application that exposes a port and a TCP endpoint listening for traffic on the port.

Procedure

Create a project called hello-openshift by running the following command:
```
oc new-project hello-openshift
```
```
$ oc new-project hello-openshift
```
Copy to Clipboard Toggle word wrap

Create a pod in the project by running the following command:

oc create -f https://raw.githubusercontent.com/openshift/origin/master/examples/hello-openshift/hello-pod.json

$ oc create -f https://raw.githubusercontent.com/openshift/origin/master/examples/hello-openshift/hello-pod.json

Copy to Clipboard

Toggle word wrap

Create a service called hello-openshift by running the following command:
```
oc expose pod/hello-openshift
```
```
$ oc expose pod/hello-openshift
```
Copy to Clipboard Toggle word wrap

Create an unsecured route to the hello-openshift application by running the following command:

oc expose svc hello-openshift

$ oc expose svc hello-openshift

Copy to Clipboard

Toggle word wrap

If you examine the resulting Route resource, it should look similar to the following:

YAML definition of the created unsecured route:

apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: hello-openshift
spec:
  host: hello-openshift-hello-openshift.<Ingress_Domain> 
  port:
    targetPort: 8080
  to:
    kind: Service
    name: hello-openshift

apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: hello-openshift
spec:
  host: hello-openshift-hello-openshift.<Ingress_Domain>


  port:
    targetPort: 8080
  to:
    kind: Service
    name: hello-openshift

Copy to Clipboard

Toggle word wrap

1: <Ingress_Domain> is the default ingress domain name.

Note

To display your default ingress domain, run the following command:

oc get ingresses.config/cluster -o jsonpath={.spec.domain}

$ oc get ingresses.config/cluster -o jsonpath={.spec.domain}

Copy to Clipboard

Toggle word wrap

15.1.2. Configuring route timeouts
Copy link

You can configure the default timeouts for an existing route when you have services in need of a low timeout, which is required for Service Level Availability (SLA) purposes, or a high timeout, for cases with a slow back end.

Prerequisites

You need a deployed Ingress Controller on a running cluster.

Procedure

Using the oc annotate command, add the timeout to the route:

oc annotate route <route_name> \
    --overwrite haproxy.router.openshift.io/timeout=<timeout><time_unit>

$ oc annotate route <route_name> \
    --overwrite haproxy.router.openshift.io/timeout=<timeout><time_unit>

Copy to Clipboard

Toggle word wrap

1: Supported time units are microseconds (us), milliseconds (ms), seconds (s), minutes (m), hours (h), or days (d).

The following example sets a timeout of two seconds on a route named myroute:

oc annotate route myroute --overwrite haproxy.router.openshift.io/timeout=2s

$ oc annotate route myroute --overwrite haproxy.router.openshift.io/timeout=2s

Copy to Clipboard

Toggle word wrap

15.1.3. Enabling HTTP strict transport security
Copy link

HTTP Strict Transport Security (HSTS) policy is a security enhancement, which ensures that only HTTPS traffic is allowed on the host. Any HTTP requests are dropped by default. This is useful for ensuring secure interactions with websites, or to offer a secure application for the user’s benefit.

When HSTS is enabled, HSTS adds a Strict Transport Security header to HTTPS responses from the site. You can use the insecureEdgeTerminationPolicy value in a route to redirect to send HTTP to HTTPS. However, when HSTS is enabled, the client changes all requests from the HTTP URL to HTTPS before the request is sent, eliminating the need for a redirect. This is not required to be supported by the client, and can be disabled by setting max-age=0.

Important

HSTS works only with secure routes (either edge terminated or re-encrypt). The configuration is ineffective on HTTP or passthrough routes.

Procedure

To enable HSTS on a route, add the haproxy.router.openshift.io/hsts_header value to the edge terminated or re-encrypt route:
```
apiVersion: v1
kind: Route
metadata:
  annotations:
    haproxy.router.openshift.io/hsts_header: max-age=31536000;includeSubDomains;preload   
```
```
apiVersion: v1
kind: Route
metadata:
  annotations:
    haproxy.router.openshift.io/hsts_header: max-age=31536000;includeSubDomains;preload 
```
1
```
 
```
2
```
 
```
3
Copy to Clipboard Toggle word wrap
1
max-age is the only required parameter. It measures the length of time, in seconds, that the HSTS policy is in effect. The client updates max-age whenever a response with a HSTS header is received from the host. When max-age times out, the client discards the policy.
2
includeSubDomains is optional. When included, it tells the client that all subdomains of the host are to be treated the same as the host.
3
preload is optional. When max-age is greater than 0, then including preload in haproxy.router.openshift.io/hsts_header allows external services to include this site in their HSTS preload lists. For example, sites such as Google can construct a list of sites that have preload set. Browsers can then use these lists to determine which sites they can communicate with over HTTPS, before they have interacted with the site. Without preload set, browsers must have interacted with the site over HTTPS to get the header.

15.1.4. Troubleshooting throughput issues
Copy link

Sometimes applications deployed through OpenShift Container Platform can cause network throughput issues such as unusually high latency between specific services.

Use the following methods to analyze performance issues if pod logs do not reveal any cause of the problem:

Use a packet analyzer, such as ping or tcpdump to analyze traffic between a pod and its node.
For example, run the tcpdump tool on each pod while reproducing the behavior that led to the issue. Review the captures on both sides to compare send and receive timestamps to analyze the latency of traffic to and from a pod. Latency can occur in OpenShift Container Platform if a node interface is overloaded with traffic from other pods, storage devices, or the data plane.
```
tcpdump -s 0 -i any -w /tmp/dump.pcap host <podip 1> && host <podip 2>
```
```
$ tcpdump -s 0 -i any -w /tmp/dump.pcap host <podip 1> && host <podip 2> 
```
1
Copy to Clipboard Toggle word wrap
1
podip is the IP address for the pod. Run the oc get pod <pod_name> -o wide command to get the IP address of a pod.
tcpdump generates a file at /tmp/dump.pcap containing all traffic between these two pods. Ideally, run the analyzer shortly before the issue is reproduced and stop the analyzer shortly after the issue is finished reproducing to minimize the size of the file. You can also run a packet analyzer between the nodes (eliminating the SDN from the equation) with:
```
tcpdump -s 0 -i any -w /tmp/dump.pcap port 4789
```
```
$ tcpdump -s 0 -i any -w /tmp/dump.pcap port 4789
```
Copy to Clipboard Toggle word wrap
Use a bandwidth measuring tool, such as iperf, to measure streaming throughput and UDP throughput. Run the tool from the pods first, then from the nodes, to locate any bottlenecks.
- For information on installing and using iperf, see this Red Hat Solution.

15.1.5. Using cookies to keep route statefulness
Copy link

OpenShift Container Platform provides sticky sessions, which enables stateful application traffic by ensuring all traffic hits the same endpoint. However, if the endpoint pod terminates, whether through restart, scaling, or a change in configuration, this statefulness can disappear.

OpenShift Container Platform can use cookies to configure session persistence. The Ingress controller selects an endpoint to handle any user requests, and creates a cookie for the session. The cookie is passed back in the response to the request and the user sends the cookie back with the next request in the session. The cookie tells the Ingress Controller which endpoint is handling the session, ensuring that client requests use the cookie so that they are routed to the same pod.

Note

Cookies cannot be set on passthrough routes, because the HTTP traffic cannot be seen. Instead, a number is calculated based on the source IP address, which determines the backend.

If backends change, the traffic can be directed to the wrong server, making it less sticky. If you are using a load balancer, which hides source IP, the same number is set for all connections and traffic is sent to the same pod.

15.1.5.1. Annotating a route with a cookie
Copy link

You can set a cookie name to overwrite the default, auto-generated one for the route. This allows the application receiving route traffic to know the cookie name. By deleting the cookie it can force the next request to re-choose an endpoint. So, if a server was overloaded it tries to remove the requests from the client and redistribute them.

Procedure

Annotate the route with the specified cookie name:
```
oc annotate route <route_name> router.openshift.io/cookie_name="<cookie_name>"
```
```
$ oc annotate route <route_name> router.openshift.io/cookie_name="<cookie_name>"
```
Copy to Clipboard Toggle word wrap
where:
<route_name>
Specifies the name of the route.
<cookie_name>
Specifies the name for the cookie.
For example, to annotate the route my_route with the cookie name my_cookie:
```
oc annotate route my_route router.openshift.io/cookie_name="my_cookie"
```
```
$ oc annotate route my_route router.openshift.io/cookie_name="my_cookie"
```
Copy to Clipboard Toggle word wrap
Capture the route hostname in a variable:
```
ROUTE_NAME=$(oc get route <route_name> -o jsonpath='{.spec.host}')
```
```
$ ROUTE_NAME=$(oc get route <route_name> -o jsonpath='{.spec.host}')
```
Copy to Clipboard Toggle word wrap
where:
<route_name>
Specifies the name of the route.
Save the cookie, and then access the route:
```
curl $ROUTE_NAME -k -c /tmp/cookie_jar
```
```
$ curl $ROUTE_NAME -k -c /tmp/cookie_jar
```
Copy to Clipboard Toggle word wrap
Use the cookie saved by the previous command when connecting to the route:
```
curl $ROUTE_NAME -k -b /tmp/cookie_jar
```
```
$ curl $ROUTE_NAME -k -b /tmp/cookie_jar
```
Copy to Clipboard Toggle word wrap

15.1.6. Path-based routes
Copy link

Path-based routes specify a path component that can be compared against a URL, which requires that the traffic for the route be HTTP based. Thus, multiple routes can be served using the same hostname, each with a different path. Routers should match routes based on the most specific path to the least. However, this depends on the router implementation.

The following table shows example routes and their accessibility:

Expand

Table 15.1. Route availability
Route	When Compared to	Accessible
www.example.com/test	www.example.com/test	Yes
www.example.com/test	www.example.com	No
www.example.com/test and www.example.com	www.example.com/test	Yes
www.example.com/test and www.example.com	www.example.com	Yes
www.example.com	www.example.com/text	Yes (Matched by the host, not the route)
www.example.com	www.example.com	Yes

An unsecured route with a path

apiVersion: v1
kind: Route
metadata:
  name: route-unsecured
spec:
  host: www.example.com
  path: "/test" 
  to:
    kind: Service
    name: service-name

apiVersion: v1
kind: Route
metadata:
  name: route-unsecured
spec:
  host: www.example.com
  path: "/test"


  to:
    kind: Service
    name: service-name

Copy to Clipboard

Toggle word wrap

1: The path is the only added attribute for a path-based route.

Note

Path-based routing is not available when using passthrough TLS, as the router does not terminate TLS in that case and cannot read the contents of the request.

15.1.7. Route-specific annotations
Copy link

The Ingress Controller can set the default options for all the routes it exposes. An individual route can override some of these defaults by providing specific configurations in its annotations. Red Hat does not support adding a route annotation to an operator-managed route.

Important

To create a whitelist with multiple source IPs or subnets, use a space-delimited list. Any other delimiter type causes the list to be ignored without a warning or error message.

Expand

Table 15.2. Route annotations
Variable	Description	Environment variable used as default
`haproxy.router.openshift.io/balance`	Sets the load-balancing algorithm. Available options are `source`, `roundrobin`, and `leastconn`.	`ROUTER_TCP_BALANCE_SCHEME` for passthrough routes. Otherwise, use `ROUTER_LOAD_BALANCE_ALGORITHM`.
`haproxy.router.openshift.io/disable_cookies`	Disables the use of cookies to track related connections. If set to `true` or `TRUE`, the balance algorithm is used to choose which back-end serves connections for each incoming HTTP request.
`router.openshift.io/cookie_name`	Specifies an optional cookie to use for this route. The name must consist of any combination of upper and lower case letters, digits, "_", and "-". The default is the hashed internal key name for the route.
`haproxy.router.openshift.io/pod-concurrent-connections`	Sets the maximum number of connections that are allowed to a backing pod from a router. Note: If there are multiple pods, each can have this many connections. If you have multiple routers, there is no coordination among them, each may connect this many times. If not set, or set to 0, there is no limit.
`haproxy.router.openshift.io/rate-limit-connections`	Setting `true` or `TRUE` enables rate limiting functionality which is implemented through stick-tables on the specific backend per route. Note: Using this annotation provides basic protection against distributed denial-of-service (DDoS) attacks.
`haproxy.router.openshift.io/rate-limit-connections.concurrent-tcp`	Limits the number of concurrent TCP connections made through the same source IP address. It accepts a numeric value. Note: Using this annotation provides basic protection against distributed denial-of-service (DDoS) attacks.
`haproxy.router.openshift.io/rate-limit-connections.rate-http`	Limits the rate at which a client with the same source IP address can make HTTP requests. It accepts a numeric value. Note: Using this annotation provides basic protection against distributed denial-of-service (DDoS) attacks.
`haproxy.router.openshift.io/rate-limit-connections.rate-tcp`	Limits the rate at which a client with the same source IP address can make TCP connections. It accepts a numeric value. Note: Using this annotation provides basic protection against distributed denial-of-service (DDoS) attacks.
`haproxy.router.openshift.io/timeout`	Sets a server-side timeout for the route. (TimeUnits)	`ROUTER_DEFAULT_SERVER_TIMEOUT`
`haproxy.router.openshift.io/timeout-tunnel`	This timeout applies to a tunnel connection, for example, WebSocket over cleartext, edge, reencrypt, or passthrough routes. With cleartext, edge, or reencrypt route types, this annotation is applied as a timeout tunnel with the existing timeout value. For the passthrough route types, the annotation takes precedence over any existing timeout value set.	`ROUTER_DEFAULT_TUNNEL_TIMEOUT`
`ingresses.config/cluster ingress.operator.openshift.io/hard-stop-after`	You can set either an IngressController or the ingress config . This annotation redeploys the router and configures the HA proxy to emit the haproxy `hard-stop-after` global option, which defines the maximum time allowed to perform a clean soft-stop.	`ROUTER_HARD_STOP_AFTER`
`router.openshift.io/haproxy.health.check.interval`	Sets the interval for the back-end health checks. (TimeUnits)	`ROUTER_BACKEND_CHECK_INTERVAL`
`haproxy.router.openshift.io/ip_whitelist`	Sets a whitelist for the route. The whitelist is a space-separated list of IP addresses and CIDR ranges for the approved source addresses. Requests from IP addresses that are not in the whitelist are dropped. The maximum number of IP addresses and CIDR ranges allowed in a whitelist is 61.
`haproxy.router.openshift.io/hsts_header`	Sets a Strict-Transport-Security header for the edge terminated or re-encrypt route.
`haproxy.router.openshift.io/log-send-hostname`	Sets the `hostname` field in the Syslog header. Uses the hostname of the system. `log-send-hostname` is enabled by default if any Ingress API logging method, such as sidecar or Syslog facility, is enabled for the router.
`haproxy.router.openshift.io/rewrite-target`	Sets the rewrite path of the request on the backend.
`router.openshift.io/cookie-same-site`	Sets a value to restrict cookies. The values are: `Lax`: cookies are transferred between the visited site and third-party sites. `Strict`: cookies are restricted to the visited site. `None`: cookies are restricted to the visited site. This value is applicable to re-encrypt and edge routes only. For more information, see the SameSite cookies documentation.
`haproxy.router.openshift.io/set-forwarded-headers`	Sets the policy for handling the `Forwarded` and `X-Forwarded-For` HTTP headers per route. The values are: `append`: appends the header, preserving any existing header. This is the default value. `replace`: sets the header, removing any existing header. `never`: never sets the header, but preserves any existing header. `if-none`: sets the header if it is not already set.	`ROUTER_SET_FORWARDED_HEADERS`

Note

Environment variables cannot be edited.

Router timeout variables

TimeUnits are represented by a number followed by the unit: us *(microseconds), ms (milliseconds, default), s (seconds), m (minutes), h *(hours), d (days).

The regular expression is: [1-9][0-9]*(us\|ms\|s\|m\|h\|d).

Expand

Variable	Default	Description
`ROUTER_BACKEND_CHECK_INTERVAL`	`5000ms`	Length of time between subsequent liveness checks on back ends.
`ROUTER_CLIENT_FIN_TIMEOUT`	`1s`	Controls the TCP FIN timeout period for the client connecting to the route. If the FIN sent to close the connection does not answer within the given time, HAProxy closes the connection. This is harmless if set to a low value and uses fewer resources on the router.
`ROUTER_DEFAULT_CLIENT_TIMEOUT`	`30s`	Length of time that a client has to acknowledge or send data.
`ROUTER_DEFAULT_CONNECT_TIMEOUT`	`5s`	The maximum connection time.
`ROUTER_DEFAULT_SERVER_FIN_TIMEOUT`	`1s`	Controls the TCP FIN timeout from the router to the pod backing the route.
`ROUTER_DEFAULT_SERVER_TIMEOUT`	`30s`	Length of time that a server has to acknowledge or send data.
`ROUTER_DEFAULT_TUNNEL_TIMEOUT`	`1h`	Length of time for TCP or WebSocket connections to remain open. This timeout period resets whenever HAProxy reloads.
`ROUTER_SLOWLORIS_HTTP_KEEPALIVE`	`300s`	Set the maximum time to wait for a new HTTP request to appear. If this is set too low, it can cause problems with browsers and applications not expecting a small `keepalive` value. Some effective timeout values can be the sum of certain variables, rather than the specific expected timeout. For example, `ROUTER_SLOWLORIS_HTTP_KEEPALIVE` adjusts `timeout http-keep-alive`. It is set to `300s` by default, but HAProxy also waits on `tcp-request inspect-delay`, which is set to `5s`. In this case, the overall timeout would be `300s` plus `5s`.
`ROUTER_SLOWLORIS_TIMEOUT`	`10s`	Length of time the transmission of an HTTP request can take.
`RELOAD_INTERVAL`	`5s`	Allows the minimum frequency for the router to reload and accept new changes.
`ROUTER_METRICS_HAPROXY_TIMEOUT`	`5s`	Timeout for the gathering of HAProxy metrics.

A route setting custom timeout

apiVersion: v1
kind: Route
metadata:
  annotations:
    haproxy.router.openshift.io/timeout: 5500ms 
...

apiVersion: v1
kind: Route
metadata:
  annotations:
    haproxy.router.openshift.io/timeout: 5500ms

...

Copy to Clipboard

Toggle word wrap

1: Specifies the new timeout with HAProxy supported units (us, ms, s, m, h, d). If the unit is not provided, ms is the default.

Note

Setting a server-side timeout value for passthrough routes too low can cause WebSocket connections to timeout frequently on that route.

A route that allows only one specific IP address

metadata:
  annotations:
    haproxy.router.openshift.io/ip_whitelist: 192.168.1.10

metadata:
  annotations:
    haproxy.router.openshift.io/ip_whitelist: 192.168.1.10

Copy to Clipboard

Toggle word wrap

A route that allows several IP addresses

metadata:
  annotations:
    haproxy.router.openshift.io/ip_whitelist: 192.168.1.10 192.168.1.11 192.168.1.12

metadata:
  annotations:
    haproxy.router.openshift.io/ip_whitelist: 192.168.1.10 192.168.1.11 192.168.1.12

Copy to Clipboard

Toggle word wrap

A route that allows an IP address CIDR network

metadata:
  annotations:
    haproxy.router.openshift.io/ip_whitelist: 192.168.1.0/24

metadata:
  annotations:
    haproxy.router.openshift.io/ip_whitelist: 192.168.1.0/24

Copy to Clipboard

Toggle word wrap

A route that allows both IP an address and IP address CIDR networks

metadata:
  annotations:
    haproxy.router.openshift.io/ip_whitelist: 180.5.61.153 192.168.1.0/24 10.0.0.0/8

metadata:
  annotations:
    haproxy.router.openshift.io/ip_whitelist: 180.5.61.153 192.168.1.0/24 10.0.0.0/8

Copy to Clipboard

Toggle word wrap

A route specifying a rewrite target

apiVersion: v1
kind: Route
metadata:
  annotations:
    haproxy.router.openshift.io/rewrite-target: / 
...

apiVersion: v1
kind: Route
metadata:
  annotations:
    haproxy.router.openshift.io/rewrite-target: /

...

Copy to Clipboard

Toggle word wrap

1: Sets / as rewrite path of the request on the backend.

Setting the haproxy.router.openshift.io/rewrite-target annotation on a route specifies that the Ingress Controller should rewrite paths in HTTP requests using this route before forwarding the requests to the backend application. The part of the request path that matches the path specified in spec.path is replaced with the rewrite target specified in the annotation.

The following table provides examples of the path rewriting behavior for various combinations of spec.path, request path, and rewrite target.

Expand

Table 15.3. rewrite-target examples:
Route.spec.path	Request path	Rewrite target	Forwarded request path
/foo	/foo	/	/
/foo	/foo/	/	/
/foo	/foo/bar	/	/bar
/foo	/foo/bar/	/	/bar/
/foo	/foo	/bar	/bar
/foo	/foo/	/bar	/bar/
/foo	/foo/bar	/baz	/baz/bar
/foo	/foo/bar/	/baz	/baz/bar/
/foo/	/foo	/	N/A (request path does not match route path)
/foo/	/foo/	/	/
/foo/	/foo/bar	/	/bar

15.1.8. Configuring the route admission policy
Copy link

Administrators and application developers can run applications in multiple namespaces with the same domain name. This is for organizations where multiple teams develop microservices that are exposed on the same hostname.

Warning

Allowing claims across namespaces should only be enabled for clusters with trust between namespaces, otherwise a malicious user could take over a hostname. For this reason, the default admission policy disallows hostname claims across namespaces.

Prerequisites

Cluster administrator privileges.

Procedure

Edit the .spec.routeAdmission field of the ingresscontroller resource variable using the following command:

oc -n openshift-ingress-operator patch ingresscontroller/default --patch '{"spec":{"routeAdmission":{"namespaceOwnership":"InterNamespaceAllowed"}}}' --type=merge

$ oc -n openshift-ingress-operator patch ingresscontroller/default --patch '{"spec":{"routeAdmission":{"namespaceOwnership":"InterNamespaceAllowed"}}}' --type=merge

Copy to Clipboard

Toggle word wrap

Sample Ingress Controller configuration

spec:
  routeAdmission:
    namespaceOwnership: InterNamespaceAllowed
...

spec:
  routeAdmission:
    namespaceOwnership: InterNamespaceAllowed
...

Copy to Clipboard

Toggle word wrap

15.1.9. Creating a route through an Ingress object
Copy link

Some ecosystem components have an integration with Ingress resources but not with route resources. To cover this case, OpenShift Container Platform automatically creates managed route objects when an Ingress object is created. These route objects are deleted when the corresponding Ingress objects are deleted.

Procedure

Define an Ingress object in the OpenShift Container Platform console or by entering the oc create command:

YAML Definition of an Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: frontend
  annotations:
    route.openshift.io/termination: "reencrypt" 
spec:
  rules:
  - host: www.example.com
    http:
      paths:
      - backend:
          service:
            name: frontend
            port:
              number: 443
        path: /
        pathType: Prefix
  tls:
  - hosts:
    - www.example.com
    secretName: example-com-tls-certificate

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: frontend
  annotations:
    route.openshift.io/termination: "reencrypt"


spec:
  rules:
  - host: www.example.com
    http:
      paths:
      - backend:
          service:
            name: frontend
            port:
              number: 443
        path: /
        pathType: Prefix
  tls:
  - hosts:
    - www.example.com
    secretName: example-com-tls-certificate

Copy to Clipboard

Toggle word wrap

1

The route.openshift.io/termination annotation can be used to configure the spec.tls.termination field of the Route as Ingress has no field for this. The accepted values are edge, passthrough and reencrypt. All other values are silently ignored. When the annotation value is unset, edge is the default route. The TLS certificate details must be defined in the template file to implement the default edge route.

If you specify the passthrough value in the route.openshift.io/termination annotation, set path to '' and pathType to ImplementationSpecific in the spec:

  spec:
    rules:
    - host: www.example.com
      http:
        paths:
        - path: ''
          pathType: ImplementationSpecific
          backend:
            service:
              name: frontend
              port:
                number: 443

  spec:
    rules:
    - host: www.example.com
      http:
        paths:
        - path: ''
          pathType: ImplementationSpecific
          backend:
            service:
              name: frontend
              port:
                number: 443

Copy to Clipboard

Toggle word wrap

oc apply -f ingress.yaml

$ oc apply -f ingress.yaml

Copy to Clipboard

Toggle word wrap

List your routes:

oc get routes

$ oc get routes

Copy to Clipboard

Toggle word wrap

The result includes an autogenerated route whose name starts with frontend-:

NAME             HOST/PORT         PATH    SERVICES    PORT    TERMINATION          WILDCARD
frontend-gnztq   www.example.com           frontend    443     reencrypt/Redirect   None

NAME             HOST/PORT         PATH    SERVICES    PORT    TERMINATION          WILDCARD
frontend-gnztq   www.example.com           frontend    443     reencrypt/Redirect   None

Copy to Clipboard

Toggle word wrap

If you inspect this route, it looks this:

YAML Definition of an autogenerated route

apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: frontend-gnztq
  ownerReferences:
  - apiVersion: networking.k8s.io/v1
    controller: true
    kind: Ingress
    name: frontend
    uid: 4e6c59cc-704d-4f44-b390-617d879033b6
spec:
  host: www.example.com
  path: /
  port:
    targetPort: https
  tls:
    certificate: |
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----
    insecureEdgeTerminationPolicy: Redirect
    key: |
      -----BEGIN RSA PRIVATE KEY-----
      [...]
      -----END RSA PRIVATE KEY-----
    termination: reencrypt
  to:
    kind: Service
    name: frontend

apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: frontend-gnztq
  ownerReferences:
  - apiVersion: networking.k8s.io/v1
    controller: true
    kind: Ingress
    name: frontend
    uid: 4e6c59cc-704d-4f44-b390-617d879033b6
spec:
  host: www.example.com
  path: /
  port:
    targetPort: https
  tls:
    certificate: |
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----
    insecureEdgeTerminationPolicy: Redirect
    key: |
      -----BEGIN RSA PRIVATE KEY-----
      [...]
      -----END RSA PRIVATE KEY-----
    termination: reencrypt
  to:
    kind: Service
    name: frontend

Copy to Clipboard

Toggle word wrap

15.2. Secured routes
Copy link

Secure routes provide the ability to use several types of TLS termination to serve certificates to the client. The following sections describe how to create re-encrypt, edge, and passthrough routes with custom certificates.

Important

If you create routes in Microsoft Azure through public endpoints, the resource names are subject to restriction. You cannot create resources that use certain terms. For a list of terms that Azure restricts, see Resolve reserved resource name errors in the Azure documentation.

15.2.1. Creating a re-encrypt route with a custom certificate
Copy link

You can configure a secure route using reencrypt TLS termination with a custom certificate by using the oc create route command.

Prerequisites

You must have a certificate/key pair in PEM-encoded files, where the certificate is valid for the route host.
You may have a separate CA certificate in a PEM-encoded file that completes the certificate chain.
You must have a separate destination CA certificate in a PEM-encoded file.
You must have a service that you want to expose.

Note

Password protected key files are not supported. To remove a passphrase from a key file, use the following command:

openssl rsa -in password_protected_tls.key -out tls.key

$ openssl rsa -in password_protected_tls.key -out tls.key

Copy to Clipboard

Toggle word wrap

Procedure

This procedure creates a Route resource with a custom certificate and reencrypt TLS termination. The following assumes that the certificate/key pair are in the tls.crt and tls.key files in the current working directory. You must also specify a destination CA certificate to enable the Ingress Controller to trust the service’s certificate. You may also specify a CA certificate if needed to complete the certificate chain. Substitute the actual path names for tls.crt, tls.key, cacert.crt, and (optionally) ca.crt. Substitute the name of the Service resource that you want to expose for frontend. Substitute the appropriate hostname for www.example.com.

Create a secure Route resource using reencrypt TLS termination and a custom certificate:

oc create route reencrypt --service=frontend --cert=tls.crt --key=tls.key --dest-ca-cert=destca.crt --ca-cert=ca.crt --hostname=www.example.com

$ oc create route reencrypt --service=frontend --cert=tls.crt --key=tls.key --dest-ca-cert=destca.crt --ca-cert=ca.crt --hostname=www.example.com

Copy to Clipboard

Toggle word wrap

If you examine the resulting Route resource, it should look similar to the following:

YAML Definition of the Secure Route

apiVersion: v1
kind: Route
metadata:
  name: frontend
spec:
  host: www.example.com
  to:
    kind: Service
    name: frontend
  tls:
    termination: reencrypt
    key: |-
      -----BEGIN PRIVATE KEY-----
      [...]
      -----END PRIVATE KEY-----
    certificate: |-
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----
    caCertificate: |-
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----
    destinationCACertificate: |-
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----

apiVersion: v1
kind: Route
metadata:
  name: frontend
spec:
  host: www.example.com
  to:
    kind: Service
    name: frontend
  tls:
    termination: reencrypt
    key: |-
      -----BEGIN PRIVATE KEY-----
      [...]
      -----END PRIVATE KEY-----
    certificate: |-
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----
    caCertificate: |-
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----
    destinationCACertificate: |-
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----

Copy to Clipboard

Toggle word wrap

See oc create route reencrypt --help for more options.

15.2.2. Creating an edge route with a custom certificate
Copy link

You can configure a secure route using edge TLS termination with a custom certificate by using the oc create route command. With an edge route, the Ingress Controller terminates TLS encryption before forwarding traffic to the destination pod. The route specifies the TLS certificate and key that the Ingress Controller uses for the route.

Prerequisites

You must have a certificate/key pair in PEM-encoded files, where the certificate is valid for the route host.
You may have a separate CA certificate in a PEM-encoded file that completes the certificate chain.
You must have a service that you want to expose.

Note

Password protected key files are not supported. To remove a passphrase from a key file, use the following command:

openssl rsa -in password_protected_tls.key -out tls.key

$ openssl rsa -in password_protected_tls.key -out tls.key

Copy to Clipboard

Toggle word wrap

Procedure

This procedure creates a Route resource with a custom certificate and edge TLS termination. The following assumes that the certificate/key pair are in the tls.crt and tls.key files in the current working directory. You may also specify a CA certificate if needed to complete the certificate chain. Substitute the actual path names for tls.crt, tls.key, and (optionally) ca.crt. Substitute the name of the service that you want to expose for frontend. Substitute the appropriate hostname for www.example.com.

Create a secure Route resource using edge TLS termination and a custom certificate.

oc create route edge --service=frontend --cert=tls.crt --key=tls.key --ca-cert=ca.crt --hostname=www.example.com

$ oc create route edge --service=frontend --cert=tls.crt --key=tls.key --ca-cert=ca.crt --hostname=www.example.com

Copy to Clipboard

Toggle word wrap

If you examine the resulting Route resource, it should look similar to the following:

YAML Definition of the Secure Route

apiVersion: v1
kind: Route
metadata:
  name: frontend
spec:
  host: www.example.com
  to:
    kind: Service
    name: frontend
  tls:
    termination: edge
    key: |-
      -----BEGIN PRIVATE KEY-----
      [...]
      -----END PRIVATE KEY-----
    certificate: |-
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----
    caCertificate: |-
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----

apiVersion: v1
kind: Route
metadata:
  name: frontend
spec:
  host: www.example.com
  to:
    kind: Service
    name: frontend
  tls:
    termination: edge
    key: |-
      -----BEGIN PRIVATE KEY-----
      [...]
      -----END PRIVATE KEY-----
    certificate: |-
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----
    caCertificate: |-
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----

Copy to Clipboard

Toggle word wrap

See oc create route edge --help for more options.

15.2.3. Creating a passthrough route
Copy link

You can configure a secure route using passthrough termination by using the oc create route command. With passthrough termination, encrypted traffic is sent straight to the destination without the router providing TLS termination. Therefore no key or certificate is required on the route.

Prerequisites

You must have a service that you want to expose.

Procedure

Create a Route resource:

oc create route passthrough route-passthrough-secured --service=frontend --port=8080

$ oc create route passthrough route-passthrough-secured --service=frontend --port=8080

Copy to Clipboard

Toggle word wrap

If you examine the resulting Route resource, it should look similar to the following:

A Secured Route Using Passthrough Termination

apiVersion: v1
kind: Route
metadata:
  name: route-passthrough-secured 
spec:
  host: www.example.com
  port:
    targetPort: 8080
  tls:
    termination: passthrough 
    insecureEdgeTerminationPolicy: None 
  to:
    kind: Service
    name: frontend

apiVersion: v1
kind: Route
metadata:
  name: route-passthrough-secured


spec:
  host: www.example.com
  port:
    targetPort: 8080
  tls:
    termination: passthrough


    insecureEdgeTerminationPolicy: None


  to:
    kind: Service
    name: frontend

Copy to Clipboard

Toggle word wrap

1: The name of the object, which is limited to 63 characters.
2: The termination field is set to passthrough. This is the only required tls field.
3: Optional insecureEdgeTerminationPolicy. The only valid values are None, Redirect, or empty for disabled.

The destination pod is responsible for serving certificates for the traffic at the endpoint. This is currently the only method that can support requiring client certificates, also known as two-way authentication.

Chapter 15. Configuring Routes

15.1. Route configuration
Copy link

15.1.1. Creating an HTTP-based route
Copy link

15.1.2. Configuring route timeouts
Copy link

15.1.3. Enabling HTTP strict transport security
Copy link

15.1.4. Troubleshooting throughput issues
Copy link

15.1.5. Using cookies to keep route statefulness
Copy link

15.1.6. Path-based routes
Copy link

15.1.7. Route-specific annotations
Copy link

15.1.8. Configuring the route admission policy
Copy link

15.1.9. Creating a route through an Ingress object
Copy link

15.2. Secured routes
Copy link

15.2.1. Creating a re-encrypt route with a custom certificate
Copy link

15.2.2. Creating an edge route with a custom certificate
Copy link

15.2.3. Creating a passthrough route
Copy link

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

Chapter 15. Configuring Routes

15.1. Route configurationCopy linkLink copied to clipboard!

15.1.1. Creating an HTTP-based routeCopy linkLink copied to clipboard!

15.1.2. Configuring route timeoutsCopy linkLink copied to clipboard!

15.1.3. Enabling HTTP strict transport securityCopy linkLink copied to clipboard!

15.1.4. Troubleshooting throughput issuesCopy linkLink copied to clipboard!

15.1.5. Using cookies to keep route statefulnessCopy linkLink copied to clipboard!

15.1.5.1. Annotating a route with a cookieCopy linkLink copied to clipboard!

15.1.6. Path-based routesCopy linkLink copied to clipboard!

15.1.7. Route-specific annotationsCopy linkLink copied to clipboard!

15.1.8. Configuring the route admission policyCopy linkLink copied to clipboard!

15.1.9. Creating a route through an Ingress objectCopy linkLink copied to clipboard!

15.2. Secured routesCopy linkLink copied to clipboard!

15.2.1. Creating a re-encrypt route with a custom certificateCopy linkLink copied to clipboard!

15.2.2. Creating an edge route with a custom certificateCopy linkLink copied to clipboard!

15.2.3. Creating a passthrough routeCopy linkLink copied to clipboard!

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

15.1. Route configuration
Copy link

15.1.1. Creating an HTTP-based route
Copy link

15.1.2. Configuring route timeouts
Copy link

15.1.3. Enabling HTTP strict transport security
Copy link

15.1.4. Troubleshooting throughput issues
Copy link

15.1.5. Using cookies to keep route statefulness
Copy link

15.1.5.1. Annotating a route with a cookie
Copy link

15.1.6. Path-based routes
Copy link

15.1.7. Route-specific annotations
Copy link

15.1.8. Configuring the route admission policy
Copy link

15.1.9. Creating a route through an Ingress object
Copy link

15.2. Secured routes
Copy link

15.2.1. Creating a re-encrypt route with a custom certificate
Copy link

15.2.2. Creating an edge route with a custom certificate
Copy link

15.2.3. Creating a passthrough route
Copy link