Document DNS capture configuration for ServiceEntry resources

Added new module documenting the requirement to explicitly configure
DNS capture when migrating from Service Mesh 2.6 to 3.0 if using
ServiceEntry resources for external services.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: lhite8041

.gitignore

@@ -19,3 +19,4 @@ commercial_package
 .vale/styles/AsciiDocDITA
 .vale/styles/OpenShiftAsciiDoc
 .vale/styles/RedHat
+migrating/JIRA-9894-dns-capture-documentation-plan.md

migrating/checklists/ossm-migrating-read-me.adoc

@@ -38,6 +38,8 @@ include::modules/ossm-migrating-read-me-kubernetes-network-policy-management.ado
 
 include::modules/ossm-migrating-read-me-tls-configuration-change.adoc[leveloffset=+1]
 
+include::modules/ossm-migrating-read-me-dns-capture-configuration.adoc[leveloffset=+1]
+
 [role="_additional-resources"]
 [id="additional-resources_{context}"]
 == Additional resources

modules/ossm-migrating-2-and-3-differences.adoc

@@ -23,5 +23,6 @@ If you are a current {SMProductName} user, there are several important differenc
 * Support for Istioctl
 * Change to Kubernetes network policy management
 * Transport layer security (TLS) configuration change
+* DNS capture configuration for ServiceEntry resources
 
 You must be using {SMProduct} 2.6 to migrate to {SMProduct} 3.

modules/ossm-migrating-read-me-dns-capture-configuration.adoc

@@ -0,0 +1,20 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/migrating/checklists/ossm-migrating-read-me.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-migrating-read-me-dns-capture-configuration_{context}"]
+= DNS capture configuration for ServiceEntry resources
+
+[role="_abstract"]
+
+If your workloads use `ServiceEntry` resources to access external services through DNS names, you must explicitly configure DNS capture in the proxy metadata settings when migrating to {SMProductName} 3.0. Without DNS capture enabled, applications encounter DNS resolution failures with errors such as `Name or service not known`.
+
+{SMProduct} 2.6 enabled DNS capture by default to support federation, which did not align with the upstream {istio} project. {SMProduct} 3.0 removes this default configuration and aligns with the upstream project's multicluster topologies.
+
+To configure DNS capture in {SMProduct} 3.0, set the `ISTIO_META_DNS_AUTO_ALLOCATE` and `ISTIO_META_DNS_CAPTURE` fields to `true` in the `spec.values.meshConfig.defaultConfig.proxyMetadata` path of your `{istio}` resource. 
+
+[NOTE]
+====
+The equivalent of `spec.values.meshConfig.defaultConfig.proxyMetadata` in {SMProduct} 2.6 was `spec.proxy.runtime.container.env`.
+====