$ oc new-project hello-openshift
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.
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.
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
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 . |
apiVersion: route.openshift.io/v1
kind: Route
metadata:
name: hello-openshift
spec:
host: hello-openshift-hello-openshift.<Ingress_Domain> (1)
port:
targetPort: 8080 (2)
to:
kind: Service
name: hello-openshift
1 | <Ingress_Domain> is the default ingress domain name. The ingresses.config/cluster object is created during the installation and cannot be changed. If you want to specify a different domain, you can specify an alternative cluster domain using the appsDomain option. |
||
2 | targetPort is the target port on pods that is selected by the service that this route points to.
|
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.
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.
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
:
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
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:
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 . |
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.
You need a deployed Ingress Controller on a running cluster.
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 (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. |
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.
You are logged in to the cluster with a user with administrator privileges for the project.
You installed the oc
CLI.
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 <route_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 ( |
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 |