= Route Trait

// Start of autogenerated code - DO NOT EDIT! (description)
The Route trait can be used to configure the creation of OpenShift routes for the integration.

The certificate and key contents may be sourced either from the local filesystem or in a OpenShift `secret` object.
The user may use the parameters ending in `-secret` (example: `tls-certificate-secret`) to reference a certificate stored in a `secret`.
Parameters ending in `-secret` have higher priorities and in case the same route parameter is set, for example: `tls-key-secret` and `tls-key`,
then `tls-key-secret` is used.
The recommended approach to set the key and certificates is to use `secrets` to store their contents and use the
following parameters to reference them: `tls-certificate-secret`, `tls-key-secret`, `tls-ca-certificate-secret`, `tls-destination-ca-certificate-secret`
See the examples section at the end of this page to see the setup options.


This trait is available in the following profiles: **OpenShift**.

// End of autogenerated code - DO NOT EDIT! (description)
// Start of autogenerated code - DO NOT EDIT! (configuration)
== Configuration

Trait properties can be specified when running any integration with the CLI:
[source,console]
----
$ kamel run --trait route.[key]=[value] --trait route.[key2]=[value2] integration.groovy
----
The following configuration options are available:

[cols="2m,1m,5a"]
|===
|Property | Type | Description

| route.enabled
| bool
| Can be used to enable or disable a trait. All traits share this common property.

| route.annotations
| map[string]string
| The annotations added to route.
This can be used to set route specific annotations
For annotations options see https://docs.openshift.com/container-platform/3.11/architecture/networking/routes.html#route-specific-annotations
CLI usage example: -t "route.annotations.'haproxy.router.openshift.io/balance'=true"

| route.host
| string
| To configure the host exposed by the route.

| route.tls-termination
| string
| The TLS termination type, like `edge`, `passthrough` or `reencrypt`.

Refer to the OpenShift route documentation for additional information.

| route.tls-certificate
| string
| The TLS certificate contents.

Refer to the OpenShift route documentation for additional information.

| route.tls-certificate-secret
| string
| The secret name and key reference to the TLS certificate. The format is "secret-name[/key-name]", the value represents the secret name, if there is only one key in the secret it will be read, otherwise you can set a key name separated with a "/".

Refer to the OpenShift route documentation for additional information.

| route.tls-key
| string
| The TLS certificate key contents.

Refer to the OpenShift route documentation for additional information.

| route.tls-key-secret
| string
| The secret name and key reference to the TLS certificate key. The format is "secret-name[/key-name]", the value represents the secret name, if there is only one key in the secret it will be read, otherwise you can set a key name separated with a "/".

Refer to the OpenShift route documentation for additional information.

| route.tls-ca-certificate
| string
| The TLS CA certificate contents.

Refer to the OpenShift route documentation for additional information.

| route.tls-ca-certificate-secret
| string
| The secret name and key reference to the TLS CA certificate. The format is "secret-name[/key-name]", the value represents the secret name, if there is only one key in the secret it will be read, otherwise you can set a key name separated with a "/".

Refer to the OpenShift route documentation for additional information.

| route.tls-destination-ca-certificate
| string
| The destination CA certificate provides the contents of the ca certificate of the final destination.  When using reencrypt
termination this file should be provided in order to have routers use it for health checks on the secure connection.
If this field is not specified, the router may provide its own destination CA and perform hostname validation using
the short service name (service.namespace.svc), which allows infrastructure generated certificates to automatically
verify.

Refer to the OpenShift route documentation for additional information.

| route.tls-destination-ca-certificate-secret
| string
| The secret name and key reference to the destination CA certificate. The format is "secret-name[/key-name]", the value represents the secret name, if there is only one key in the secret it will be read, otherwise you can set a key name separated with a "/".

Refer to the OpenShift route documentation for additional information.

| route.tls-insecure-edge-termination-policy
| string
| To configure how to deal with insecure traffic, e.g. `Allow`, `Disable` or `Redirect` traffic.

Refer to the OpenShift route documentation for additional information.

|===

// End of autogenerated code - DO NOT EDIT! (configuration)

== Examples

These examples uses *secrets* to store the certificates and keys to be referenced in the integrations. Read OpenShift route documentation for detailed information about routes. The https://github.com/apache/camel-k/blob/main/examples/http/PlatformHttpServer.java[PlatformHttpServer.java] is the integration example. 

As a requirement to run these examples, you should have a `secret` with a key and certificate.

=== Generate a self-signed certificate and create a secret

[source,console]
openssl genrsa -out tls.key
openssl req -new -key tls.key -out csr.csr -subj "/CN=my-server.com"
openssl x509 -req -in csr.csr -signkey tls.key -out tls.crt
oc create secret tls my-combined-certs --key=tls.key  --cert=tls.crt

