Configuring custom domains

Feature Availability: beta since Knative v0.24

  • beta features are well-tested and enabling them is considered safe. Support for the overall feature will not be dropped, though details may change in incompatible ways.

Each Knative Service is automatically assigned a default domain name when it is created. However, you can map any custom domain name that you own to a Knative Service, by using domain mapping.

You can create a DomainMapping object to map a single, non-wildcard domain to a specific Knative Service.

For example, if you own the domain name example.org, and you configure the domain DNS to reference your Knative cluster, you can use domain mapping to serve a Knative Service at this domain.

Note

If you create a domain mapping to map to a private Knative Service, the private Knative Service will be accessible from public internet with the custom domain of the domain mapping.

Prerequisites

  • You must have access to a Kubernetes cluster, with Knative Serving and an Ingress implementation installed. For more information, see the Installation documentation.
  • You must have the domain mapping feature enabled on your cluster.
  • You must have access to a Knative service that you can map a domain to.
  • You must own or have access to a domain name to map, and be able to change the domain DNS to point to your Knative cluster by using the tools provided by your domain registrar.

Procedure

  1. By default, in order to create a DomainMapping you, or a cluster administrator, must first delegate the domain name to the namespace you wish to create the DomainMapping in by creating a ClusterDomainClaim. ClusterDomainClaims delegate a domain name to a namespace, so that DomainMappings in that namespace can use the domain name.

    Create a ClusterDomainClaim by entering the following command:

    1. kubectl apply -f - <<EOF
    2. apiVersion: networking.internal.knative.dev/v1alpha1
    3. kind: ClusterDomainClaim
    4. metadata:
    5.   name: <domain-name>
    6. spec:
    7.   namespace: <namespace>
    8. EOF

    Tip

    You can avoid this step by setting the autocreateClusterDomainClaims property to “true” in the config-network config map, in the knative-serving namespace. This allows any user, in any namespace, to map any domain name, even ones in other namespaces or for domain names that they do not own.

  2. Create a DomainMapping object by entering the following command:

    1. kubectl apply -f - <<EOF
    2. apiVersion: serving.knative.dev/v1alpha1
    3. kind: DomainMapping
    4. metadata:
    5.   name: <domain-name>
    6.   namespace: <namespace>
    7. spec:
    8.   ref:
    9.     name: <service-name>
    10.     kind: Service
    11.     apiVersion: serving.knative.dev/v1
    12. EOF

    Where:

    • <domain-name> is the domain name that you want to map a Service to.
    • <namespace> is the namespace that contains both the DomainMapping and Service objects.
    • <service-name> is the name of the service that will be mapped to the domain.

    Tip

    You can also map to other targets as long as they conform to the Addressable contract and their resolved URL is of the form {name}.{namespace}.{clusterdomain}, where {name} and {namespace} are the name and namespace of a Kubernetes service, and {clusterdomain}is the cluster domain. Examples of objects that conform to this contract include Knative Services, Routes, and Kubernetes services.

  3. Point the domain name to the IP address of your Knative cluster. Details of this step differ depending on your domain registrar.