Creating advanced routes

To secure application traffic and serve custom certificates to clients, configure routes by using edge, passthrough, or re-encrypt TLS termination. By using these methods, you can define granular encryption rules, ensuring that traffic is decrypted and re-encrypted according to your specific security requirements.

Creating an edge route with a custom certificate

To secure traffic by using a custom certificate, configure a route with edge TLS termination by running the oc create route command. This configuration terminates encryption at the Ingress Controller before forwarding traffic to the destination pod.

The route specifies the TLS certificate and key that the Ingress Controller uses for the route.

The procedure creates a Route resource with a custom certificate and edge TLS termination. The procedure assumes that the certificate/key pair are in the tls.crt and tls.key files in the current working directory. You may also specify a CA certificate if needed to complete the certificate chain. Substitute the actual path names for tls.crt, tls.key, and (optionally) ca.crt. Substitute the name of the service that you want to expose for frontend. Substitute the appropriate hostname for www.example.com.

Prerequisites

You must have a certificate/key pair in PEM-encoded files, where the certificate is valid for the route host.
You might have a separate CA certificate in a PEM-encoded file that completes the certificate chain.
You must have a service that you want to expose.

Note

Password protected key files are not supported. To remove a passphrase from a key file, use the following command:

$ openssl rsa -in password_protected_tls.key -out tls.key

Procedure

Create a secure Route resource using edge TLS termination and a custom certificate.

$ oc create route edge --service=frontend --cert=tls.crt --key=tls.key --ca-cert=ca.crt --hostname=www.example.com

If you examine the resulting Route resource, the resource should have a configuration similar to the following example:

YAML Definition of the Secure Route

apiVersion: route.openshift.io/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-----
# ...

See oc create route edge --help for more options.

Creating a re-encrypt route with a custom certificate

To secure traffic by using a custom certificate, configure a route with re-encrypt TLS termination by running the oc create route command. This configuration enables the Ingress Controller to decrypt traffic, and then re-encrypt traffic before forwarding the traffic to the destination pod.

The procedure creates a Route resource with a custom certificate and reencrypt TLS termination. The procedure assumes that the certificate/key pair are in the tls.crt and tls.key files in the current working directory. You must also specify a destination CA certificate to enable the Ingress Controller to trust the service’s certificate. You may also specify a CA certificate if needed to complete the certificate chain. Substitute the actual path names for tls.crt, tls.key, cacert.crt, and (optionally) ca.crt. Substitute the name of the Service resource that you want to expose for frontend. Substitute the appropriate hostname for www.example.com.

Prerequisites

You must have a certificate/key pair in PEM-encoded files, where the certificate is valid for the route host.
You may have a separate CA certificate in a PEM-encoded file that completes the certificate chain.
You must have a separate destination CA certificate in a PEM-encoded file.
You must have a service that you want to expose.

Note

Password protected key files are not supported. To remove a passphrase from a key file, use the following command:

$ openssl rsa -in password_protected_tls.key -out tls.key

Procedure

Create a secure Route resource using reencrypt TLS termination and a custom certificate:

$ oc create route reencrypt --service=frontend --cert=tls.crt --key=tls.key --dest-ca-cert=destca.crt --ca-cert=ca.crt --hostname=www.example.com

If you examine the resulting Route resource, the resource should have a configuration similar to the following example:

YAML Definition of the Secure Route

apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: frontend
spec:
  host: www.example.com
  to:
    kind: Service
    name: frontend
  tls:
    termination: reencrypt
    key: |-
      -----BEGIN PRIVATE KEY-----
      [...]
      -----END PRIVATE KEY-----
    certificate: |-
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----
    caCertificate: |-
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----
    destinationCACertificate: |-
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----
# ...

See oc create route reencrypt --help for more options.

Creating a passthrough route

To send encrypted traffic directly to the destination without decryption at the router, configure a route with passthrough termination by running the oc create route command. This configuration requires no key or certificate on the route, as the destination pod handles TLS termination.

Prerequisites

You must have a service that you want to expose.

Procedure

Create a Route resource:
```
$ oc create route passthrough route-passthrough-secured --service=frontend --port=8080
```
If you examine the resulting Route resource, it should look similar to the following:
A Secured Route Using Passthrough Termination
```
apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: route-passthrough-secured
spec:
  host: www.example.com
  port:
    targetPort: 8080
  tls:
    termination: passthrough
    insecureEdgeTerminationPolicy: None
  to:
    kind: Service
    name: frontend
```
where:

