Chapter 14. Configuring custom domains for Knative services 14.1. Configuring a custom domain for a Knative service 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. 14.2. 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. 14.2.1. 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. Note 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/v1beta1 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/v1beta1 kind: DomainMapping metadata: name: example.com namespace: default spec: ref: name: showcase kind: Service apiVersion: serving.knative.dev/v1 Example route domain mapping apiVersion: serving.knative.dev/v1beta1 kind: DomainMapping metadata: name: example.com namespace: default spec: ref: name: example-route kind: Route apiVersion: serving.knative.dev/v1 Apply the DomainMapping CR as a YAML file: USD oc apply -f <filename> 14.3. Custom domains for Knative services 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. 14.3.1. Creating a custom domain mapping by using the Knative CLI 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. Note 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: USD kn domain create <domain_mapping_name> --ref <target_name> Example command USD kn domain create example.com --ref showcase 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: USD kn domain create <domain_mapping_name> --ref <ksvc:service_name:service_namespace> Example command USD kn domain create example.com --ref ksvc:showcase:example-namespace Map a domain to a Knative route: USD kn domain create <domain_mapping_name> --ref <kroute:route_name> Example command USD kn domain create example.com --ref kroute:example-route 14.4. Domain mapping 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. 14.4.1. Mapping a custom domain to a service by using the Developer perspective 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. Note Your custom domain must point to the IP address of the OpenShift Container Platform cluster. Procedure Navigate to the Topology page. Right-click the service you want to map to a domain, and select the Edit option that contains the service name. For example, if the service is named showcase , select the Edit showcase option. In the Advanced options section, click Show advanced Routing options . If the domain mapping CR that you want to map to the service already exists, you can select it in the Domain mapping list. 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 . 14.5. Domain mapping using the Administrator perspective If you do not want to switch to the Developer perspective in the OpenShift Container Platform web console or use the Knative ( kn ) CLI or YAML files, you can use the Administator perspective of the OpenShift Container Platform web console. 14.5.1. Mapping a custom domain to a service by using the Administrator perspective 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. If you have cluster administrator permissions on OpenShift Container Platform (or cluster or dedicated administrator permissions on OpenShift Dedicated or Red Hat OpenShift Service on AWS), you can create a DomainMapping custom resource (CR) by using the Administrator perspective in the web console. Prerequisites You have logged in to the web console. You are in the Administrator perspective. You have installed the OpenShift Serverless Operator. You have installed Knative Serving. You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads. You have created a Knative service and control a custom domain that you want to map to that service. Note Your custom domain must point to the IP address of the cluster. Procedure Navigate to CustomResourceDefinitions and use the search box to find the DomainMapping custom resource definition (CRD). Click the DomainMapping CRD, then navigate to the Instances tab. Click Create DomainMapping . Modify the YAML for the DomainMapping CR so that it includes the following information for your instance: apiVersion: serving.knative.dev/v1beta1 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 domain mapping to a Knative service apiVersion: serving.knative.dev/v1beta1 kind: DomainMapping metadata: name: custom-ksvc-domain.example.com namespace: default spec: ref: name: showcase kind: Service apiVersion: serving.knative.dev/v1 Verification Access the custom domain by using a curl request. For example: Example command USD curl custom-ksvc-domain.example.com Example output {"artifact":"knative-showcase","greeting":"Welcome"} 14.5.2. Restricting cipher suites by using the Administrator perspective When you specify net-kourier for ingress and use DomainMapping , the TLS for OpenShift routing is set to passthrough, and TLS is handled by the Kourier Gateway. In such cases, you might need to restrict which TLS cipher suites for Kourier are allowed for users. Prerequisites You have logged in to the web console. You are in the Administrator perspective. You have installed the OpenShift Serverless Operator. You have installed Knative Serving. You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads. Note Your custom domain must point to the IP address of the cluster. Procedure In the KnativeServing CR, use the cipher-suites value to specify the cipher suites you want to enable: KnativeServing CR example spec: config: kourier: cipher-suites: ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-ECDSA-CHACHA20-POLY1305 Other cipher suites will be disabled. You can specify multiple suites by separating them with commas. Note The Kourier Gateway's container image utilizes the Envoy proxy image, and the default enabled cipher suites depend on the version of the Envoy proxy. 14.6. Securing a mapped service using a TLS certificate 14.6.1. 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. 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: USD oc create secret tls <tls_secret_name> --cert=<path_to_certificate_file> --key=<path_to_key_file> Add the networking.internal.knative.dev/certificate-uid: <id>` label to the Kubernetes TLS secret: USD oc label secret <tls_secret_name> networking.internal.knative.dev/certificate-uid="<id>" 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. Note 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/v1beta1 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 : USD 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: USD curl https://<domain_name> If the certificate is self-signed, skip verification by adding the -k flag to the curl command. 14.6.2. Improving net-kourier memory usage by using secret filtering By default, the informers implementation for the Kubernetes client-go library fetches all resources of a particular type. This can lead to a substantial overhead when many resources are available, which can cause the Knative net-kourier ingress controller to fail on large clusters due to memory leaking. However, a filtering mechanism is available for the Knative net-kourier ingress controller, which enables the controller to only fetch Knative related secrets. The secret filtering is enabled by default on the OpenShift Serverless Operator side. An environment variable, ENABLE_SECRET_INFORMER_FILTERING_BY_CERT_UID=true , is added by default to the net-kourier controller pods. Important If you enable secret filtering, all of your secrets need to be labeled with networking.internal.knative.dev/certificate-uid: "<id>" . Otherwise, Knative Serving does not detect them, which leads to failures. You must label both new and existing secrets. Prerequisites You have cluster administrator permissions on OpenShift Container Platform, or you have cluster or dedicated administrator permissions on Red Hat OpenShift Service on AWS or OpenShift Dedicated. A project that you created or that you have roles and permissions for to create applications and other workloads. Install the OpenShift Serverless Operator and Knative Serving. Install the OpenShift CLI ( oc ). You can disable the secret filtering by setting the ENABLE_SECRET_INFORMER_FILTERING_BY_CERT_UID variable to false by using the workloads field in the KnativeServing custom resource (CR). Example KnativeServing CR apiVersion: operator.knative.dev/v1beta1 kind: KnativeServing metadata: name: knative-serving namespace: knative-serving spec: ... workloads: - env: - container: controller envVars: - name: ENABLE_SECRET_INFORMER_FILTERING_BY_CERT_UID value: 'false' name: net-kourier-controller

