Chapter 22. Configuring Routes

Procedure

1. Create a project called hello-openshift by running the following command:

   $ oc new-project hello-openshift

2. 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

3. Create a service called hello-openshift by running the following command:

   $ oc expose pod/hello-openshift

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

   $ oc expose svc hello-openshift

Procedure

1. Create a project called hello-openshift by running the following command:

   $ oc new-project hello-openshift

2. 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

3. Create a service called hello-openshift by running the following command:

   $ oc expose pod/hello-openshift

4. 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.

5. 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

Procedure

1. 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

Procedure

1. Create a route definition and save it in a file called app-example-route.yaml:

   YAML definition of the created route with HTTP header directives

   apiVersion: route.openshift.io/v1
   kind: Route
   # ...
   spec:
     host: app.example.com
     tls:
       termination: edge
     to:
       kind: Service
       name: app-example
     httpHeaders:
       actions: 1
         response: 2
         - name: Content-Location 3
           action:
             type: Set 4
             set:
               value: /lang/en-us 5

   1

   The list of actions you want to perform on the HTTP headers.

   2

   The type of header you want to change. In this case, a response header.

   3

   The name of the header you want to change. For a list of available headers you can set or delete, see HTTP header configuration.

   4

   The type of action being taken on the header. This field can have the value Set or Delete.

   5

   When setting HTTP headers, you must provide a value. The value can be a string from a list of available directives for that header, for example DENY, or it can be a dynamic value that will be interpreted using HAProxy’s dynamic value syntax. In this case, the value is set to the relative location of the content.

2. Create a route to your existing web application using the newly created route definition:

   $ oc -n app-example create -f app-example-route.yaml

1. If the number of IP addresses and CIDR ranges in an allowlist exceeds 61, they are written into a separate file that is then referenced from haproxy.config. This file is stored in the var/lib/haproxy/router/whitelists folder.

   Note

   To ensure that the addresses are written to the allowlist, check that the full list of CIDR ranges are listed in the Ingress Controller configuration file. The etcd object size limit restricts how large a route annotation can be. Because of this, it creates a threshold for the maximum number of IP addresses and CIDR ranges that you can include in an allowlist.

Procedure

1. 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" 1
       route.openshift.io/destination-ca-certificate-secret: secret-ca-cert 2
   spec:
     rules:
     - host: www.example.com 3
       http:
         paths:
         - backend:
             service:
               name: frontend
               port:
                 number: 443
           path: /
           pathType: Prefix
     tls:
     - hosts:
       - www.example.com
       secretName: example-com-tls-certificate

   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.

   3

   When working with an Ingress object, you must specify an explicit hostname, unlike when working with routes. You can use the <host_name>.<cluster_ingress_domain> syntax, for example apps.openshiftdemos.com, to take advantage of the *.<cluster_ingress_domain> wildcard DNS record and serving certificate for the cluster. Otherwise, you must ensure that there is a DNS record for the chosen hostname.

   1. 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

      $ oc apply -f ingress.yaml

   2

   The route.openshift.io/destination-ca-certificate-secret can be used on an Ingress object to define a route with a custom destination certificate (CA). The annotation references a kubernetes secret, secret-ca-cert that will be inserted into the generated route.

   1. To specify a route object with a destination CA from an ingress object, you must create a kubernetes.io/tls or Opaque type secret with a certificate in PEM-encoded format in the data.tls.crt specifier of the secret.

2. List your routes:

   $ oc get routes

   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

   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
       destinationCACertificate: |
         -----BEGIN CERTIFICATE-----
         [...]
         -----END CERTIFICATE-----
     to:
       kind: Service
       name: frontend

Procedure

1. Create a YAML file for the Ingress object. In this example, the file is called example-ingress.yaml:

   YAML definition of an Ingress object

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: frontend
     ...
   spec:
     rules:
       ...
     tls:
     - {} 1

   1

   Use this exact syntax to specify TLS without specifying a custom certificate.