metadata.name

Specifies the name of the object, which is limited to 63 characters.

tls.termination

Specifies the termination field is set to passthrough. This is the only required tls field.

tls.insecureEdgeTerminationPolicy

Specifies the type of edge termination policy. Optional parameter. The only valid values are None, Redirect, or empty for disabled.

The destination pod is responsible for serving certificates for the traffic at the endpoint. This is currently the only method that can support requiring client certificates, also known as two-way authentication.

Creating a route using the destination CA certificate in the Ingress annotation

To define a route with a custom destination CA certificate, apply the route.openshift.io/destination-ca-certificate-secret annotation to an Ingress object. This configuration ensures the Ingress Controller uses the specified secret to verify the identity of the destination service.

Prerequisites

You have a certificate/key pair in PEM-encoded files, where the certificate is valid for the route host.
You have a separate CA certificate in a PEM-encoded file that completes the certificate chain.
You have a separate destination CA certificate in a PEM-encoded file.
You have a service that you want to expose.

Procedure

Create a secret for the destination CA certificate by entering the following command:

$ oc create secret generic dest-ca-cert --from-file=tls.crt=<file_path>

For example:

$ oc -n test-ns create secret generic dest-ca-cert --from-file=tls.crt=tls.crt

Example output

secret/dest-ca-cert created

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

where:

destination-ca-certificate-secret

Specifies the route.openshift.io/destination-ca-certificate-secret annotation. The annotation references a Kubernetes secret.

The Ingress Controller inserts a secret that is referenced in the annotation 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-----
...

Creating a route with externally managed certificates

You can configure OpenShift Container Platform routes with third-party certificate management solutions by using the .spec.tls.externalCertificate field of the route API. You can reference externally managed TLS certificates via secrets, eliminating the need for manual certificate management.

By using the externally managed certificate, you can reduce errors to ensure a smoother rollout of certificate updates and enable the OpenShift router to serve renewed certificates promptly. You can use externally managed certificates with both edge routes and re-encrypt routes.

Prerequisites

You must have a secret containing a valid certificate or key pair in PEM-encoded format of type kubernetes.io/tls, which includes both tls.key and tls.crt keys. Example command: $ oc create secret tls myapp-tls --cert=server.crt --key=server.key.

Procedure

Create a role object 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> \
--namespace=<current-namespace>
```
- <secret-name>: Specify the actual name of your secret.
- <current-namespace>: Specify the namespace where both your secret and route reside.
Create a rolebinding object 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>
```
- <current-namespace>: Specify the namespace where both your secret and route reside.

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>
    termination: edge
    [...]
[...]

<secret-name>: Specify the actual name of your secret.

Create a route resource by running the following command:
```
$ oc apply -f <route.yaml>
```
- <route.yaml>: Specify the generated YAML filename.
  
  If the secret exists and has a certificate/key pair, the router will serve the generated certificate if all prerequisites are met.
  
  Note
  
  If .spec.tls.externalCertificate is not provided, the router uses default generated certificates.
  
  You cannot provide the .spec.tls.certificate field or the .spec.tls.key field when using the .spec.tls.externalCertificate field.

Creating a route using the default certificate through an Ingress object

To generate a secure, edge-terminated route that uses the default ingress certificate, specify an empty TLS configuration in the Ingress object. This configuration overrides the default behavior, preventing the creation of an insecure route.

Prerequisites

You have a service that you want to expose.
You have access to the OpenShift CLI (oc).

Procedure

Create a YAML file for the Ingress object. In the following 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:
  - {}
```
where:

spec.tls

Specifies the TLS configuration. Use the exact syntax shown to specify TLS without specifying a custom certificate.
Create the Ingress object by running the following command:
```
$ oc create -f example-ingress.yaml
```

Verification

Verify that OpenShift Container Platform has created the expected route for the Ingress object by running the following command:
```
$ oc get routes -o yaml
```
Example output
```
apiVersion: v1
items:
- apiVersion: route.openshift.io/v1
  kind: Route
  metadata:
    name: frontend-j9sdd
# ...
  spec:
  ...
    tls:
      insecureEdgeTerminationPolicy: Redirect
      termination: edge
# ...
```
where:

metadata.name

Specifies the name of the route, which includes the name of the Ingress object followed by a random suffix.

spec.tls

To use the default certificate, the route should not specify spec.certificate.

tls.termination

Specifies the termination policy for the route. The route should specify the edge termination policy.