Commands:
apiVersion: serving.knative.dev/v1beta1 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
apiVersion: serving.knative.dev/v1beta1 kind: DomainMapping metadata: name: example.com namespace: default spec: ref: name: showcase kind: Service apiVersion: serving.knative.dev/v1
apiVersion: serving.knative.dev/v1beta1 kind: DomainMapping metadata: name: example.com namespace: default spec: ref: name: example-route kind: Route apiVersion: serving.knative.dev/v1
oc apply -f <filename>
kn domain create <domain_mapping_name> --ref <target_name>
kn domain create example.com --ref showcase
kn domain create <domain_mapping_name> --ref <ksvc:service_name:service_namespace>
kn domain create example.com --ref ksvc:showcase:example-namespace
kn domain create <domain_mapping_name> --ref <kroute:route_name>
kn domain create example.com --ref kroute:example-route
apiVersion: serving.knative.dev/v1beta1 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
apiVersion: serving.knative.dev/v1beta1 kind: DomainMapping metadata: name: custom-ksvc-domain.example.com namespace: default spec: ref: name: showcase kind: Service apiVersion: serving.knative.dev/v1
curl custom-ksvc-domain.example.com
artifact: knative-showcase
greeting: Welcome
spec: config: kourier: cipher-suites: ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-ECDSA-CHACHA20-POLY1305
oc create secret tls <tls_secret_name> --cert=<path_to_certificate_file> --key=<path_to_key_file>
oc label secret <tls_secret_name> networking.internal.knative.dev/certificate-uid="<id>"
apiVersion: serving.knative.dev/v1beta1 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>
oc get domainmapping <domain_name>
NAME URL READY REASON example.com https://example.com True
curl https://<domain_name>
apiVersion: operator.knative.dev/v1beta1 kind: KnativeServing metadata: name: knative-serving namespace: knative-serving spec: workloads: - env: - container: controller envVars: - name: ENABLE_SECRET_INFORMER_FILTERING_BY_CERT_UID value: 'false' name: net-kourier-controller