An OpenShift Online 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 OpenShift Online router, or if using an unrelated host name you may need to modify its DNS records independently to resolve to the router.
You can create unsecured and secured 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:
Using the CLI, create an unsecured route. For OpenShift Online Starter, follow this example:
$ oc expose svc/frontend
For OpenShift Online Pro, follow this example, with
--hostname being optional:
$ oc expose svc/frontend --hostname=www.example.com
The new route inherits the name from the service unless you specify one
apiVersion: v1 kind: Route metadata: name: frontend spec: to: kind: Service name: frontend
For information on configuring routes using the CLI, see Route Types.
Unsecured routes are the default configuration, and are therefore the simplest
to set up.
offer security for connections to remain private. To create a secured HTTPS route
encrypted with the default certificate for OpenShift Online Pro
you can use the
create route command.
TLS is the replacement of SSL for HTTPS and other encrypted protocols.
For OpenShift Online Starter:
$ oc create route edge --service=frontend
apiVersion: v1 kind: Route metadata: name: frontend spec: to: kind: Service name: frontend tls: termination: edge
For OpenShift Online Pro, you can use your own certificate and key files from a CA. However, you can still omit the certificate and key files if you want to use the default certificate. With OpenShift Online Starter, you cannot specify a certificate and key.
For OpenShift Online Pro:
$ oc create route edge --service=frontend \ --cert=example.crt \ --key=example.key \ --ca-cert=ca.crt \ --hostname=www.example.com
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. To remove a passphrase from a keyfile, you can run:
# openssl rsa -in <passwordProtectedKey.key> -out <new.key>
Further information on all types of TLS termination as well as path-based routing are available in the Architecture section.
OpenShift Online 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.
You can set a cookie name to overwrite the default, auto-generated one for the route. 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.
Annotate the route with the desired cookie name:
$ oc annotate route <route_name> router.openshift.io/cookie_name="<your_cookie_name>"
For example, to specify
my_cookie as your new cookie name:
$ oc annotate route my_route router.openshift.io/cookie_name="my_cookie"
Save the cookie, and access the route:
$ curl $my_route -k -c /tmp/my_cookie
Routes are restricted in OpenShift Online Starter, but are not restricted in OpenShift Online Pro. Custom route hosts are permitted in OpenShift Online Pro. If using OpenShift Online Starter, the following host template is enforced on all user routes:
To determine the external address, run:
$ oc get route/<route-name>
Custom certificates are permitted in OpenShift Online Pro. In OpenShift Online 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 OpenShift Online Starter.
These restrictions are enforced by the API. Attempts to create routes with custom hosts or certificates will be rejected in OpenShift Online Starter. In OpenShift Online Pro, a default host is provided if the user does not specify a custom host.
Once your custom route is created in OpenShift Online Pro, you must update your DNS provider by creating a canonical name (CNAME) record. Your CNAME record should point your custom domain to the OpenShift Online router as the alias. The OpenShift Online router’s domain is different for every cluster.
CNAME records cannot be set for a naked domain (
In OpenShift Online Pro, you can view a created custom route to see the CNAME record that you must provide to your DNS provider.