Configuring a custom domain for a Knative service - Security | Serverless | OpenShift Container Platform Branch Build

Creating a custom domain mapping
Creating a custom domain mapping by using the Knative CLI
Mapping a custom domain to a service by using the Developer perspective
Securing a service with a custom domain by using a TLS certificate

Knative services are automatically assigned a default domain name based on your cluster configuration. For example, <service_name>-<namespace>.example.com. You can customize the domain for your Knative service by mapping a custom domain name that you own to a Knative service.

You can do this by creating a DomainMapping resource for the service. You can also create multiple DomainMapping resources to map multiple domains and subdomains to a single service.

Creating a custom domain mapping

You can customize the domain for your Knative service by mapping a custom domain name that you own to a Knative service. To map a custom domain name to a custom resource (CR), you must create a DomainMapping CR that maps to an Addressable target CR, such as a Knative service or a Knative route.

Prerequisites

The OpenShift Serverless Operator and Knative Serving are installed on your cluster.
Install the OpenShift CLI (oc).
You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in OpenShift Container Platform.
You have created a Knative service and control a custom domain that you want to map to that service.

Your custom domain must point to the IP address of the OpenShift Container Platform cluster.

Procedure

Create a YAML file containing the DomainMapping CR in the same namespace as the target CR you want to map to:

apiVersion: serving.knative.dev/v1alpha1
kind: DomainMapping
metadata:
 name: <domain_name> (1)
 namespace: <namespace> (2)
spec:
 ref:
   name: <target_name> (3)
   kind: <target_type> (4)
   apiVersion: serving.knative.dev/v1

1	The custom domain name that you want to map to the target CR.
2	The namespace of both the `DomainMapping` CR and the target CR.
3	The name of the target CR to map to the custom domain.
4	The type of CR being mapped to the custom domain.

Example service domain mapping

apiVersion: serving.knative.dev/v1alpha1
kind: DomainMapping
metadata:
 name: example-domain
 namespace: default
spec:
 ref:
   name: example-service
   kind: Service
   apiVersion: serving.knative.dev/v1

Example route domain mapping

apiVersion: serving.knative.dev/v1alpha1
kind: DomainMapping
metadata:
 name: example-domain
 namespace: default
spec:
 ref:
   name: example-route
   kind: Route
   apiVersion: serving.knative.dev/v1

Apply the DomainMapping CR as a YAML file:
```
$ oc apply -f <filename>
```

Creating a custom domain mapping by using the Knative CLI

You can customize the domain for your Knative service by mapping a custom domain name that you own to a Knative service. You can use the Knative (kn) CLI to create a DomainMapping custom resource (CR) that maps to an Addressable target CR, such as a Knative service or a Knative route.

Prerequisites

The OpenShift Serverless Operator and Knative Serving are installed on your cluster.
You have created a Knative service or route, and control a custom domain that you want to map to that CR.

Your custom domain must point to the DNS of the OpenShift Container Platform cluster.
You have installed the Knative (kn) CLI.
You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in OpenShift Container Platform.

Procedure

Map a domain to a CR in the current namespace:
```
$ kn domain create <domain_mapping_name> --ref <target_name>
```
Example command
```
$ kn domain create example-domain-map --ref example-service
```
The --ref flag specifies an Addressable target CR for domain mapping.

If a prefix is not provided when using the --ref flag, it is assumed that the target is a Knative service in the current namespace.

Map a domain to a Knative service in a specified namespace:

$ kn domain create <domain_mapping_name> --ref <ksvc:service_name:service_namespace>

Example command

$ kn domain create example-domain-map --ref ksvc:example-service:example-namespace

Map a domain to a Knative route:

$ kn domain create <domain_mapping_name> --ref <kroute:route_name>

Example command

$ kn domain create example-domain-map --ref kroute:example-route

Mapping a custom domain to a service by using the Developer perspective

You can customize the domain for your Knative service by mapping a custom domain name that you own to a Knative service. You can use the Developer perspective of the OpenShift Container Platform web console to map a DomainMapping custom resource (CR) to a Knative service.

Prerequisites

You have logged in to the web console.
You are in the Developer perspective.
The OpenShift Serverless Operator and Knative Serving are installed on your cluster. This must be completed by a cluster administrator.
You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in OpenShift Container Platform.
You have created a Knative service and control a custom domain that you want to map to that service.

Your custom domain must point to the IP address of the OpenShift Container Platform cluster.

Procedure

Navigate to the Topology page.
Right-click on the service that you want to map to a domain, and select the Edit option that contains the service name. For example, if the service is named example-service, select the Edit example-service option.
In the Advanced options section, click Show advanced Routing options.
1. If the domain mapping CR that you want to map to the service already exists, you can select it in the Domain mapping list.
2. If you want to create a new domain mapping CR, type the domain name into the box, and select the Create option. For example, if you type in example.com, the Create option is Create "example.com".
Click Save to save the changes to your service.

Verification

Navigate to the Topology page.
Click on the service that you have created.
In the Resources tab of the service information window, you can see the domain you have mapped to the service listed under Domain mappings.

Securing a service with a custom domain by using a TLS certificate

After you have configured a custom domain for a Knative service, you can use a TLS certificate to secure the mapped service. To do this, you must create a Kubernetes TLS secret, and then update the DomainMapping CR to use the TLS secret that you have created.

If you use net-istio for Ingress and enable mTLS via SMCP using security.dataPlane.mtls: true, Service Mesh deploys DestinationRules for the *.local host, which does not allow DomainMapping for OpenShift Serverless.

To work around this issue, enable mTLS by deploying PeerAuthentication instead of using security.dataPlane.mtls: true.

Prerequisites

You configured a custom domain for a Knative service and have a working DomainMapping CR.
You have a TLS certificate from your Certificate Authority provider or a self-signed certificate.
You have obtained the cert and key files from your Certificate Authority provider, or a self-signed certificate.
Install the OpenShift CLI (oc).

Procedure

Create a Kubernetes TLS secret:

$ oc create secret tls <tls_secret_name> --cert=<path_to_certificate_file> --key=<path_to_key_file>

If you are using Red Hat OpenShift Service Mesh as the ingress for your OpenShift Serverless installation, label the Kubernetes TLS secret with the following:
```
“networking.internal.knative.dev/certificate-uid": “<value>”
```
If you are using a third-party secret provider such as cert-manager, you can configure your secret manager to label the Kubernetes TLS secret automatically. Cert-manager users can use the secret template offered to automatically generate secrets with the correct label. In this case, secret filtering is done based on the key only, but this value can carry useful information such as the certificate ID that the secret contains.

The cert-manager Operator for Red Hat OpenShift is a Technology Preview feature. For more information, see the Installing the cert-manager Operator for Red Hat OpenShift documentation.

Update the DomainMapping CR to use the TLS secret that you have created:

apiVersion: serving.knative.dev/v1alpha1
kind: DomainMapping
metadata:
  name: <domain_name>
  namespace: <namespace>
spec:
  ref:
    name: <service_name>
    kind: Service
    apiVersion: serving.knative.dev/v1
# TLS block specifies the secret to be used
  tls:
    secretName: <tls_secret_name>

Verification

Verify that the DomainMapping CR status is True, and that the URL column of the output shows the mapped domain with the scheme https:

$ oc get domainmapping <domain_name>

Example output

NAME                      URL                               READY   REASON
example.com               https://example.com               True

Optional: If the service is exposed publicly, verify that it is available by running the following command:
```
$ curl https://<domain_name>
```
If the certificate is self-signed, skip verification by adding the -k flag to the curl command.