=== Making an HTTP request to the route

For all examples, you can use the following curl command to make an HTTP request. It makes use of inline scripts to retrieve the openshift namespace and cluster base domain, if you are using a shell which doesn't support these inline scripts, you should replace the inline scripts with the values of your actual namespace and base domain.

[source,console]
curl -k https://platform-http-server-`oc config view --minify -o 'jsonpath={..namespace}'`.`oc get dnses/cluster -ojsonpath='{.spec.baseDomain}'`/hello?name=Camel-K

* To add an *edge* route using secrets, use the parameters ending in `-secret` to set the secret name which contains the certificate. This route example trait references a secret named `my-combined-certs` which contains two keys named `tls.key` and `tls.crt`.
+
[source,console]
kamel run --dev PlatformHttpServer.java -t route.tls-termination=edge -t route.tls-certificate-secret=my-combined-certs/tls.crt -t route.tls-key-secret=my-combined-certs/tls.key

* To add a *passthrough* route using secrets, the TLS is setup in the integration pod, the keys and certificates should be visible in the running integration pod, to achieve this we are using the `--resource` kamel parameter to mount the secret in the integration pod, then we use some camel quarkus parameters to reference these certificate files in the running pod, they start with `-p quarkus.http.ssl.certificate`. This route example trait references a secret named `my-combined-certs` which contains two keys named `tls.key` and `tls.crt`.
+
[source,console]
kamel run --dev PlatformHttpServer.java --resource secret:my-combined-certs@/etc/ssl/my-combined-certs -p quarkus.http.ssl.certificate.file=/etc/ssl/my-combined-certs/tls.crt -p quarkus.http.ssl.certificate.key-file=/etc/ssl/my-combined-certs/tls.key -t route.tls-termination=passthrough -t container.port=8443

* To add a *reencrypt* route using secrets, the TLS is setup in the integration pod, the keys and certificates should be visible in the running integration pod, to achieve this we are using the `--resource` kamel parameter to mount the secret in the integration pod, then we use some camel quarkus parameters to reference these certificate files in the running pod, they start with `-p quarkus.http.ssl.certificate`. This route example trait references a secret named `my-combined-certs` which contains two keys named `tls.key` and `tls.crt`.
+
[source,console]
kamel run --dev PlatformHttpServer.java --resource secret:my-combined-certs@/etc/ssl/my-combined-certs  -p quarkus.http.ssl.certificate.file=/etc/ssl/my-combined-certs/tls.crt -p quarkus.http.ssl.certificate.key-file=/etc/ssl/my-combined-certs/tls.key -t route.tls-termination=reencrypt -t route.tls-destination-ca-certificate-secret=my-combined-certs/tls.crt -t route.tls-certificate-secret=my-combined-certs/tls.crt -t route.tls-key-secret=my-combined-certs/tls.key -t container.port=8443

* To add a *reencrypt* route using a specific certificate from a secret for the route and https://docs.openshift.com/container-platform/4.8/security/certificates/service-serving-certificate.html#add-service-certificate_service-serving-certificate[OpenShift service serving certificates] for the integration endpoint. This way the OpenShift service serving certificates is set up only in the integration pod. The keys and certificates should be visible in the running integration pod, to achieve this we are using the `--resource` kamel parameter to mount the secret in the integration pod, then we use some camel quarkus parameters to reference these certificate files in the running pod, they start with `-p quarkus.http.ssl.certificate`. This route example trait references a secret named `my-combined-certs` which contains two keys named `tls.key` and `tls.crt`.
+
[source,console]
kamel run --dev PlatformHttpServer.java --resource secret:cert-from-openshift@/etc/ssl/cert-from-openshift  -p quarkus.http.ssl.certificate.file=/etc/ssl/cert-from-openshift/tls.crt -p quarkus.http.ssl.certificate.key-file=/etc/ssl/cert-from-openshift/tls.key -t route.tls-termination=reencrypt -t route.tls-certificate-secret=my-combined-certs/tls.crt -t route.tls-key-secret=my-combined-certs/tls.key -t container.port=8443
+
Then you should annotate the integration service to inject the OpenShift service serving certificates
+
[source,console]
oc annotate service platform-http-server service.beta.openshift.io/serving-cert-secret-name=cert-from-openshift

* To add an *edge* route using a certificate and a private key provided from your local filesystem. This example uses inline scripts to read the certificate and private key file contents, then remove all new line characters, (this is required to set the certificate as parameter's values), so the values are in a single line.
+
[source,console]
kamel run PlatformHttpServer.java --dev -t route.tls-termination=edge -t route.tls-certificate="$(cat tls.crt|awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}')" -t route.tls-key="$(cat tls.key|awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}')"
