diff --git a/applications/configuration-as-code/services/web-service.mdx b/applications/configuration-as-code/services/web-service.mdx
index 50bad48..9d6dc39 100644
--- a/applications/configuration-as-code/services/web-service.mdx
+++ b/applications/configuration-as-code/services/web-service.mdx
@@ -57,12 +57,18 @@ services:
 
 <Badge shape="pill" color="gray">Optional</Badge>
 
-When `true`, the service is only accessible within the cluster (not publicly exposed).
+When `true`, the service is routed through the cluster's internal load balancer and is only reachable from clients on the same private network (for example, a VPN or peered VPC). Public traffic is not accepted.
 
 ```yaml
 private: true
 ```
 
+<Info>
+Private web services require an internal load balancer controller to be installed on the target cluster. Porter validates this when you create or update an app — if the controller is not installed, the request is rejected with an `invalid_load_balancer_mode` error. In the dashboard, the **Internal** load-balancer option only appears when the controller is detected. Contact Porter support if you need the internal load balancer enabled on a cluster.
+
+Private services use a different CNAME target than public services. After enabling `private: true`, copy the load-balancer hostname shown in the **Networking** tab of your web service when configuring DNS for any custom domains — do not reuse the public hostname.
+</Info>
+
 ---
 
 ## `disableTLS`
diff --git a/applications/configure/custom-domains.mdx b/applications/configure/custom-domains.mdx
index ace5ebe..bddda55 100644
--- a/applications/configure/custom-domains.mdx
+++ b/applications/configure/custom-domains.mdx
@@ -26,6 +26,10 @@ The DNS records that need to be created for your Web service vary slightly depen
 
 Copy this address, as you will need it to create the DNS record.
 
+<Info>
+Public and private (internal) web services use different load-balancer hostnames. The address shown in the **Networking** tab always reflects the load balancer that backs the service's current mode, so copy it from the same service you're attaching the domain to. If you switch a service between public and internal, the hostname changes and you must update your DNS record to match.
+</Info>
+
 ### Google Cloud and Azure
 
 On Google Cloud and Azure, the load balancer that sits in front of your infrastructure has a static IP address.