2. Create the Ingress object by running the following command:

   $ oc create -f example-ingress.yaml

Procedure

1. Add the route.openshift.io/destination-ca-certificate-secret to the Ingress annotations:

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: frontend
     annotations:
       route.openshift.io/termination: "reencrypt"
       route.openshift.io/destination-ca-certificate-secret: secret-ca-cert 1
   ...

   1

   The annotation references a kubernetes secret.

2. The secret referenced in this annotation will be inserted into the generated route.

   Example output

   apiVersion: route.openshift.io/v1
   kind: Route
   metadata:
     name: frontend
     annotations:
       route.openshift.io/termination: reencrypt
       route.openshift.io/destination-ca-certificate-secret: secret-ca-cert
   spec:
   ...
     tls:
       insecureEdgeTerminationPolicy: Redirect
       termination: reencrypt
       destinationCACertificate: |
         -----BEGIN CERTIFICATE-----
         [...]
         -----END CERTIFICATE-----
   ...

Procedure

1. To have the Ingress Controller serve traffic over IPv4/IPv6 to a workload, you can create a service YAML file or modify an existing service YAML file by setting the ipFamilies and ipFamilyPolicy fields. For example:

   Sample service YAML file

   apiVersion: v1
   kind: Service
   metadata:
     creationTimestamp: yyyy-mm-ddT00:00:00Z
     labels:
       name: <service_name>
       manager: kubectl-create
       operation: Update
       time: yyyy-mm-ddT00:00:00Z
     name: <service_name>
     namespace: <namespace_name>
     resourceVersion: "<resource_version_number>"
     selfLink: "/api/v1/namespaces/<namespace_name>/services/<service_name>"
     uid: <uid_number>
   spec:
     clusterIP: 172.30.0.0/16
     clusterIPs: 1
     - 172.30.0.0/16
     - <second_IP_address>
     ipFamilies: 2
     - IPv4
     - IPv6
     ipFamilyPolicy: RequireDualStack 3
     ports:
     - port: 8080
       protocol: TCP
       targetport: 8080
     selector:
       name: <namespace_name>
     sessionAffinity: None
     type: ClusterIP
   status:
     loadbalancer: {}

   1

   In a dual-stack instance, there are two different clusterIPs provided.

   2

   For a single-stack instance, enter IPv4 or IPv6. For a dual-stack instance, enter both IPv4 and IPv6.

   3

   For a single-stack instance, enter SingleStack. For a dual-stack instance, enter RequireDualStack.

   These resources generate corresponding endpoints. The Ingress Controller now watches endpointslices.

2. To view endpoints, enter the following command:

   $ oc get endpoints

3. To view endpointslices, enter the following command:

   $ oc get endpointslices

Procedure

1. Create a role in the same namespace as the secret to allow the router service account read access by running the following command:

   $ oc create role secret-reader --verb=get,list,watch --resource=secrets --resource-name=<secret-name> \ 1
   --namespace=<current-namespace> 2

   1

   Specify the actual name of your secret.

   2

   Specify the namespace where both your secret and route reside.

2. Create a rolebinding in the same namespace as the secret and bind the router service account to the newly created role by running the following command:

   $ oc create rolebinding secret-reader-binding --role=secret-reader --serviceaccount=openshift-ingress:router --namespace=<current-namespace> 1

   1

   Specify the namespace where both your secret and route reside.

3. Create a YAML file that defines the route and specifies the secret containing your certificate using the following example.

   YAML definition of the secure route

   apiVersion: route.openshift.io/v1
   kind: Route
   metadata:
     name: myedge
     namespace: test
   spec:
     host: myedge-test.apps.example.com
     tls:
       externalCertificate:
         name: <secret-name> 1
       termination: edge
       [...]
   [...]

   1

   Specify the actual name of your secret.

4. Create a route resource by running the following command:

   $ oc apply -f <route.yaml> 1

   1

   Specify the generated YAML filename.