Route configuration - Configuring Routes | Networking | OpenShift Container Platform 4.11

Creating an HTTP-based route
Creating a route for Ingress Controller sharding
Configuring route timeouts
HTTP Strict Transport Security
Throughput issue troubleshooting methods
Using cookies to keep route statefulness
- Annotating a route with a cookie
Path-based routes
Route-specific annotations
Configuring the route admission policy
Creating a route through an Ingress object
Creating a route using the destination CA certificate in the Ingress annotation
Configuring the OpenShift Container Platform Ingress Controller for dual-stack networking

Creating an HTTP-based route

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
```

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

Create a service called hello-openshift by running the following command:
```
$ oc expose pod/hello-openshift
```
Create an unsecured route to the hello-openshift application by running the following command:
```
$ oc expose svc hello-openshift
```

Verification

To verify that the route resource that you created, run the following command:
```
$ oc get routes -o yaml <name of resource> (1)
```
1 In this example, the route is named hello-openshift.

Sample 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> (1)
  port:
    targetPort: 8080
  to:
    kind: Service
    name: hello-openshift

<Ingress_Domain> is the default ingress domain name.

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

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

Creating a route for Ingress Controller sharding

A route allows you to host your application at a URL. In this case, the hostname is not set and the route uses a subdomain instead. When you specify a subdomain, you automatically use the domain of the Ingress Controller that exposes the route. For situations where a route is exposed by multiple Ingress Controllers, the route is hosted at multiple URLs.

The following procedure describes how to create a route for Ingress Controller sharding, using the hello-openshift application as an example.

Ingress Controller sharding is useful when balancing incoming traffic load among a set of Ingress Controllers and when isolating traffic to a specific Ingress Controller. For example, company A goes to one Ingress Controller and company B to another.

Prerequisites

You installed the OpenShift CLI (oc).
You are logged in as a project administrator.
You have a web application that exposes a port and an HTTP or TLS endpoint listening for traffic on the port.
You have configured the Ingress Controller for sharding.

Procedure

Create a project called hello-openshift by running the following command:
```
$ oc new-project hello-openshift
```

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

Create a service called hello-openshift by running the following command:
```
$ oc expose pod/hello-openshift
```

Create a route definition called hello-openshift-route.yaml:

YAML definition of the created route for sharding:

apiVersion: route.openshift.io/v1
kind: Route
metadata:
  labels:
    type: sharded (1)
  name: hello-openshift-edge
  namespace: hello-openshift
spec:
  subdomain: hello-openshift (2)
  tls:
    termination: edge
  to:
    kind: Service
    name: hello-openshift

1	Both the label key and its corresponding label value must match the ones specified in the Ingress Controller. In this example, the Ingress Controller has the label key and value `type: sharded`.
2	The route will be exposed using the value of the `subdomain` field. When you specify the `subdomain` field, you must leave the hostname unset. If you specify both the `host` and `subdomain` fields, then the route will use the value of the `host` field, and ignore the `subdomain` field.

Use hello-openshift-route.yaml to create a route to the hello-openshift application by running the following command:
```
$ oc -n hello-openshift create -f hello-openshift-route.yaml
```

Verification

Get the status of the route with the following command:

$ oc -n hello-openshift get routes/hello-openshift-edge -o yaml

The resulting Route resource should look similar to the following:

Example output

apiVersion: route.openshift.io/v1
kind: Route
metadata:
  labels:
    type: sharded
  name: hello-openshift-edge
  namespace: hello-openshift
spec:
  subdomain: hello-openshift
  tls:
    termination: edge
  to:
    kind: Service
    name: hello-openshift
status:
  ingress:
  - host: hello-openshift.<apps-sharded.basedomain.example.net> (1)
    routerCanonicalHostname: router-sharded.<apps-sharded.basedomain.example.net> (2)
    routerName: sharded (3)

1	The hostname the Ingress Controller, or router, uses to expose the route. The value of the `host` field is automatically determined by the Ingress Controller, and uses its domain. In this example, the domain of the Ingress Controller is `<apps-sharded.basedomain.example.net>`.
2	The hostname of the Ingress Controller.
3	The name of the Ingress Controller. In this example, the Ingress Controller has the name `sharded`.

Configuring route timeouts

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> (1)
```
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
```

HTTP Strict Transport Security

HTTP Strict Transport Security (HSTS) policy is a security enhancement, which signals to the browser client that only HTTPS traffic is allowed on the route host. HSTS also optimizes web traffic by signaling HTTPS transport is required, without using HTTP redirects. HSTS is useful for speeding up interactions with websites.

When HSTS policy is enforced, HSTS adds a Strict Transport Security header to HTTP and HTTPS responses from the site. You can use the insecureEdgeTerminationPolicy value in a route to redirect HTTP to HTTPS. When HSTS is enforced, the client changes all requests from the HTTP URL to HTTPS before the request is sent, eliminating the need for a redirect.

Cluster administrators can configure HSTS to do the following:

Enable HSTS per-route
Disable HSTS per-route
Enforce HSTS per-domain, for a set of domains, or use namespace labels in combination with domains

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

Enabling HTTP Strict Transport Security per-route

HTTP strict transport security (HSTS) is implemented in the HAProxy template and applied to edge and re-encrypt routes that have the haproxy.router.openshift.io/hsts_header annotation.

Prerequisites

You are logged in to the cluster with a user with administrator privileges for the project.
You installed the oc CLI.

Procedure

To enable HSTS on a route, add the haproxy.router.openshift.io/hsts_header value to the edge-terminated or re-encrypt route. You can use the oc annotate tool to do this by running the following command:

$ oc annotate route <rout_name> -n <namespace> --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=31536000;\ (1)
includeSubDomains;preload"

1	In this example, the maximum age is set to `31536000` ms, which is approximately eight and a half hours.

In this example, the equal sign (=) is in quotes. This is required to properly execute the annotate command.

Example route configured with an annotation

apiVersion: route.openshift.io/v1
kind: Route
metadata:
  annotations:
    haproxy.router.openshift.io/hsts_header: max-age=31536000;includeSubDomains;preload   (1) (2) (3)
...
spec:
  host: def.abc.com
  tls:
    termination: "reencrypt"
    ...
  wildcardPolicy: "Subdomain"

1	Required. `max-age` measures the length of time, in seconds, that the HSTS policy is in effect. If set to `0`, it negates the policy.
2	Optional. When included, `includeSubDomains` tells the client that all subdomains of the host must have the same HSTS policy as the host.
3	Optional. When `max-age` is greater than 0, you can add `preload` in `haproxy.router.openshift.io/hsts_header` to allow 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, even before they have interacted with the site. Without `preload` set, browsers must have interacted with the site over HTTPS, at least once, to get the header.

Disabling HTTP Strict Transport Security per-route

To disable HTTP strict transport security (HSTS) per-route, you can set the max-age value in the route annotation to 0.

Prerequisites

You are logged in to the cluster with a user with administrator privileges for the project.
You installed the oc CLI.

Procedure

To disable HSTS, set the max-age value in the route annotation to 0, by entering the following command:

$ oc annotate route <rout_name> -n <namespace> --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=0"

You can alternatively apply the following YAML to create the config map:

Example of disabling HSTS per-route

metadata:
  annotations:
    haproxy.router.openshift.io/hsts_header: max-age=0

To disable HSTS for every route in a namespace, enter the following command:

$ oc annotate route --all -n <namespace> --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=0"

Verification

To query the annotation for all routes, enter the following command:

$ oc get route  --all-namespaces -o go-template='{{range .items}}{{if .metadata.annotations}}{{$a := index .metadata.annotations "haproxy.router.openshift.io/hsts_header"}}{{$n := .metadata.name}}{{with $a}}Name: {{$n}} HSTS: {{$a}}{{"\n"}}{{else}}{{""}}{{end}}{{end}}{{end}}'

Example output

Name: routename HSTS: max-age=0

Enforcing HTTP Strict Transport Security per-domain

To enforce HTTP Strict Transport Security (HSTS) per-domain for secure routes, add a requiredHSTSPolicies record to the Ingress spec to capture the configuration of the HSTS policy.

If you configure a requiredHSTSPolicy to enforce HSTS, then any newly created route must be configured with a compliant HSTS policy annotation.

To handle upgraded clusters with non-compliant HSTS routes, you can update the manifests at the source and apply the updates.

You cannot use oc expose route or oc create route commands to add a route in a domain that enforces HSTS, because the API for these commands does not accept annotations.

HSTS cannot be applied to insecure, or non-TLS routes, even if HSTS is requested for all routes globally.

Prerequisites

You are logged in to the cluster with a user with administrator privileges for the project.
You installed the oc CLI.

Procedure

Edit the Ingress config file:

$ oc edit ingresses.config.openshift.io/cluster

Example HSTS policy

apiVersion: config.openshift.io/v1
kind: Ingress
metadata:
  name: cluster
spec:
  domain: 'hello-openshift-default.apps.username.devcluster.openshift.com'
  requiredHSTSPolicies: (1)
  - domainPatterns: (2)
    - '*hello-openshift-default.apps.username.devcluster.openshift.com'
    - '*hello-openshift-default2.apps.username.devcluster.openshift.com'
    namespaceSelector: (3)
      matchLabels:
        myPolicy: strict
    maxAge: (4)
      smallestMaxAge: 1
      largestMaxAge: 31536000
    preloadPolicy: RequirePreload (5)
    includeSubDomainsPolicy: RequireIncludeSubDomains (6)
  - domainPatterns: (2)
    - 'abc.example.com'
    - '*xyz.example.com'
    namespaceSelector:
      matchLabels: {}
    maxAge: {}
    preloadPolicy: NoOpinion
    includeSubDomainsPolicy: RequireNoIncludeSubDomains

1	Required. `requiredHSTSPolicies` are validated in order, and the first matching `domainPatterns` applies.
2	Required. You must specify at least one `domainPatterns` hostname. Any number of domains can be listed. You can include multiple sections of enforcing options for different `domainPatterns`.
3	Optional. If you include `namespaceSelector`, it must match the labels of the project where the routes reside, to enforce the set HSTS policy on the routes. Routes that only match the `namespaceSelector` and not the `domainPatterns` are not validated.
4	Required. `max-age` measures the length of time, in seconds, that the HSTS policy is in effect. This policy setting allows for a smallest and largest `max-age` to be enforced. The `largestMaxAge` value must be between `0` and `2147483647`. It can be left unspecified, which means no upper limit is enforced. The `smallestMaxAge` value must be between `0` and `2147483647`. Enter `0` to disable HSTS for troubleshooting, otherwise enter `1` if you never want HSTS to be disabled. It can be left unspecified, which means no lower limit is enforced.
5	Optional. Including `preload` in `haproxy.router.openshift.io/hsts_header` allows external services to include this site in their HSTS preload lists. 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 need to interact at least once with the site to get the header. `preload` can be set with one of the following: `RequirePreload`: `preload` is required by the `RequiredHSTSPolicy`. `RequireNoPreload`: `preload` is forbidden by the `RequiredHSTSPolicy`. `NoOpinion`: `preload` does not matter to the `RequiredHSTSPolicy`.
6	Optional. `includeSubDomainsPolicy` can be set with one of the following: `RequireIncludeSubDomains`: `includeSubDomains` is required by the `RequiredHSTSPolicy`. `RequireNoIncludeSubDomains`: `includeSubDomains` is forbidden by the `RequiredHSTSPolicy`. `NoOpinion`: `includeSubDomains` does not matter to the `RequiredHSTSPolicy`.

You can apply HSTS to all routes in the cluster or in a particular namespace by entering the oc annotate command.
- To apply HSTS to all routes in the cluster, enter the oc annotate command. For example:
  $ oc annotate route --all --all-namespaces --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=31536000"
- To apply HSTS to all routes in a particular namespace, enter the oc annotate command. For example:
  $ oc annotate route --all -n my-namespace --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=31536000"

Verification

You can review the HSTS policy you configured. For example:

To review the maxAge set for required HSTS policies, enter the following command:

$ oc get clusteroperator/ingress -n openshift-ingress-operator -o jsonpath='{range .spec.requiredHSTSPolicies[*]}{.spec.requiredHSTSPolicies.maxAgePolicy.largestMaxAge}{"\n"}{end}'

To review the HSTS annotations on all routes, enter the following command:

$ oc get route  --all-namespaces -o go-template='{{range .items}}{{if .metadata.annotations}}{{$a := index .metadata.annotations "haproxy.router.openshift.io/hsts_header"}}{{$n := .metadata.name}}{{with $a}}Name: {{$n}} HSTS: {{$a}}{{"\n"}}{{else}}{{""}}{{end}}{{end}}{{end}}'

Example output

Name: <_routename_> HSTS: max-age=31536000;preload;includeSubDomains

Throughput issue troubleshooting methods

Sometimes applications deployed by using OpenSh