Chapter 7. Configuring routes

7.1. Creating an HTTP-based route
Link kopieren

To host your application at a public URL by using the basic HTTP routing protocol, create an HTTP-based route. This configuration exposes a service on an unsecured application port, allowing external access without TLS encryption.

A route can either be secure or unsecured, depending on the network security configuration of your application.

The following procedure describes how to create a simple HTTP-based route to a web application, using the hello-microshift application as an example.

Prerequisites

You installed the OpenShift CLI (oc).
You have access to your MicroShift node.
You have a web application that exposes a port and a TCP endpoint listening for traffic on the port.

Procedure

Create a service called hello-microshift by running the following command:
```
oc expose pod hello-microshift -n $namespace
```
```
$ oc expose pod hello-microshift -n $namespace
```
Copy to Clipboard Toggle word wrap
Create an unsecured route to the hello-microshift application by running the following command:
```
oc expose svc/hello-microshift --hostname=microshift.com $namespace
```
```
$ oc expose svc/hello-microshift --hostname=microshift.com $namespace
```
Copy to Clipboard Toggle word wrap

Verification

Verify that the route resource was created by running the following command:
```
oc get routes -o yaml <name of resource> -n $namespace
```
```
$ oc get routes -o yaml <name of resource> -n $namespace
```
Copy to Clipboard Toggle word wrap
namespace: Specifies the route that is named hello-microshift and the namespace is named hello-microshift.
Sample YAML definition for the created unsecured route
```
apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: hello-microshift
  namespace: hello-microshift
spec:
  host: microshift.com
  port:
    targetPort: 8080
  to:
    kind: Service
    name: hello-microshift
```
```
apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: hello-microshift
  namespace: hello-microshift
spec:
  host: microshift.com
  port:
    targetPort: 8080
  to:
    kind: Service
    name: hello-microshift
```
Copy to Clipboard Toggle word wrap
where:
spec.host
Specifies the hostname.
port.targetPort
Specifies the target port for the router to map the endpoint port in the service.
Note
MicroShift does not use an API that creates a default ingress domain, but instead provides a wildcard for automatically generated domains. Each route can also define a separate hostname.

7.2. HTTP Strict Transport Security
Link kopieren

To enhance security and optimize website performance, use the HTTP Strict Transport Security (HSTS) policy. This mechanism signals browsers to use only HTTPS traffic on the route host, eliminating the need for HTTP redirects and speeding up user interactions.

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

Important

HSTS works only with secure routes, either edge-terminated or re-encrypt. The configuration is ineffective on HTTP or passthrough routes.

7.3. Enabling HTTP Strict Transport Security per-route
Link kopieren

To enforce secure HTTPS connections for specific applications, enable HTTP Strict Transport Security (HSTS) on a per-route basis. Applying the haproxy.router.openshift.io/hsts_header annotation to edge and re-encrypt routes ensures that browsers reject unencrypted traffic.

Prerequisites

You have root access to the cluster.
You installed the OpenShift CLI (oc).

Procedure

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. To properly run the command, ensure that the semicolon (;) in the haproxy.router.openshift.io/hsts_header route annotation is also surrounded by double quotation marks ("").
Example annotate command that sets the maximum age to 31536000 ms (approximately 8.5 hours)
```
oc annotate route <route_name> -n <namespace> --overwrite=true "haproxy.router.openshift.io/hsts_header=max-age=31536000;\
includeSubDomains;preload"
```
```
$ oc annotate route <route_name> -n <namespace> --overwrite=true "haproxy.router.openshift.io/hsts_header=max-age=31536000;\
includeSubDomains;preload"
```
Copy to Clipboard Toggle word wrap
Example route configured with an annotation
```
apiVersion: route.openshift.io/v1
kind: Route
metadata:
  annotations:
    haproxy.router.openshift.io/hsts_header: max-age=31536000;includeSubDomains;preload
# ...
spec:
  host: def.abc.com
  tls:
    termination: "reencrypt"
    ...
  wildcardPolicy: "Subdomain"
# ...
```
```
apiVersion: route.openshift.io/v1
kind: Route
metadata:
  annotations:
    haproxy.router.openshift.io/hsts_header: max-age=31536000;includeSubDomains;preload
# ...
spec:
  host: def.abc.com
  tls:
    termination: "reencrypt"
    ...
  wildcardPolicy: "Subdomain"
# ...
```
Copy to Clipboard Toggle word wrap
where:
max-age
Specifies the measurement of the length of time, in seconds, for the HSTS policy. If set to 0, it negates the policy.
includeSubDomains
Specifies that all subdomains of the host must have the same HSTS policy as the host. Optional parameter.
preload
Specifies that the site is included in the HSTS preload list when max-age is greater than 0. For example, sites such as Google can construct a list of sites that have preload set. Browsers can then use these lists to determine which sites they can communicate with over HTTPS, even before they have interacted with the site. Without preload set, browsers must have interacted with the site over HTTPS, at least once, to get the header. Optional parameter.

