OpenShift Route

Openshift is a cloud-based Kubernetes service by RedHat. OpenShift routes enable access to pods (one or
more containers deployed in a cluster) from external resources.
In most cases, applications deployed on OpenShift expose external endpoints to the outside of the
cluster through a router.

For example, if your Kubernetes workload is
a web API (or any other interface external users need to access), you need to provide a route to the
particular
service or pod within OpenShift to access the required application or service. Each route consists of a
name (limited to 63 characters), a service selector,
and an optional security configuration.

To help you better understand the topic, we’ll take a closer look at the types of OpenShift routes and
different methods for configuration and troubleshooting.

Types of OpenShift Routes

There are two types of OpenShift routes:

1. HTTP routes (unsecured routes)
2. HTTPS routes (secured routes)

Let’s start by looking at an unsecured route example.

Unsecured OpenShift Routes

Unsecured Routes in OpenShift use plaintext HTTP communication. You can create OpenShift routes through
GUI/web console or CLI (command line interface). Below, we’ll walk through both methods

How to Create an Unsecured Route by Using Web Console

To create a route using the Web Console, navigate to the “Routes” page under the “Application” section.
Select the “Create Route” option to configure and create the route.

How to Create an Unsecured Route Using CLI

Use the following command to create an unsecured route

$oc expose svc/service --hostname=www.example.com
                

This command exposes the service against the URL www.example.com. External users will be redirected to
the service named service when accessing the URL www.example.com.

Below is the YAML definition for Unsecured Route Object:

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

Unsecured routes are much easier to maintain because they do not require a key or certificate.

OpenShift Path-Based Routes

Path-Based routes allow for a path to be specified within the route. It is then compared against a URL to
either allow or
disallow the traffic. Traffic for a Path-Based route should be HTTP-based (unsecured). The same hostname
can be used to
configure multiple routes, each with its path. The URL is compared to the routes, and the most specific
route (best match)
is chosen. In the case of multiple routes, the comparison will move to the following route until the
best match is found.
This is all configurable, and the comparison criteria can be configured in the router. The hostname and
paths are sent
back to the server for it to respond to its requests successfully.

For example, if the route www.example.com/test is compared to the URL www.example.com/test
it will allow the traffic. However, it will not allow traffic compared to a URL of www.example.com.

On the other hand, if the route www.example.com is compared to the URL www.example.com/test,
it will allow traffic based on the comparison match with the host and not the route.

Here is the YAML for an unsecured route with a path:

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

📝 Note: defining a route is the only additional attribute in path-based routing. Path-based routing
is not secured and does not support TLS termination.

For more examples, visit the OpenShift Path-based Routing documentation.

OpenShift Secured Routes

As the name suggests, Secured Routes are secured with TLS by providing a key and certificate. Secure
routes offer various TLS terminations to serve certificates to the client. A TLS termination is
the process of decrypting encrypted traffic. In OpenShift, TLS termination means terminating TLS
encryption before passing the traffic to the required service or pod. Routers support edge, passthrough,
and re-encryption termination.

TLS Termination in OpenShift uses SNI (Server Name Indication). SNI is an extension of the Transport
Layer Security (TLS)
network protocol. The client indicates which hostname it is trying to connect to at the beginning of the
TLS handshake.

Non-SNI traffic routed to the secure port (default 443) is assigned a default certificate that most
likely will not match the hostname, resulting in an authentication error.

You can learn more about secured routes in the OpenShift Route documentation.

OpenShift and the SNI Communication Flow

Below is an overview of an SNI communication flow:

Secured routes can use one of three types of secure TLS termination. The type of termination is
determined by where the encryption is being terminated.
The three termination types are:

1. Edge Termination – Terminates encryption at the router.
2. Passthrough Termination – Termination is passed from the router straight to the pod.
3. Re-encryption Termination – Is like Edge Termination, but it adds encapsulation.

In the sections below, we’ll take a closer look at each type of termination.

Edge Termination

Edge termination terminates the encryption at the router. All communication till the router is secured,
and any communication from the router to the endpoints is not.
Since the encryption in edge termination is terminated at the router, the TLS certificate must be added
to the route. If no certificate
is specified, the router’s default certificate is used and will likely result in an authentication
error.

The screenshot below shows how edge termination is configured using a GUI. Note that there is an option
in the screenshot below to deal with “Insecure traffic”.
Edge termination allows three different ways to treat insecure traffic. It can either be blocked,
allowed, or redirected.

