Chapter 8. Configuring custom domains for Knative services

Procedure

1. 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.com
    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.com
    namespace: default
   spec:
    ref:
      name: example-route
      kind: Route
      apiVersion: serving.knative.dev/v1

2. Apply the DomainMapping CR as a YAML file:

   $ oc apply -f <filename>

Procedure

1. Navigate to the Topology page.
2. 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.

3. 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".
4. Click Save to save the changes to your service.

Verification

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

Procedure

1. Navigate to CustomResourceDefinitions and use the search box to find the DomainMapping custom resource definition (CRD).
2. Click the DomainMapping CRD, then navigate to the Instances tab.
3. Click Create DomainMapping.

4. Modify the YAML for the DomainMapping CR so that it includes the following information for your instance:

   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 domain mapping to a Knative service

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

Procedure

1. Create a Kubernetes TLS secret:

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

2. Add the networking.internal.knative.dev/certificate-uid: <id>` label to the Kubernetes TLS secret:

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

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

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

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