7.3.1. Disabling HTTP Strict Transport Security per-route
Link kopieren

To allow unencrypted connections or troubleshoot access issues, disable HTTP Strict Transport Security (HSTS) for a specific route. Setting the max-age route annotation to 0 instructs browsers to stop enforcing HTTPS requirements on the route host.

Prerequisites

You have root access to the cluster.
You installed the OpenShift CLI (oc).

Procedure

To disable HSTS, enter the following to set the max-age value in the route annotation to 0:

oc annotate route <route_name> -n <namespace> --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=0"

$ oc annotate route <route_name> -n <namespace> --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=0"

Copy to Clipboard

Toggle word wrap

Tip

You can alternatively apply the following YAML to create the config map:

Example of disabling HSTS per-route

kind: Route
apiVersion: route.openshift.io/v1
metadata:
  annotations:
    haproxy.router.openshift.io/hsts_header: max-age=0

kind: Route
apiVersion: route.openshift.io/v1
metadata:
  annotations:
    haproxy.router.openshift.io/hsts_header: max-age=0

Copy to Clipboard

Toggle word wrap

To disable HSTS for every route in a namespace, enter the following command:

oc annotate route --all -n <namespace> --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=0"

$ oc annotate route --all -n <namespace> --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=0"

Copy to Clipboard

Toggle word wrap

Verification

To query the annotation for all routes, enter the following command:

oc get route  --all-namespaces -o go-template='{{range .items}}{{if .metadata.annotations}}{{$a := index .metadata.annotations "haproxy.router.openshift.io/hsts_header"}}{{$n := .metadata.name}}{{with $a}}Name: {{$n}} HSTS: {{$a}}{{"\n"}}{{else}}{{""}}{{end}}{{end}}{{end}}'

$ oc get route  --all-namespaces -o go-template='{{range .items}}{{if .metadata.annotations}}{{$a := index .metadata.annotations "haproxy.router.openshift.io/hsts_header"}}{{$n := .metadata.name}}{{with $a}}Name: {{$n}} HSTS: {{$a}}{{"\n"}}{{else}}{{""}}{{end}}{{end}}{{end}}'

Copy to Clipboard

Toggle word wrap

Example output

Name: routename HSTS: max-age=0

Name: routename HSTS: max-age=0

Copy to Clipboard

Toggle word wrap

7.3.2. Enforcing HTTP Strict Transport Security per-domain
Link kopieren

To enforce secure communication per-domain, configure routes with a compliant HSTS policy annotation. For upgraded nodes with non-compliant routes, ensure consistent enforcement by updating the source manifests to apply the new security policies.

You cannot use oc expose route or oc create route commands to add a route in a domain that enforces HSTS because the API for these commands does not accept annotations.

Important

HSTS cannot be applied to insecure, or non-TLS, routes.

Prerequisites

You have root access to the node.
You installed the OpenShift CLI (oc).

Procedure

Apply HSTS to all routes in the node by running the following command:

oc annotate route --all --all-namespaces --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=31536000;preload;includeSubDomains"

$ oc annotate route --all --all-namespaces --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=31536000;preload;includeSubDomains"

Copy to Clipboard

Toggle word wrap

Apply HSTS to all routes in a particular namespace by running the following command:

oc annotate route --all -n <my_namespace> --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=31536000;preload;includeSubDomains"

$ oc annotate route --all -n <my_namespace> --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=31536000;preload;includeSubDomains"

