<commit_before>= Routes
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:

toc::[]

== Overview

An OpenShift
link:../architecture/core_concepts/routes.html[route] exposes a
link:../architecture/core_concepts/pods_and_services.html#services[service]
at a hostname like `www.example.com` so that external clients can reach
it by name.

DNS resolution for a hostname is handled separately from routing;
your administrator may have configured a cloud domain that will always
correctly resolve to the OpenShift router, or if using an unrelated
hostname you may need to modify its DNS records independently to resolve
to the router.

== Creating Routes

Tooling for creating routes is developing. In the web console they are
displayed but there is not yet a method to create them. Via the CLI you
currently can create only an unsecured route using `oc expose`:

    $ oc expose service/<name> --hostname=<www.example.com>

The new route will inherit the name from the service unless you specify one.

.An Unsecured Route YAML Definition
[source,yaml]
----
apiVersion: v1
kind: Route
metadata:
  name: <route-name>
spec:
  host: www.example.com
  to:
    kind: Service
    name: <service-name>
----

Unsecured routes are simplest to set up, as they are the
default configuration, but secured routes offer security for
connections to remain private. To create a secured HTTPS
route encrypted with a key and certificate (PEM-format
files which you must generate and sign separately), you will
need to edit the unsecured route to add TLS termination (note:
link:https://en.wikipedia.org/wiki/Transport_Layer_Security[TLS] is the
replacement of SSL for HTTPS and other encrypted protocols).

    $ oc edit route/<name>

.A Secure Route Using Edge Termination
[source,yaml]
----
apiVersion: v1
kind: Route
metadata:
  name: <route-name>
spec:
  host: www.example.com
  to:
    kind: Service
    name: <service-name>
  tls:
    termination: edge
    key: |-
      -----BEGIN PRIVATE KEY-----
      [...]
      -----END PRIVATE KEY-----
    certificate: |-
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----
    caCertificate: |-
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----
----

You can specify a secured route without a key and certificate, in which case the
link:../admin_guide/install/deploy_router.html#using-wildcard-dns[router's
default certificate] will be used for TLS termination.

NOTE: TLS termination in OpenShift relies on
link:https://en.wikipedia.org/wiki/Server_Name_Indication[SNI] for serving
custom certificates. Any non-SNI traffic received on port 443 is handled with TLS
termination and a default certificate (which may not match the requested hostname,
resulting in validation errors).

There is further information on all available types of
link:../architecture/core_concepts/routes.html#secured-routes[TLS
termination] as well as
link:../architecture/core_concepts/routes.html#path-based-routes[path-based
routing] in the
link:../architecture/core_concepts/routes.html[Architecture section].<commit_msg>Formatting edits to dev_guide/routes<commit_after>= Routes
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:

toc::[]

== Overview

An OpenShift link:../architecture/core_concepts/routes.html[route] exposes a
link:../architecture/core_concepts/pods_and_services.html#services[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 router, or if using an unrelated
host name you may need to modify its DNS records independently to resolve
to the router.

[[creating-routes]]

== Creating Routes

Tooling for creating routes is developing. In the web console, they are
displayed but there is not yet a method to create them. Using the CLI, you
currently can create only an unsecured route:

----
$ oc expose service/<name> --hostname=<www.example.com>
----

The new route inherits the name from the service unless you specify one.

.An Unsecured Route YAML Definition
====
[source,yaml]
----
apiVersion: v1
kind: Route
metadata:
  name: route-name
spec:
  host: www.example.com
  to:
    kind: Service
    name: service-name
----
====

Unsecured routes are the default configuration, and are therefore the simplest
to set up. However, secured routes offer security for connections to remain
private. To create a secured HTTPS route encrypted with a key and certificate
(PEM-format files which you must generate and sign separately), you must
edit the unsecured route to add TLS termination.

[NOTE]
====
link:https://en.wikipedia.org/wiki/Transport_Layer_Security[TLS] is the
replacement of SSL for HTTPS and other encrypted protocols.
====

----
$ oc edit route/<name>
----

.A Secure Route Using Edge Termination
====
[source,yaml]
----
apiVersion: v1
kind: Route
metadata:
  name: route-name
spec:
  host: www.example.com
  to:
    kind: Service
    name: service-name
  tls:
    termination: edge
    key: |-
      -----BEGIN PRIVATE KEY-----
      [...]
      -----END PRIVATE KEY-----
    certificate: |-
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----
    caCertificate: |-
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----
----
====

You can specify a secured route without a key and certificate, in which case the
link:../admin_guide/install/deploy_router.html#using-wildcard-dns[router's
default certificate] will be used for TLS termination.

[NOTE]
====
TLS termination in OpenShift relies on
link:https://en.wikipedia.org/wiki/Server_Name_Indication[SNI] for serving
custom certificates. Any non-SNI traffic received on port 443 is handled with
TLS termination and a default certificate, which may not match the requested
host name, resulting in validation errors.
====

Further information on all types of
link:../architecture/core_concepts/routes.html#secured-routes[TLS termination]
as well as
link:../architecture/core_concepts/routes.html#path-based-routes[path-based
routing] are available in the
link:../architecture/core_concepts/routes.html[Architecture section].
{'fraction_non_alphanumeric': 0.10523817059661339, 'fraction_numerical': 0.001582528881152081, 'mean_word_length': 3.636830520909758, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 13, 'https://': 4, 'lorem ipsum': 0, 'www.': 8, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6304751', 'n_tokens_mistral': 1894, 'n_tokens_neox': 1775, 'n_words': 709}