Overview

An Digital Garage route exposes a service at a host name, like www.example.com, so that external clients can reach it by name.

DNS resolution for a host name is handled separately from routing; your administrator may have configured a cloud domain that will always correctly resolve to the Digital Garage router, or if using an unrelated host name you may need to modify its DNS records independently to resolve to the router.

Creating Routes

You can create unsecured and secured routes routes using the web console or the CLI.

Using the web console, you can navigate to the Routes page, found under the Applications section of the navigation.

Click Create Route to define and create a route in your project:

Creating a Route Using the Web Console
Figure 1. Creating a Route Using the Web Console

Using the CLI, the following example creates an unsecured route:

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

The new route inherits the name from the service unless you specify one using the --name option.

YAML Definition of the Unsecured Route Created Above
apiVersion: v1
kind: Route
metadata:
  name: frontend
spec:
  host: www.example.com
  to:
    kind: Service
    name: frontend
1 For path-based routing, specify a path component that can be compared against a URL.

Unsecured routes are the default configuration, and are therefore the simplest to set up. However, secured routes offer security for connections to remain private. To create a secured HTTPS route encrypted with a key and certificate (PEM-format files which you must generate and sign separately), you can use the create route command and optionally provide certificates and a key.

TLS is the replacement of SSL for HTTPS and other encrypted protocols.

$ oc create route edge --service=frontend \
    --cert=${MASTER_CONFIG_DIR}/ca.crt \
    --key=${MASTER_CONFIG_DIR}/ca.key \
    --ca-cert=${MASTER_CONFIG_DIR}/ca.crt \
    --hostname=www.example.com
YAML Definition of the Secured Route Created Above
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-----

Currently, password protected key files are not supported. HAProxy prompts for a password upon starting and does not have a way to automate this process. To remove a passphrase from a keyfile, you can run:

# openssl rsa -in <passwordProtectedKey.key> -out <new.key>

You can create a secured route without specifying a key and certificate, in which case the will be used for TLS termination.

TLS termination in Digital Garage relies on SNI for serving custom certificates. Any non-SNI traffic received on port 443 is handled with TLS termination and a default certificate, which may not match the requested host name, resulting in validation errors.

Further information on all types of TLS termination as well as path-based routing are available in the Architecture section.

Allowing Route Endpoints to Control Cookie Names

Digital Garage 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.

Digital Garage can use cookies to configure session persistence. The router 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 router which endpoint is handling the session, ensuring that client requests use the cookie so that they are routed to the same pod.

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 shed the requests from the client and redistribute them.

  1. Annotate the route with the desired cookie name:

    $ oc annotate route <route_name> router.openshift.io/<cookie_name>= “-<cookie_annotation>”

    For example, to annotate the cookie name of my_cookie to the my_route with the annotation of my_cookie_anno:

    $ oc annotate route my_route router.openshift.io/my_cookie= “-my_cookie_anno”
  2. Save the cookie, and access the route:

    $ curl $my_route -k -c /tmp/my_cookie

Restrictions

Routes are restricted in Digital Garage Starter, but are not restricted in Digital Garage Pro. Custom route hosts are permitted in Digital Garage Pro. If using Digital Garage Starter, the following host template is enforced on all user routes:

<route-name>-<namespace>.<external-address>

For example:

<route-name>-<namespace>.1d35.starter-us-east-1.openshiftapps.com

To determine the external address, run:

$ oc get route/<route-name>

Custom certificates are permitted in Digital Garage Pro. In Digital Garage Starter, only unencrypted routes, edge routes using the default certificate, and passthrough routes work. Edge and re-encrypt routes with custom certificates do not work in Digital Garage Starter.

These restrictions are enforced by the API. Attempts to create routes with custom hosts or certificates will be rejected in Digital Garage Starter. In Digital Garage Pro, a default host is provided if the user does not specify a custom host.

Update DNS for Custom Routes

Once your custom route is created in Digital Garage Pro, you must update your DNS provider by creating a canonical name (CNAME) record. Your CNAME record should point your custom domain to the Digital Garage router as the alias. The Digital Garage router’s domain is different for every cluster.

CNAME records cannot be set for a naked domain (example.com). A subdomain must be specified (www.example.com).

In Digital Garage Pro, you can view a created custom route to see the CNAME record that you must provide to your DNS provider.

View a created custom route to see the CNAME record