Copy to Clipboard

Toggle word wrap

<my_namespace>: Specify the namespace that you want to use.

Verification

Review the HSTS annotations on all routes by running the following command:

oc get route  --all-namespaces -o go-template='{{range .items}}{{if .metadata.annotations}}{{$a := index .metadata.annotations "haproxy.router.openshift.io/hsts_header"}}{{$n := .metadata.name}}{{with $a}}Name: {{$n}} HSTS: {{$a}}{{"\n"}}{{else}}{{""}}{{end}}{{end}}{{end}}'

$ oc get route  --all-namespaces -o go-template='{{range .items}}{{if .metadata.annotations}}{{$a := index .metadata.annotations "haproxy.router.openshift.io/hsts_header"}}{{$n := .metadata.name}}{{with $a}}Name: {{$n}} HSTS: {{$a}}{{"\n"}}{{else}}{{""}}{{end}}{{end}}{{end}}'

Copy to Clipboard

Toggle word wrap

Example output

Name: <_routename_> HSTS: max-age=31536000;preload;includeSubDomains

Name: <_routename_> HSTS: max-age=31536000;preload;includeSubDomains

Copy to Clipboard

Toggle word wrap

7.4. Throughput issue troubleshooting methods
Link kopieren

To diagnose and resolve network throughput issues, such as unusually high latency between specific services, apply troubleshooting methods. Identifying connectivity bottlenecks helps ensure stable application performance within Red Hat build of MicroShift.

If pod logs do not reveal any cause of the problem, use the following methods to analyze performance issues:

Use a packet analyzer, such as ping or tcpdump to analyze traffic between a pod and its node.
For example, run the tcpdump tool on each pod while reproducing the behavior that led to the issue. Review the captures on both sides to compare send and receive timestamps to analyze the latency of traffic to and from a pod. Latency can occur in Red Hat build of MicroShift if a node interface is overloaded with traffic from other pods, storage devices, or the data plane.
```
tcpdump -s 0 -i any -w /tmp/dump.pcap host <podip 1> && host <podip 2>
```
```
$ tcpdump -s 0 -i any -w /tmp/dump.pcap host <podip 1> && host <podip 2> 
```
1
Copy to Clipboard Toggle word wrap
where:
podip
Specifies the IP address for the pod. Run the oc get pod <pod_name> -o wide command to get the IP address of a pod.
The tcpdump command generates a file at /tmp/dump.pcap containing all traffic between these two pods. You can run the analyzer shortly before the issue is reproduced and stop the analyzer shortly after the issue is finished reproducing to minimize the size of the file. You can also run a packet analyzer between the nodes with:
$ tcpdump -s 0 -i any -w /tmp/dump.pcap port 4789

Copy to Clipboard Toggle word wrap
Use a bandwidth measuring tool, such as iperf, to measure streaming throughput and UDP throughput. Locate any bottlenecks by running the tool from the pods first, and then running it from the nodes.

7.5. Using cookies to keep route statefulness
Link kopieren

To maintain stateful application traffic during pod restarts or scaling events, configure sticky sessions by using cookies. By using this method, you ensure that all incoming traffic reaches the same endpoint, preventing state loss even if the specific endpoint pod changes.

Red Hat build of MicroShift can use cookies to configure session persistence. The Ingress Controller 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 Ingress Controller which endpoint is handling the session, ensuring that client requests use the cookie so that they are routed to the same pod.

Note

Cookies cannot be set on passthrough routes, because the HTTP traffic cannot be seen. Instead, a number is calculated based on the source IP address, which determines the backend.

If backends change, the traffic can be directed to the wrong server, making it less sticky. If you are using a load balancer, which hides source IP, the same number is set for all connections and traffic is sent to the same pod.

To enable applications to manage session persistence and load distribution, annotate the route with a custom cookie name. Overwriting the default cookie allows the backend application to identify and delete the specific cookie, forcing endpoint re-selection when necessary.

When a server is overloaded, the server tries to remove the requests from the client and redistribute the requests to other endpoints.

Procedure

