Creating basic routes - Ingress and load balancing | Networking

Creating an HTTP-based route
Path-based routes
Creating a route for Ingress Controller sharding
Creating a route through an Ingress object

If you have unencrypted HTTP, you can create a basic route with a route object.

Creating an HTTP-based route

You can use the following procedure to create a simple HTTP-based route to a web application, using the hello-openshift application as an example.

You can create a route to host your application at a public URL. The route 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.

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 hello-openshift
```
Example YAML definition of the created unsecured route
```
apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: hello-openshift
spec:
  host: www.example.com
  port:
    targetPort: 8080
  to:
    kind: Service
    name: hello-openshift
```
where:
host

Specifies an alias DNS record that points to the service. This field can be any valid DNS name, such as www.example.com. The DNS name must follow DNS952 subdomain conventions. If not specified, a route name is automatically generated.

targetPort
Specifies the target port on pods that is selected by the service that this route points to.
To display your default ingress domain, run the following command:

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

Path-based routes

To serve multiple applications by using a single hostname, configure path-based routes. This HTTP-based configuration directs traffic to specific services by comparing the URL path component, ensuring requests match the most specific route defined.

The following table shows example routes and their accessibility:

Table 1. Route availability
Route	When compared to	Accessible
www.example.com/test	www.example.com/test	Yes
www.example.com/test	www.example.com	No
www.example.com/test and www.example.com	www.example.com/test	Yes
www.example.com/test and www.example.com	www.example.com	Yes
www.example.com	www.example.com/text	Yes (Matched by the host, not the route)
www.example.com	www.example.com	Yes

Example of an unsecured route with a path

apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: route-unsecured
spec:
  host: www.example.com
  path: "/test"
  to:
    kind: Service
    name: service-name

spec.host: Specifies the path attribute for a path-based route.

Path-based routing is not available when using passthrough TLS, as the router does not terminate TLS in that case and cannot read the contents of the request.

Creating a route for Ingress Controller sharding

To host applications at specific URLs and balance traffic load in OKD, configure Ingress Controller sharding. By sharding, you can isolate traffic for specific workloads or tenants, ensuring efficient resource management across your cluster.

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

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
  name: hello-openshift-edge
  namespace: hello-openshift
spec:
  subdomain: hello-openshift
  tls:
    termination: edge
  to:
    kind: Service
    name: hello-openshift
```
where:

type

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

subdomain

Specifies the route gets exposed by 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 uses 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>
    routerCanonicalHostname: router-sharded.<apps-sharded.basedomain.example.net>
    routerName: sharded
```
where:

host

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

<apps-sharded.basedomain.example.net>

Specifies the hostname of the Ingress Controller. If the hostname is not set, the route can use a subdomain instead. When you specify a subdomain, you automatically use the domain of the Ingress Controller that exposes the route. When a route is exposed by multiple Ingress Controllers, the route is hosted at multiple URLs.

routerName

Specifies the name of the Ingress Controller. In this example, the Ingress Controller has the name sharded.

Creating a route through an Ingress object

To integrate ecosystem components that require Ingress resources, configure an Ingress object. OKD automatically manages the lifecycle of the corresponding route objects, creating and deleting them to ensure seamless connectivity.

Procedure

Define an Ingress object in the OKD 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"
    route.openshift.io/destination-ca-certificate-secret: secret-ca-cert
spec:
  rules:
  - host: www.example.com
    http:
      paths:
      - backend:
          service:
            name: frontend
            port:
              number: 443
        path: /
        pathType: Prefix
  tls:
  - hosts:
    - www.example.com
    secretName: example-com-tls-certificate
# ...
```
where:
route.openshift.io/termination

Specifies the route.openshift.io/termination annotation. You can configure the spec.tls.termination parameter of the Route because Ingress does not have this parameter. 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.

rules.host

Specifies an explicit hostname for the Ingress object. Mandatory parameter. 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.

destination-ca-certificate-secret
Specifies the route.openshift.io/destination-ca-certificate-secret annotation. The annotation 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.
If you specify the passthrough value in the route.openshift.io/termination annotation, set path to '' and pathType to ImplementationSpecific in the spec:

apiVersion: networking.k8s.io/v1 kind: Ingress # ... spec: rules: - host: www.example.com http: paths: - path: '' pathType: ImplementationSpecific backend: service: name: frontend port: number: 443 # ...

$ oc apply -f ingress.yaml

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.

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

YAML definition example 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