Custom domains for EC

paigecalvert · paigecalvert · commit ebaec1cce815 · 2025-03-17T13:31:25.000-06:00
diff --git a/docs/reference/embedded-config.mdx b/docs/reference/embedded-config.mdx
@@ -34,6 +34,9 @@ spec:
     - name: app
       labels:
        app: "true"
+    domains:
+      proxyRegistryDomain: images.mycompany.com
+      replicatedAppDomain: updates.mycompany.com
   extensions:
     helm:
       repositories:
@@ -148,6 +151,27 @@ spec:
         gpu: "true" # Label applied to "gpu" nodes    
 ```
 
+## domains
+
+You can configure the `domains` key so that Replicated Embedded Cluster uses your custom domains for the Replicated proxy registry and Replicated app service.
+
+When the `domains.proxyRegistryDomain` and `domains.appServiceDomain` fields are set, Embedded Cluster uses the custom domains specified for requests to the proxy service and app service. Embedded Cluster also passes the domains to KOTS to ensure that KOTS uses the same custom domains for requests these services.
+
+If the `domains.proxyRegistryDomain` and `domains.appServiceDomain` fields are not set, Embedded Cluster uses the default Replicated domains.
+
+For more information about adding custom domains to alias Replicated endpoints, see [About Custom Domains](/vendor/custom-domains).
+
+#### Example
+
+```yaml
+apiVersion: embeddedcluster.replicated.com/v1beta1
+kind: Config
+spec:
+  domains:
+    proxyRegistryDomain: images.mycompany.com
+    replicatedAppDomain: updates.mycompany.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.
diff --git a/docs/vendor/custom-domains-using.md b/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**. 
 
@@ -30,6 +28,11 @@ To add and configure a custom domain:
 
     Your changes can take up to 24 hours to propagate.
 
+    TXT records must be created to verify:
+
+      - 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.
+
 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**.
 
     Your changes can take up to 24 hours to propagate.
@@ -59,11 +62,39 @@ 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
+
+You can configure Replicated Embedded Cluster to use your custom domains for the Replicated proxy registry and Replicated app service.
+
+To configure Embedded Cluster to use your custom domains for the proxy registry and app service:
+
+1. Add the custom domains that you want to use for the proxy registry and the app service. See [Add a Custom Domain in the Vendor Portal](#add-domain) above.
+
+1. In the [Embedded Cluster Config](/reference/embedded-config) spec for your application, add `domains.proxyRegistryDomain` and `domains.appServiceDomain`. 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: images.mycompany.com
+        # Your app service custom domain
+        replicatedAppDomain: updates.mycompany.com   
+    ```
+    For more information, see [domains](/reference/embedded-config#domains) in _Embedded Cluster Config_.
+
+1. Save your changes and add the Embedded Cluster Config to a new release. Promote the release to the channel that your team uses for testing and install with Embedded Cluster in a development environment to test your changes.
 
 ### Set a Default Domain
 
@@ -109,7 +140,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.
 
diff --git a/docs/vendor/custom-domains.md b/docs/vendor/custom-domains.md
@@ -1,40 +1,33 @@
 # 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 private registry.
 
-For information about configuring and managing custom domains, see [Using Custom Domains](custom-domains-using).
+For information about adding and assigning 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.
diff --git a/docs/vendor/embedded-overview.mdx b/docs/vendor/embedded-overview.mdx
@@ -119,8 +119,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.