Annotate the route with the specified cookie name:
```
oc annotate route <route_name> router.openshift.io/cookie_name="<cookie_name>"
```
```
$ oc annotate route <route_name> router.openshift.io/cookie_name="<cookie_name>"
```
Copy to Clipboard Toggle word wrap
where:
<route_name>
Specifies the name of the route.
<cookie_name>
Specifies the name for the cookie.
For example, to annotate the route my_route with the cookie name my_cookie:
$ oc annotate route my_route router.openshift.io/cookie_name="my_cookie"

Copy to Clipboard Toggle word wrap
Capture the route hostname in a variable:
```
ROUTE_NAME=$(oc get route <route_name> -o jsonpath='{.spec.host}')
```
```
$ ROUTE_NAME=$(oc get route <route_name> -o jsonpath='{.spec.host}')
```
Copy to Clipboard Toggle word wrap
where:
<route_name>
Specifies the name of the route.
Save the cookie, and then access the route:
```
curl $ROUTE_NAME -k -c /tmp/cookie_jar
```
```
$ curl $ROUTE_NAME -k -c /tmp/cookie_jar
```
Copy to Clipboard Toggle word wrap
Use the cookie saved by the previous command when connecting to the route:
```
curl $ROUTE_NAME -k -b /tmp/cookie_jar
```
```
$ curl $ROUTE_NAME -k -b /tmp/cookie_jar
```
Copy to Clipboard Toggle word wrap

7.6. Path-based routes
Link kopieren

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:

Expand

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

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

Copy to Clipboard

Toggle word wrap

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

Note

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.

7.7. HTTP header configuration
Link kopieren

To customize request and response headers, modify individual route configurations or apply route annotations. Understanding the interaction between these methods ensures you effectively manage header policies and resolve potential configuration conflicts.

The various ways of configuring headers can present challenges when working together.

Note

You can only set or delete headers within a Route CR. You cannot append headers. If an HTTP header is set with a value, that value must be complete and not require appending in the future. In situations where it makes sense to append a header, such as the X-Forwarded-For header, use the spec.httpHeaders.forwardedHeaderPolicy field, instead of spec.httpHeaders.actions.

Example Route spec

apiVersion: route.openshift.io/v1
kind: Route
# ...
spec:
  httpHeaders:
    actions:
      response:
      - name: X-Frame-Options
        action:
          type: Set
          set:
            value: SAMEORIGIN

apiVersion: route.openshift.io/v1
kind: Route
# ...
spec:
  httpHeaders:
    actions:
      response:
      - name: X-Frame-Options
        action:
          type: Set
          set:
            value: SAMEORIGIN

Copy to Clipboard

Toggle word wrap

Any actions defined in a route override values set using route annotations.

Special case headers: The following headers are either prevented entirely from being set or deleted, or allowed under specific circumstances:

Expand

Header name	Configurable using `Route` spec	Reason for disallowment	Configurable using another method
`proxy`	No	The `proxy` HTTP request header can be used to exploit vulnerable CGI applications by injecting the header value into the `HTTP_PROXY` environment variable. The `proxy` HTTP request header is also non-standard and prone to error during configuration.	No
`host`	Yes	When the `host` HTTP request header is set using the `IngressController` CR, HAProxy can fail when looking up the correct route.	No
`strict-transport-security`	No	The `strict-transport-security` HTTP response header is already handled using route annotations and does not need a separate implementation.	Yes: the `haproxy.router.openshift.io/hsts_header` route annotation
`cookie` and `set-cookie`	No	The cookies that HAProxy sets are used for session tracking to map client connections to particular back-end servers. Allowing these headers to be set could interfere with HAProxy’s session affinity and restrict HAProxy’s ownership of a cookie.	Yes: * the `haproxy.router.openshift.io/disable_cookie` route annotation * the `haproxy.router.openshift.io/cookie_name` route annotation

7.8. Setting or deleting HTTP request and response headers in a route
Link kopieren

You can set or delete certain HTTP request and response headers for compliance purposes or other reasons. You can set or delete these headers either for all routes served by an Ingress Controller or for specific routes.

For example, you might want to enable a web application to serve content in alternate locations for specific routes if that content is written in multiple languages, even if there is a default global location specified by the Ingress Controller serving the routes.

The following procedure creates a route that sets the Content-Location HTTP request header so that the URL associated with the application, https://app.example.com, directs to the location https://app.example.com/lang/en-us. Directing application traffic to this location means that anyone using that specific route is accessing web content written in American English.