The following command is used to create a Secure Route with Edge Termination

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

Note: Certificate/Key pair must be created in PEM-encoded format and should exist in the path
folder before running the above command.

Below is the YAML for a Secured Route using Edge Termination:

apiVersion: route.openshift.io/v1
                    kind: Route
                    metadata:
                      name: route-edge-secured                         (1)
                    spec:
                      host: www.example.com                            
                      to:
                        kind: Service
                        name: route-edge-secured                            
                      tls:
                        termination: edge                              (2)  
                        key: |-                                        (3)
                          -----BEGIN PRIVATE KEY-----
                          [...]
                          -----END PRIVATE KEY-----
                        certificate: |-                                (4)             
                          -----BEGIN CERTIFICATE-----
                          [...]
                          -----END CERTIFICATE-----
                        caCertificate: |-                              (5)          
                          -----BEGIN CERTIFICATE-----
                          [...]
                          -----END CERTIFICATE-----                                                 
                

1. The name field is used for naming the object and has a limit of 63 characters.
2. The termination field is edge for edge termination.
3. The key field is where the contents of the PEM key are entered.
4. The certificate field is for the contents of the certificate in PEM format.
5. caCertificate is optional but it may be required to enter the CA (Certificate Authority) cert for successful authentication.

insecureEdgeTerminationPolicy is the attribute used to configure what happens
with this type of traffic. The three values representing the goal discussed above are None or empty, Allow or Redirect.

Below is the YAML for A Secured Route using Edge Termination allowing HTTP Traffic:

apiVersion: route.openshift.io/v1
                    kind: Route
                    metadata:
                      name: route-edge-secured-allow-insecure         (1)
                    spec:
                      host: www.example.com                                 
                      to:
                        kind: Service
                        name: service-name 
                      tls:
                        termination: edge                             (2) 
                        insecureEdgeTerminationPolicy: Allow          (3)
                        [ ... ]
                    

1. The name field is used for naming the object and has a limit of 63 characters.
2. The termination field is edge for Edge Termination.
3. insecureEdgeTerminationPolicy field is used to configure what happens with the insecure traffic.
   In the example YAML file above, insecure traffic is allowed.

Below is the YAML for a Secured Route Using Edge Termination redirecting HTTP traffic to HTTPS:

apiVersion: route.openshift.io/v1
                    kind: Route
                    metadata:
                      name: route-edge-secured-redirect-insecure      (1)
                    spec:
                      host: www.example.com
                      to:
                        kind: Service
                        name: service-name  
                      tls:
                        Termination: edge                             (2)                            
                        insecureEdgeTerminationPolicy: Redirect       (3) 
                        [ ... ]
                    

1. The name field is used for naming the object and has a limit of 63 characters.
2. The termination field is edge for Edge Termination.
3. insecureEdgeTerminationPolicy field is used to configure what happens with the insecure traffic.
   In the example YAML file above, insecure traffic is Redirected to HTTPS.

Passthrough Termination

In Passthrough Termination, the termination is passed on from the router straight to the pod. The
pod is then responsible for providing the certificate and decrypting the traffic. Since termination
is not happening on the router, certificates are not part of the route.

Passthrough Termination provides end-to-end encryption. This is the only type of termination that
requires the client to have a certificate. It is also known as “two-way authentication”. The
screenshot below shows how to configure Passthrough Termination using GUI.

Even though Passthrough Termination is being used, there is still an option for “Insecure traffic”.
The only options available for “Insecure traffic” when using Passthrough termination are “empty” or
“redirect”. There is no option to add the certificate because the Pod provides the certificate for
Passthrough Termination.

The following command is used to create passthrough termination:

$oc create route passthrough route-passthrough --service=service-name --port=1234

Below is the YAML for a Secured Route using Passthrough Termination:

apiVersion: route.openshift.io/v1
                    kind: Route
                    metadata:
                      name: route-passthrough                 (1)
                    spec:
                      host: www.example.com
                      Port:
                        targetPort: 1234  
                      to:
                        kind: Service
                        name: service-name 
                      tls:
                        termination: passthrough              (2)                                                  
                

1. The name field is used for naming the object and has a limit of 63 characters.
2. The termination field is passthrough for Passthrough Termination.

Re-encryption Termination

