×

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, 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

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.

  • 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
  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>

Creating a custom domain mapping by using the Knative CLI

You can use the 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.

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. The examples in the following procedure show the prefixes for mapping to 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 kn CLI tool.

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.com --ref example-service
  • 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.com --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.com --ref kroute:example-route