Prerequisites

You have installed the OpenShift CLI (oc).
You are logged into an Red Hat build of MicroShift cluster 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.

Procedure

Create a route definition and save it in a file called app-example-route.yaml:
YAML definition of the created route with HTTP header directives
```
apiVersion: route.openshift.io/v1
kind: Route
# ...
spec:
  host: app.example.com
  tls:
    termination: edge
  to:
    kind: Service
    name: app-example
  httpHeaders:
    actions:
      response:
      - name: Content-Location
        action:
          type: Set
          set:
            value: /lang/en-us
# ...
```
```
apiVersion: route.openshift.io/v1
kind: Route
# ...
spec:
  host: app.example.com
  tls:
    termination: edge
  to:
    kind: Service
    name: app-example
  httpHeaders:
    actions:
      response:
      - name: Content-Location
        action:
          type: Set
          set:
            value: /lang/en-us
# ...
```
Copy to Clipboard Toggle word wrap
where:
actions
Specifies the list of actions you want to perform on the HTTP headers.
response
Specifies the type of header you want to change. In this case, a response header.
response.name
Specifies the name of the header you want to change. For a list of available headers you can set or delete, see HTTP header configuration.
action.type
Specifies the type of action being taken on the header. This field can have the value Set or Delete.
set.value
When setting HTTP headers, you must provide a value. The value can be a string from a list of available directives for that header, for example DENY, or it can be a dynamic value that will be interpreted using HAProxy’s dynamic value syntax. In this case, the value is set to the relative location of the content.
Create a route to your existing web application using the newly created route definition:
```
oc -n app-example create -f app-example-route.yaml
```
```
$ oc -n app-example create -f app-example-route.yaml
```
Copy to Clipboard Toggle word wrap
For HTTP request headers, the actions specified in the route definitions are executed after any actions performed on HTTP request headers in the Ingress Controller. This means that any values set for those request headers in a route will take precedence over the ones set in the Ingress Controller. For more information on the processing order of HTTP headers, see HTTP header configuration.

7.9. Creating a route through an Ingress object
Link kopieren

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

Procedure

Define an Ingress object in the Red Hat build of MicroShift 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
# ...

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

Copy to Clipboard

Toggle word wrap

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

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

Copy to Clipboard

Toggle word wrap

oc apply -f ingress.yaml

$ oc apply -f ingress.yaml

Copy to Clipboard

Toggle word wrap

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

$ oc get routes

Copy to Clipboard

Toggle word wrap

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

NAME             HOST/PORT         PATH    SERVICES    PORT    TERMINATION          WILDCARD
frontend-gnztq   www.example.com           frontend    443     reencrypt/Redirect   None

Copy to Clipboard

Toggle word wrap

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

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

Copy to Clipboard

Toggle word wrap

7.10. Creating a route using the default certificate through an Ingress object
Link kopieren

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:
  - {}
```
```
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: frontend
  ...
spec:
  rules:
    ...
  tls:
  - {}
```
Copy to Clipboard Toggle word wrap
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
```
```
$ oc create -f example-ingress.yaml
```
Copy to Clipboard Toggle word wrap

Verification

Verify that Red Hat build of MicroShift has created the expected route for the Ingress object by running the following command:
```
oc get routes -o yaml
```
```
$ oc get routes -o yaml
```
Copy to Clipboard Toggle word wrap
Example output
```
apiVersion: v1
items:
- apiVersion: route.openshift.io/v1
  kind: Route
  metadata:
    name: frontend-j9sdd
# ...
  spec:
  ...
    tls:
      insecureEdgeTerminationPolicy: Redirect
      termination: edge
# ...
```
```
apiVersion: v1
items:
- apiVersion: route.openshift.io/v1
  kind: Route
  metadata:
    name: frontend-j9sdd
# ...
  spec:
  ...
    tls:
      insecureEdgeTerminationPolicy: Redirect
      termination: edge
# ...
```
Copy to Clipboard Toggle word wrap
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.

7.11. Creating a route using the destination CA certificate in the Ingress annotation
Link kopieren

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>

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

Copy to Clipboard

