HOLD FOR RELEASE Custom domains for EC (#3116)

* Custom domains for EC

* edits

* edits

* edits

* edit

* edits

* edits

* edits

* edits

Author: paigecalvert

docs/reference/embedded-config.mdx

@@ -2,19 +2,15 @@
 
 This topic is a reference for the Replicated Embedded Cluster Config custom resource. For more information about Embedded Cluster, see [Using Embedded Cluster](/vendor/embedded-overview).
 
-:::note
-Embedded Cluster is in beta. If you are instead looking for information about creating Kubernetes Installers with Replicated kURL, see the [Replicated kURL](/vendor/packaging-embedded-kubernetes) section.
-:::
-
 ## Overview
 
-To install your application with Embedded Cluster, an Embedded Cluster Config must be created in a release. Embedded Cluster installation artifacts are available only for releases that include an Embedded Cluster Config.
+To install your application with Embedded Cluster, an Embedded Cluster Config must be included in the release. Embedded Cluster installation artifacts are available only for releases that include an Embedded Cluster Config.
 
 The Embedded Cluster Config lets you define several aspects of the Kubernetes cluster that will be created.
 
-### Limitations
+### Limitation
 
-* The Embedded Cluster Config does not support the use of Go template functions, including [KOTS template functions](/reference/template-functions-about).
+The Embedded Cluster Config does not support the use of Go template functions, including [KOTS template functions](/reference/template-functions-about).
 
 For additional property-specific limitations, see the sections below.
 
@@ -34,6 +30,9 @@ spec:
     - name: app
       labels:
        app: "true"
+    domains:
+      proxyRegistryDomain: proxy.yourcompany.com
+      replicatedAppDomain: updates.yourcompany.com
   extensions:
     helm:
       repositories:
@@ -148,6 +147,29 @@ spec:
         gpu: "true" # Label applied to "gpu" nodes    
 ```
 
+## domains
+
+Configure the `domains` key so that Embedded Cluster uses your custom domains for the Replicated proxy registry and Replicated app service.
+
+When `domains.proxyRegistryDomain` and `domains.replicatedAppDomain` are set, Embedded Cluster uses the custom domains specified when making requests to the given service. Embedded Cluster also passes the values to KOTS to ensure that KOTS uses the same domains for these services.
+
+The custom domains that you specify in the `domains.proxyRegistryDomain` and `domains.replicatedAppDomain` fields must be added to the Vendor Portal before they can be used by Embedded Cluster. For more information, see [Add a Custom Domain in the Vendor Portal](/vendor/custom-domains-using#add-domain) in _Using Custom Domains_.
+
+If `domains.proxyRegistryDomain` and `domains.replicatedAppDomain` are not set, Embedded Cluster uses the default Replicated domains. For more information about aliasing Replicated endpoints with custom domains, see [About Custom Domains](/vendor/custom-domains).
+
+#### Example
+
+```yaml
+apiVersion: embeddedcluster.replicated.com/v1beta1
+kind: Config
+spec:
+  domains:
+    # Your proxy registry custom domain
+    proxyRegistryDomain: proxy.yourcompany.com
+    # Your app service custom domain
+    replicatedAppDomain: updates.yourcompany.com    
+```
+
 ## extensions
 
 If you need to install Helm charts before your application and as part of the Embedded Cluster itself, you can do this with Helm extensions. One situation where this is useful is if you want to ship an ingress controller, because Embedded Cluster does not yet include one.

docs/vendor/custom-domains-using.md

@@ -1,16 +1,14 @@
 # Using Custom Domains
 
-This topic describes how to use the Replicated Vendor Portal to add and manage custom domains to alias the Replicated registry, the Replicated proxy registry, the Replicated app service, and the download portal.
+This topic describes how to use the Replicated Vendor Portal to add and manage custom domains to alias the Replicated registry, the Replicated proxy registry, the Replicated app service, and the Download Portal.
 
 For information about adding and managing custom domains with the Vendor API v3, see the [customHostnames](https://replicated-vendor-api.readme.io/reference/createcustomhostname) section in the Vendor API v3 documentation.
 
-For an overview about custom domains and limitations, see [About Custom Domains](custom-domains).
+For more information about custom domains, see [About Custom Domains](custom-domains).
 
-## Configure a Custom Domain
+## Add a Custom Domain in the Vendor Portal {#add-domain}
 
-Before you assign a custom domain for a registry or the download portal, you must first configure and verify the ownership and TLS certificate.
-
-To add and configure a custom domain:
+To add and verify a custom domain:
 
 1. In the [Vendor Portal](https://vendor.replicated.com), go to **Custom Domains**. 
 
@@ -26,13 +24,13 @@ To add and configure a custom domain:
 
 1. For **Create CNAME**, copy the text string and use it to create a CNAME record in your DNS account. Click **Continue**.
 
-1. For **Verify ownership**, copy the text string and use it to create a TXT record in your DNS account if displayed. If a TXT record is not displayed, ownership will be validated automatically using an HTTP token. Click **Validate & continue**.
+1. For **Verify ownership**, ownership will be validated automatically using an HTTP token when possible.
 
-    Your changes can take up to 24 hours to propagate.
+    If ownership cannot be validated automatically, copy the text string provided and use it to create a TXT record in your DNS account. Click **Validate & continue**. Your changes can take up to 24 hours to propagate.
 
-1. For **TLS cert creation verification**, copy the text string and use it to create a TXT record in your DNS account if displayed. If a TXT record is not displayed, ownership will be validated automatically using an HTTP token. Click **Validate & continue**.
+1. For **TLS cert creation verification**, TLS verification will be performed automatically using an HTTP token when possible.
 
-    Your changes can take up to 24 hours to propagate.
+    If TLS verification cannot be performed automatically, copy the text string provided and use it to create a TXT record in your DNS account. Click **Validate & continue**. Your changes can take up to 24 hours to propagate.
 
     :::note
     If you set up a [CAA record](https://letsencrypt.org/docs/caa/) for this hostname, you must include all Certificate Authorities (CAs) that Cloudflare partners with. The following CAA records are required to ensure proper certificate issuance and renewal:
@@ -59,11 +57,37 @@ To add and configure a custom domain:
     Replicated recommends that you do _not_ set a domain as the default until you are ready for it to be used by customers.
     :::
 
-The Vendor Portal marks the domain as **Configured** after the verification checks for ownership and TLS certificate creation are complete.
+    After the verification checks for ownership and TLS certificate creation are complete, the Vendor Portal marks the domain as **Configured**. 
+
+1. (Optional) After a domain is marked as **Configured**, you can remove any TXT records that you created in your DNS account.
 
 ## Use Custom Domains
 
-After you configure one or more custom domains in the Vendor Portal, you assign a custom domain by setting it as the default for all channels and customers or by assigning it to an individual release channel.
+After you add one or more custom domains in the Vendor Portal, you can configure your application to use the domains. 
+
+### Configure Embedded Cluster to Use Custom Domains {#ec}
+
+You can configure Replicated Embedded Cluster to use your custom domains for the Replicated proxy registry and Replicated app service. For more information about Embedded Cluster, see [Embedded Cluster Overview](/vendor/embedded-overview).
+
+To configure Embedded Cluster to use your custom domains for the proxy registry and app service:
+
+1. In the [Embedded Cluster Config](/reference/embedded-config) spec for your application, add `domains.proxyRegistryDomain` and `domains.replicatedAppDomain`. Set each field to your custom domain for the given service.
+
+    **Example:**
+
+    ```yaml
+    apiVersion: embeddedcluster.replicated.com/v1beta1
+    kind: Config
+    spec:
+      domains:
+        # Your proxy registry custom domain
+        proxyRegistryDomain: proxy.yourcompany.com
+        # Your app service custom domain
+        replicatedAppDomain: updates.yourcompany.com   
+    ```
+    For more information, see [domains](/reference/embedded-config#domains) in _Embedded Cluster Config_.
+
+1. Add the Embedded Cluster Config to a new release. Promote the release to a channel that your team uses for testing, and install with Embedded Cluster in a development environment to test your changes.
 
 ### Set a Default Domain
 
@@ -73,6 +97,10 @@ When you set a custom domain as the default, it is used by default for all new r
 
 Only releases that are promoted to a channel _after_ you set a default domain use the new default domain. Any existing releases that were promoted before you set the default continue to use the same domain that they used previously.
 
+:::note
+In Embedded Cluster installations, the KOTS Admin Console will use the domains specified in the `domains.proxyRegistryDomain` and `domains.replicatedAppDomain` fields of the Embedded Cluster Config when making requests to the proxy registry and app service, regardless of the default domain or the domain assigned to the given release channel. For more information about using custom domains in Embedded Cluster installations, see [Configure Embedded Cluster to Use Custom Domains](#ec) above.
+:::
+
 To set a custom domain as the default:
 
 1. In the Vendor Portal, go to **Custom Domains**.
@@ -89,6 +117,10 @@ Assigning a domain to a release channel is useful when you need to override eith
 * You need to use a different domain for releases promoted to your Beta and Stable channels.
 * You need to test a domain in a development environment before you set the domain as the default for all channels.
 
+:::note
+In Embedded Cluster installations, the KOTS Admin Console will use the domains specified in the `domains.proxyRegistryDomain` and `domains.replicatedAppDomain` fields of the Embedded Cluster Config when making requests to the proxy registry and app service, regardless of the default domain or the domain assigned to the given release channel. For more information about using custom domains in Embedded Cluster installations, see [Configure Embedded Cluster to Use Custom Domains](#ec) above.
+:::
+
 To assign a custom domain to a channel:
 
 1. In the Vendor Portal, go to **Channels** and click the settings icon for the target channel.
@@ -109,7 +141,7 @@ To reuse a custom domain for another application:
 
 1. Click **Custom Domains**.
 
-1. In the section for the target endpoint, click Add your first custom domain for your first domain, or click **Add new domain** for additional domains.
+1. In the section for the target endpoint, click **Add your first custom domain** for your first domain, or click **Add new domain** for additional domains.
 
     The **Configure a custom domain** wizard opens.
 

docs/vendor/custom-domains.md

@@ -1,40 +1,35 @@
 # About Custom Domains
 
-This topic provides an overview and the limitations of using custom domains to alias the Replicated private registry, Replicated proxy registry, Replicated app service, and the Download Portal.
+This topic provides an overview and the limitations of using custom domains to alias the Replicated proxy registry, the Replicated app service, the Replicated Download Portal, and the Replicated registry.
 
-For information about configuring and managing custom domains, see [Using Custom Domains](custom-domains-using).
+For information about adding and managing custom domains, see [Using Custom Domains](custom-domains-using).
 
 ## Overview
 
 You can use custom domains to alias Replicated endpoints by creating Canonical Name (CNAME) records for your domains.
 
 Replicated domains are external to your domain and can require additional security reviews by your customer. Using custom domains as aliases can bring the domains inside an existing security review and reduce your exposure.
 
-TXT records must be created to verify:
+You can configure custom domains for the following services:
 
-- Domain ownership: Domain ownership is verified when you initially add a record.
-- TLS certificate creation: Each new domain must have a new TLS certificate to be verified.
+- **Proxy registry:** Images can be proxied from external private registries using the Replicated proxy registry. By default, the proxy registry uses the domain `proxy.replicated.com`. Replicated recommends using a CNAME such as `proxy.{your app name}.com`. 
 
-The TXT records can be removed after the verification is complete.
+- **Replicated app service:** Upstream application YAML and metadata, including a license ID, are pulled from the app service. By default, this service uses the domain `replicated.app`. Replicated recommends using a CNAME such as `updates.{your app name}.com`. 
 
-You can configure custom domains for the following services, so that customer-facing URLs reflect your company's brand:
+- **Download Portal:** The Download Portal can be used to share customer license files, air gap bundles, and so on. By default, the Download Portal uses the domain `get.replicated.com`. Replicated recommends using a CNAME such as `portal.{your app name}.com` or `enterprise.{your app name}.com`. 
 
-- **Replicated registry:** Images and Helm charts can be pulled from the Replicated registry. By default, this registry uses the domain `registry.replicated.com`. We suggest using a CNAME such as `registry.{your app name}.com`. 
-
-- **Proxy registry:** Images can be proxied from external private registries using the Replicated proxy registry. By default, the proxy registry uses the domain `proxy.replicated.com`. We suggest using a CNAME such as `proxy.{your app name}.com`. 
-
-- **Replicated app service:** Upstream application YAML and metadata, including a license ID, are pulled from replicated.app. By default, this service uses the domain `replicated.app`. We suggest using a CNAME such as `updates.{your app name}.com`. 
-
-- **Download Portal:** The Download Portal can be used to share customer license files, air gap bundles, and so on. By default, the Download Portal uses the domain `get.replicated.com`. We suggest using a CNAME such as `portal.{your app name}.com` or `enterprise.{your app name}.com`. 
+- **Replicated registry:** Images and Helm charts can be pulled from the Replicated registry. By default, this registry uses the domain `registry.replicated.com`. Replicated recommends using a CNAME such as `registry.{your app name}.com`.
 
 ## Limitations
 
 Using custom domains has the following limitations:
 
 - A single custom domain cannot be used for multiple endpoints. For example, a single domain can map to `registry.replicated.com` for any number of applications, but cannot map to both `registry.replicated.com` and `proxy.replicated.com`, even if the applications are different.
 
-- Custom domains cannot be used to alias api.replicated.com (legacy customer-facing APIs) or kURL.
+- Custom domains cannot be used to alias `api.replicated.com` (legacy customer-facing APIs) or kURL.
 
 - Multiple custom domains can be configured, but only one custom domain can be the default for each Replicated endpoint. All configured custom domains work whether or not they are the default.
 
-- A particular custom domain can only be used by one team.
+- Each custom domain can only be used by one team.
+
+- For [Replicated Embedded Cluster](/vendor/embedded-overview) installations, any Helm [`extensions`](/reference/embedded-config) that you add in the Embedded Cluster Config do not use custom domains. During deployment, Embedded Cluster pulls both the repo for the given chart and any images in the chart as written. Embedded Cluster does not rewrite image names to use custom domains.

docs/vendor/embedded-overview.mdx

@@ -117,8 +117,6 @@ Embedded Cluster has the following limitations:
 
 * **Kubernetes version template functions not supported**: The KOTS [KubernetesVersion](/reference/template-functions-static-context#kubernetesversion), [KubernetesMajorVersion](/reference/template-functions-static-context#kubernetesmajorversion), and [KubernetesMinorVersion](/reference/template-functions-static-context#kubernetesminorversion) template functions do not provide accurate Kubernetes version information for Embedded Cluster installations. This is because these template functions are rendered before the Kubernetes cluster has been updated to the intended version. However, `KubernetesVersion` is not necessary for Embedded Cluster because vendors specify the Embedded Cluster version, which includes a known Kubernetes version.
 
-* **Custom domains not supported**: Embedded Cluster does not support the use of custom domains, even if custom domains are configured. We intend to add support for custom domains. For more information about custom domains, see [About Custom Domains](/vendor/custom-domains). 
-
 * **KOTS Auto-GitOps workflow not supported**: Embedded Cluster does not support the KOTS Auto-GitOps workflow. If an end-user is interested in GitOps, consider the Helm install method instead. For more information, see [Installing with Helm](/vendor/install-with-helm).
 
 * **Downgrading Kubernetes not supported**: Embedded Cluster does not support downgrading Kubernetes. The admin console will not prevent end-users from attempting to downgrade Kubernetes if a more recent version of your application specifies a previous Embedded Cluster version. You must ensure that you do not promote new versions with previous Embedded Cluster versions.