From 1e2103468a88cacd8d72b05e3d8929c46a0fc304 Mon Sep 17 00:00:00 2001 From: Julz Friedman Date: Mon, 9 Nov 2020 11:34:01 +0000 Subject: [PATCH 1/6] Add DomainMapping docs --- docs/serving/creating-domain-mappings.md | 57 ++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 docs/serving/creating-domain-mappings.md diff --git a/docs/serving/creating-domain-mappings.md b/docs/serving/creating-domain-mappings.md new file mode 100644 index 00000000000..01cff0f9e1c --- /dev/null +++ b/docs/serving/creating-domain-mappings.md @@ -0,0 +1,57 @@ +--- +title: "Creating a Mapping between a Custom Domain Name and a Knative Service (Alpha)" +linkTitle: "Creating Domain Mappings (Alpha)" +weight: 64 +type: "docs" +--- + +If the Domain Mapping feature is installed, you can serve +custom domains backed by Knative Services. For example, if you +own the "MyDomain.com" domain name, you can point DNS at your +Knative cluster, and have this domain name be served by a +Knative Service. + +## Before you begin + +To map a custom domain to a Knative Service, you should first [create a Knative +Service](https://knative.dev/docs/serving/creating-services/). + +## Creating a Domain Mapping + +To create a mapping from a custom domain to a Knative Service, you need to +create a YAML file that defines a Domain Mapping. +This YAML file specifies the domain name to map and the Knative Service to use +to service requests. + +You will also need to point the domain name at your Knative cluster using the +tools provided by your domain registrar. + +### Procedure + +1. Create a new file named `domainmapping.yaml` containing the following information. + ```yaml + apiVersion: serving.knative.dev/v1alpha1 + kind: DomainMapping + metadata: + name: mydomain.com + namespace: default + spec: + ref: + name: helloworld-go + kind: Service + apiVersion: serving.knative.dev/v1 + ``` + * `name`(metadata): The domain name you wish to map to the Knative Service. + * `namespace`: The namespace that both the DomainMapping and Knative Service use. + * `name`(ref): The Knative Service which should be used to service requests + for the custom domain name. + +1. From the directory where the new `domainmapping.yaml` file was created, + deploy the domain mapping by applying the `domainmapping.yaml` file. + ``` + kubectl apply --filename domainmapping.yaml + ``` + +1. You will also need to point the "mydomain.com" domain name at the IP address + of your Knative cluster. Details of this step differ depending on your + domain registrar. From c833440a3bb364c55fa2a1eca6418d6e10c995a9 Mon Sep 17 00:00:00 2001 From: Julz Friedman Date: Mon, 9 Nov 2020 13:26:11 +0000 Subject: [PATCH 2/6] x --- docs/serving/creating-domain-mappings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/serving/creating-domain-mappings.md b/docs/serving/creating-domain-mappings.md index 01cff0f9e1c..326029e672f 100644 --- a/docs/serving/creating-domain-mappings.md +++ b/docs/serving/creating-domain-mappings.md @@ -36,7 +36,7 @@ tools provided by your domain registrar. name: mydomain.com namespace: default spec: - ref: + ref: name: helloworld-go kind: Service apiVersion: serving.knative.dev/v1 From bbf2810ec923bdcf9513958f44e85a608857fb77 Mon Sep 17 00:00:00 2001 From: Julz Friedman Date: Mon, 9 Nov 2020 13:42:23 +0000 Subject: [PATCH 3/6] My oh my --- docs/serving/creating-domain-mappings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/serving/creating-domain-mappings.md b/docs/serving/creating-domain-mappings.md index 326029e672f..6e0fdaa0339 100644 --- a/docs/serving/creating-domain-mappings.md +++ b/docs/serving/creating-domain-mappings.md @@ -7,7 +7,7 @@ type: "docs" If the Domain Mapping feature is installed, you can serve custom domains backed by Knative Services. For example, if you -own the "MyDomain.com" domain name, you can point DNS at your +own the "mydomain.com" domain name, you can point DNS at your Knative cluster, and have this domain name be served by a Knative Service. From 0ee4dc6585e96028d67f8a232d8b95f70494e22b Mon Sep 17 00:00:00 2001 From: Julz Friedman Date: Mon, 9 Nov 2020 13:50:16 +0000 Subject: [PATCH 4/6] Add paragraph about wildcard (lack of) behaviour --- docs/serving/creating-domain-mappings.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/serving/creating-domain-mappings.md b/docs/serving/creating-domain-mappings.md index 6e0fdaa0339..2c108ab20af 100644 --- a/docs/serving/creating-domain-mappings.md +++ b/docs/serving/creating-domain-mappings.md @@ -26,6 +26,11 @@ to service requests. You will also need to point the domain name at your Knative cluster using the tools provided by your domain registrar. +Domain Mappings map a single, non-wildcard domain to a specific Knative +Service. For example in the example yaml below, the "mydomain.com" Domain +Mapping maps only "mydomain.com" and not "www.mydomain.com". You can create +multiple Domain Mappings to map multiple domains. + ### Procedure 1. Create a new file named `domainmapping.yaml` containing the following information. From 573944cad6cb4b7916879cba19911765c8733455 Mon Sep 17 00:00:00 2001 From: Julz Friedman Date: Mon, 4 Jan 2021 10:04:41 +0000 Subject: [PATCH 5/6] Update description and link to install docs --- docs/serving/creating-domain-mappings.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/serving/creating-domain-mappings.md b/docs/serving/creating-domain-mappings.md index 2c108ab20af..057ca249ad9 100644 --- a/docs/serving/creating-domain-mappings.md +++ b/docs/serving/creating-domain-mappings.md @@ -5,15 +5,20 @@ weight: 64 type: "docs" --- -If the Domain Mapping feature is installed, you can serve -custom domains backed by Knative Services. For example, if you -own the "mydomain.com" domain name, you can point DNS at your -Knative cluster, and have this domain name be served by a -Knative Service. +Knative Services are automatically given a default domain name based on the +cluster configuration, e.g. "mysvc.mynamespace.mydomain". You can also map a +single custom domain name that you own to a specific Knative Service using the +Domain Mapping feature, if enabled. + +For example, if you own the "mydomain.com" domain name, and configure its DNS +to reference your Knative cluster, you can use the DomainMapping feature to +have this domain be served by a Knative Service. ## Before you begin -To map a custom domain to a Knative Service, you should first [create a Knative +1. You need to enable the DomainMapping feature (and a supported Knative + Ingress implementation) to use it. See [the Install instructions](../install/). +1. To map a custom domain to a Knative Service, you should first [create a Knative Service](https://knative.dev/docs/serving/creating-services/). ## Creating a Domain Mapping From a3301c679ed4586a215635de0345f308478232fc Mon Sep 17 00:00:00 2001 From: Julz Friedman Date: Thu, 21 Jan 2021 10:56:53 +0000 Subject: [PATCH 6/6] Update link, use example.org domain, and elaborate contract for Ref --- docs/serving/creating-domain-mappings.md | 36 +++++++++++++++--------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/docs/serving/creating-domain-mappings.md b/docs/serving/creating-domain-mappings.md index 057ca249ad9..cdb3f821afd 100644 --- a/docs/serving/creating-domain-mappings.md +++ b/docs/serving/creating-domain-mappings.md @@ -10,31 +10,34 @@ cluster configuration, e.g. "mysvc.mynamespace.mydomain". You can also map a single custom domain name that you own to a specific Knative Service using the Domain Mapping feature, if enabled. -For example, if you own the "mydomain.com" domain name, and configure its DNS +For example, if you own the "example.org" domain name, and configure its DNS to reference your Knative cluster, you can use the DomainMapping feature to have this domain be served by a Knative Service. ## Before you begin 1. You need to enable the DomainMapping feature (and a supported Knative - Ingress implementation) to use it. See [the Install instructions](../install/). + Ingress implementation) to use it. See [the Install instructions](../install/any-kubernetes-cluster/#optional-serving-extensions). 1. To map a custom domain to a Knative Service, you should first [create a Knative Service](https://knative.dev/docs/serving/creating-services/). +1. You will need a Domain Name to map, and the ability to change its DNS to + point to your Knative Cluster. The details of this step are dependant on + your domain registrar. ## Creating a Domain Mapping -To create a mapping from a custom domain to a Knative Service, you need to -create a YAML file that defines a Domain Mapping. -This YAML file specifies the domain name to map and the Knative Service to use -to service requests. +To create a mapping from a custom domain name that you control to a Knative +Service, you need to create a YAML file that defines a Domain Mapping. This +YAML file specifies the domain name to map and the Knative Service to use to +service requests. You will also need to point the domain name at your Knative cluster using the tools provided by your domain registrar. Domain Mappings map a single, non-wildcard domain to a specific Knative -Service. For example in the example yaml below, the "mydomain.com" Domain -Mapping maps only "mydomain.com" and not "www.mydomain.com". You can create -multiple Domain Mappings to map multiple domains. +Service. For example in the example yaml below, the "example.org" Domain +Mapping maps only "example.org" and not "www.example.org". You can create +multiple Domain Mappings to map multiple domains and subdomains. ### Procedure @@ -43,7 +46,7 @@ multiple Domain Mappings to map multiple domains. apiVersion: serving.knative.dev/v1alpha1 kind: DomainMapping metadata: - name: mydomain.com + name: example.org namespace: default spec: ref: @@ -54,7 +57,12 @@ multiple Domain Mappings to map multiple domains. * `name`(metadata): The domain name you wish to map to the Knative Service. * `namespace`: The namespace that both the DomainMapping and Knative Service use. * `name`(ref): The Knative Service which should be used to service requests - for the custom domain name. + for the custom domain name. 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. Objects conforming to this contract include Knative + Services and Routes, and Kubernetes Services. 1. From the directory where the new `domainmapping.yaml` file was created, deploy the domain mapping by applying the `domainmapping.yaml` file. @@ -62,6 +70,6 @@ multiple Domain Mappings to map multiple domains. kubectl apply --filename domainmapping.yaml ``` -1. You will also need to point the "mydomain.com" domain name at the IP address - of your Knative cluster. Details of this step differ depending on your - domain registrar. +1. You will also need to point the "example.org" domain name at the IP + address of your Knative cluster. Details of this step differ depending on + your domain registrar.