Re-encryption is Edge Termination with encapsulation. The termination happens at the
router the same way it does in Edge Termination. However, instead of forwarding the
insecure traffic to the Pod, blocking it, or redirecting it (which can be specified
using insecureEdgeTerminationPolicy field), the router re-encrypts the traffic before
sending it off to the destination.

The re-encryption certificate can use a different certificate depending on the endpoint
requirement. This secures the entire path, even the internal communication

The screenshot below shows how Re-encryption Termination is configured using the OpenShift GUI.

The following command can be used to create a Secured Re-encrypt route

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

Note: Certificate/Key pair must be created in PEM-encoded format and should exist in the path folder before running the above command.

Below is the YAML for a Secured Route using Re-Encrypt Termination:

apiVersion: v1
                    kind: Route
                    metadata:
                      name: route-pt-secured 
                    spec:
                      host: www.example.com
                      to:
                        kind: Service
                        name: route-pt-secured                           (1)                                
                      tls:
                        termination: reencrypt                           (2)
                        key: [as in edge termination]
                        certificate: [as in edge termination]
                        caCertificate: [as in edge termination]
                        destinationCACertificate: |-                     (3)
                          -----BEGIN CERTIFICATE-----
                          [...]
                          -----END CERTIFICATE-----                                                  
                

1. The name field is used for naming the object and has a limit of 63 characters.
2. The termination field is set to reencrypt for Re-encryption Termination.
3. The destinationCACertificate field specifies the certificate for re-encryption, which
   will encrypt the traffic leaving the router to the Pod after the initial TLS termination on the router.
   If this field is left empty, the router will automatically use the certificate generated by the
   Certificate Authority configured to provide a certificate for this service. This saves the need
   for adding a certificate for every new path or router.

Since Re-encryption Termination is the same as Edge Termination for the initial TLS termination, its routes will
have insecureEdgeTerminationPolicy with all the same values as Edge-Terminated routes.

Basic Troubleshooting of OpenShift Routes and Applications

To help you get started with basic troubleshooting for OpenShift routes and applications,
let’s assume you have a service configured in a cluster and a user is trying to access
this service from outside the cluster. They can’t access the service and you need to
figure out why. Below, we’ll walk through some steps to help troubleshoot.

You know there needs to be a process configured to listen on a public IP for any external user
attempting to access the service for this to work. A route is also required for the traffic
inside the cluster if an attempt to reach the service has been made externally.

The command given below is run on the machine where the issue occurs to determine if the
service is running. This is used if the HTTP service is unavailable from outside the cluster.

curl -kv http://link.example.com:8000/bar                               
                    

Next, you should check if DNS is working. Only do this if the previous command returns output suggesting that the
service is running internally, but there may b an issue with DNS.

dig +short link.example.com                              
                    

The command above should resolve the given URL to an IP address. This shows that the
URL can be resolved externally. If it doesn’t resolve, there is an issue with the DNS.

However, if the URL resolves or it starts to resolve after fixing the DNS issue, and the service is still
not accessible externally, you should continue troubleshooting. The next step is to telnet to the resolved
IP address against the port your service is running on.

telnet10.20.30.40 8000                          
                

The command should result in this output.

Trying 10.20.30.40...
                    Connected to 10.20.30.40                            
                

If the router is not listening on the specified port, it will return the following error.

Trying 10.20.30.40... 
                    telnet: connect to address 10.20.30.40: Connection refused                           
                

Or the following error if there is no service listening on the IP address.

Trying 10.20.30.40... 
                    telnet: connect to address 10.20.30.40: Connection timed out                         
                

In either case, we will then need to troubleshoot the router.
You can find information on OpenShift network troubleshooting
here.

To check if the application route is working, run the oc get route command. This command lists the running
routes in the current namespace. If it gives the output and shows that the route is working,
there is no issue in the route.

If the oc get route command shows that the route is not working, then run the command oc describe route
"route name" to get a detailed description of the issue. This will help to identify and fix the issue.

That covers the basics of OpenShift route and application troubleshooting.
For a deeper dive, see the Troubleshooting section of the OpenShift admin guide.

Conclusion

OpenShift allows different types of routes to be configured depending on the use case.
With the ever-growing security challenges, the focus on the Zero Trust security
principle is the way forward for organizations. Even though OpenShift allows certain
route types to be configured without end-to-end encryption, it is best to keep the
environment as secure as possible and use Passthrough and Re-encryption Termination
whenever possible.