Toggle word wrap

For example:

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

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

Copy to Clipboard

Toggle word wrap

Example output

secret/dest-ca-cert created

secret/dest-ca-cert created

Copy to Clipboard

Toggle word wrap

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

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

Copy to Clipboard

Toggle word wrap

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

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

Copy to Clipboard

Toggle word wrap

Dieser Inhalt ist in der von Ihnen ausgewählten Sprache nicht verfügbar.

7.1. Creating an HTTP-based route
Link kopieren

7.2. HTTP Strict Transport Security
Link kopieren

7.3. Enabling HTTP Strict Transport Security per-route
Link kopieren

7.3.1. Disabling HTTP Strict Transport Security per-route
Link kopieren

7.3.2. Enforcing HTTP Strict Transport Security per-domain
Link kopieren

7.4. Throughput issue troubleshooting methods
Link kopieren

7.5. Using cookies to keep route statefulness
Link kopieren

7.6. Path-based routes
Link kopieren

7.7. HTTP header configuration
Link kopieren

7.8. Setting or deleting HTTP request and response headers in a route
Link kopieren

7.9. Creating a route through an Ingress object
Link kopieren

7.10. Creating a route using the default certificate through an Ingress object
Link kopieren

7.11. Creating a route using the destination CA certificate in the Ingress annotation
Link kopieren

Lernen

Testen, kaufen und verkaufen

Communitys

Über Red Hat Dokumentation

Mehr Inklusion in Open Source

Über Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

Dieser Inhalt ist in der von Ihnen ausgewählten Sprache nicht verfügbar.

Chapter 7. Configuring routes

7.1. Creating an HTTP-based routeLink kopierenLink in die Zwischenablage kopiert!

7.2. HTTP Strict Transport SecurityLink kopierenLink in die Zwischenablage kopiert!

7.3. Enabling HTTP Strict Transport Security per-routeLink kopierenLink in die Zwischenablage kopiert!

7.3.1. Disabling HTTP Strict Transport Security per-routeLink kopierenLink in die Zwischenablage kopiert!

7.3.2. Enforcing HTTP Strict Transport Security per-domainLink kopierenLink in die Zwischenablage kopiert!

7.4. Throughput issue troubleshooting methodsLink kopierenLink in die Zwischenablage kopiert!

7.5. Using cookies to keep route statefulnessLink kopierenLink in die Zwischenablage kopiert!

7.5.1. Annotating a route with a cookieLink kopierenLink in die Zwischenablage kopiert!

7.6. Path-based routesLink kopierenLink in die Zwischenablage kopiert!

7.7. HTTP header configurationLink kopierenLink in die Zwischenablage kopiert!

7.8. Setting or deleting HTTP request and response headers in a routeLink kopierenLink in die Zwischenablage kopiert!

7.9. Creating a route through an Ingress objectLink kopierenLink in die Zwischenablage kopiert!

7.10. Creating a route using the default certificate through an Ingress objectLink kopierenLink in die Zwischenablage kopiert!

7.11. Creating a route using the destination CA certificate in the Ingress annotationLink kopierenLink in die Zwischenablage kopiert!

Lernen

Testen, kaufen und verkaufen

Communitys

Über Red Hat Dokumentation

Mehr Inklusion in Open Source

Über Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

7.1. Creating an HTTP-based route
Link kopieren

7.2. HTTP Strict Transport Security
Link kopieren

7.3. Enabling HTTP Strict Transport Security per-route
Link kopieren

7.3.1. Disabling HTTP Strict Transport Security per-route
Link kopieren

7.3.2. Enforcing HTTP Strict Transport Security per-domain
Link kopieren

7.4. Throughput issue troubleshooting methods
Link kopieren

7.5. Using cookies to keep route statefulness
Link kopieren

7.5.1. Annotating a route with a cookie
Link kopieren

7.6. Path-based routes
Link kopieren

7.7. HTTP header configuration
Link kopieren

7.8. Setting or deleting HTTP request and response headers in a route
Link kopieren

7.9. Creating a route through an Ingress object
Link kopieren

7.10. Creating a route using the default certificate through an Ingress object
Link kopieren

7.11. Creating a route using the destination CA certificate in the Ingress annotation
Link kopieren