From 2e90b6ce9ba279c527ab1a116284db92e4cc8223 Mon Sep 17 00:00:00 2001
From: Faseela K <faseela.k@est.tech>
Date: Fri, 15 Nov 2024 01:06:35 +0100
Subject: [PATCH] Document DNS Auto Allocation Version 2 (#15931)

* Document DNS Auto Allocation Version 2

Signed-off-by: Faseela K <faseela.k@est.tech>

* fix gencheck

Signed-off-by: Faseela K <faseela.k@est.tech>

* fix tests

Signed-off-by: Faseela K <faseela.k@est.tech>

* fix lint

Signed-off-by: Faseela K <faseela.k@est.tech>

* review comments

Signed-off-by: Faseela K <faseela.k@est.tech>

* review comments

Signed-off-by: Faseela K <faseela.k@est.tech>

* fix lint

Signed-off-by: Faseela K <faseela.k@est.tech>

* Update index.md

* Update index.md

---------

Signed-off-by: Faseela K <faseela.k@est.tech>
---
 .../traffic-management/dns-proxy/index.md     | 62 +++++++++++++++++++
 .../traffic-management/dns-proxy/snips.sh     | 51 +++++++++++++++
 .../traffic-management/dns-proxy/test.sh      | 14 ++++-
 3 files changed, 126 insertions(+), 1 deletion(-)

diff --git a/content/en/docs/ops/configuration/traffic-management/dns-proxy/index.md b/content/en/docs/ops/configuration/traffic-management/dns-proxy/index.md
index bafd75f830b2d..90309220190f5 100644
--- a/content/en/docs/ops/configuration/traffic-management/dns-proxy/index.md
+++ b/content/en/docs/ops/configuration/traffic-management/dns-proxy/index.md
@@ -100,6 +100,10 @@ to [the following section](#external-tcp-services-without-vips) for more details
 
 To work around these issues, the DNS proxy additionally supports automatically allocating addresses for `ServiceEntry`s that do not explicitly define one. This is configured by the `ISTIO_META_DNS_AUTO_ALLOCATE` option.
 
+{{< tip >}}
+Please see [DNS Auto Allocation V2](/docs/ops/configuration/traffic-management/dns-proxy/#dns-auto-allocation-v2) for a new enhanced implementation of auto allocation supported by Istio from 1.23 onwards. DNS Auto Allocation V2 is recommended for sidecar mode and required for ambient mode.
+{{< /tip >}}
+
 When this feature is enabled, the DNS response will include a distinct and automatically assigned address for each `ServiceEntry`. The proxy is then configured to match requests to this IP address, and forward the request to the corresponding `ServiceEntry`. When using `ISTIO_META_DNS_AUTO_ALLOCATE`, Istio will automatically allocate non-routable VIPs (from the Class E subnet) to such services as long as they do not use a wildcard host. The Istio agent on the sidecar will use the VIPs as responses to the DNS lookup queries from the application. Envoy can now clearly distinguish traffic bound for each external TCP service and forward it to the right target. For more information check respective [Istio blog about smart DNS proxying](/blog/2020/dns-proxy/#automatic-vip-allocation-where-possible).
 
 {{< warning >}}
@@ -219,6 +223,64 @@ A virtual IP address will be assigned to every service entry so that client side
     ADDRESS=240.240.69.138, DESTINATION=Cluster: outbound|9000||tcp-echo.external-1.svc.cluster.local
     {{< /text >}}
 
+## DNS Auto Allocation V2
+
+Istio now offers an enhanced implementation of DNS Auto Allocation. To use the new feature, replace the `MeshConfig` flag `ISTIO_META_DNS_AUTO_ALLOCATE`, which was used in the previous example, with the pilot environment variable `PILOT_ENABLE_IP_AUTOALLOCATE` while installing Istio. All examples given so far would work as is.
+
+{{< text bash >}}
+$ cat <<EOF | istioctl install -y -f -
+apiVersion: install.istio.io/v1alpha1
+kind: IstioOperator
+spec:
+  values:
+    pilot:
+      env:
+        # Enable automatic address allocation, optional
+        PILOT_ENABLE_IP_AUTOALLOCATE: "true"
+  meshConfig:
+    defaultConfig:
+      proxyMetadata:
+        # Enable basic DNS proxying
+        ISTIO_META_DNS_CAPTURE: "true"
+    # discoverySelectors configuration below is just used for simulating the external service TCP scenario,
+    # so that we do not have to use an external site for testing.
+    discoverySelectors:
+    - matchLabels:
+        istio-injection: enabled
+EOF
+{{< /text >}}
+
+Users also have the flexibility for more granular configuration by adding the label `networking.istio.io/enable-autoallocate-ip="true/false"` to their `ServiceEntry`. This label configures whether a `ServiceEntry` without any `spec.addresses` set should get an IP address automatically allocated for it.
+
+To try this out, update the existing `ServiceEntry` with the opt-out label:
+
+{{< text bash >}}
+$ kubectl apply -f - <<EOF
+apiVersion: networking.istio.io/v1
+kind: ServiceEntry
+metadata:
+  name: external-auto
+  labels:
+    networking.istio.io/enable-autoallocate-ip: "false"
+spec:
+  hosts:
+  - auto.internal
+  ports:
+  - name: http
+    number: 80
+    protocol: HTTP
+  resolution: DNS
+EOF
+{{< /text >}}
+
+Now, send a request and verify that the auto allocation is no longer happening:
+
+{{< text bash >}}
+$ kubectl exec deploy/curl -- curl -sS -v auto.internal
+* Could not resolve host: auto.internal
+* shutting down connection #0
+{{< /text >}}
+
 ## Cleanup
 
 {{< text bash >}}
diff --git a/content/en/docs/ops/configuration/traffic-management/dns-proxy/snips.sh b/content/en/docs/ops/configuration/traffic-management/dns-proxy/snips.sh
index 00cf65d372640..e412f24fd76a8 100644
--- a/content/en/docs/ops/configuration/traffic-management/dns-proxy/snips.sh
+++ b/content/en/docs/ops/configuration/traffic-management/dns-proxy/snips.sh
@@ -160,6 +160,57 @@ ADDRESS=240.240.105.94, DESTINATION=Cluster: outbound|9000||tcp-echo.external-2.
 ADDRESS=240.240.69.138, DESTINATION=Cluster: outbound|9000||tcp-echo.external-1.svc.cluster.local
 ENDSNIP
 
+snip_dns_auto_allocation_v2_1() {
+cat <<EOF | istioctl install -y -f -
+apiVersion: install.istio.io/v1alpha1
+kind: IstioOperator
+spec:
+  values:
+    pilot:
+      env:
+        # Enable automatic address allocation, optional
+        PILOT_ENABLE_IP_AUTOALLOCATE: "true"
+  meshConfig:
+    defaultConfig:
+      proxyMetadata:
+        # Enable basic DNS proxying
+        ISTIO_META_DNS_CAPTURE: "true"
+    # discoverySelectors configuration below is just used for simulating the external service TCP scenario,
+    # so that we do not have to use an external site for testing.
+    discoverySelectors:
+    - matchLabels:
+        istio-injection: enabled
+EOF
+}
+
+snip_dns_auto_allocation_v2_2() {
+kubectl apply -f - <<EOF
+apiVersion: networking.istio.io/v1
+kind: ServiceEntry
+metadata:
+  name: external-auto
+  labels:
+    networking.istio.io/enable-autoallocate-ip: "false"
+spec:
+  hosts:
+  - auto.internal
+  ports:
+  - name: http
+    number: 80
+    protocol: HTTP
+  resolution: DNS
+EOF
+}
+
+snip_dns_auto_allocation_v2_3() {
+kubectl exec deploy/curl -- curl -sS -v auto.internal
+}
+
+! IFS=$'\n' read -r -d '' snip_dns_auto_allocation_v2_3_out <<\ENDSNIP
+* Could not resolve host: auto.internal
+* shutting down connection #0
+ENDSNIP
+
 snip_cleanup_1() {
 kubectl -n external-1 delete -f samples/tcp-echo/tcp-echo.yaml
 kubectl -n external-2 delete -f samples/tcp-echo/tcp-echo.yaml
diff --git a/content/en/docs/ops/configuration/traffic-management/dns-proxy/test.sh b/content/en/docs/ops/configuration/traffic-management/dns-proxy/test.sh
index d9025032c28d2..add242f9565b1 100644
--- a/content/en/docs/ops/configuration/traffic-management/dns-proxy/test.sh
+++ b/content/en/docs/ops/configuration/traffic-management/dns-proxy/test.sh
@@ -27,7 +27,7 @@ snip_getting_started_1
 # deploy test application
 snip_dns_capture_in_action_2
 
-# configure service entries and verify
+# configure service entries #and verify
 snip_dns_capture_in_action_1
 _verify_contains snip_dns_capture_in_action_3 "$snip_dns_capture_in_action_3_out"
 
@@ -45,6 +45,18 @@ _verify_lines snip_external_tcp_services_without_vips_5 "
 + outbound|9000||tcp-echo.external-1.svc.cluster.local
 "
 
+# enable enhanced dns auto allocation and verify all the above steps once again
+snip_dns_auto_allocation_v2_1
+_verify_contains snip_dns_capture_in_action_3 "$snip_dns_capture_in_action_3_out"
+_verify_contains snip_address_auto_allocation_2 "*   Trying 240.240."
+_verify_lines snip_external_tcp_services_without_vips_5 "
++ outbound|9000||tcp-echo.external-2.svc.cluster.local
++ outbound|9000||tcp-echo.external-1.svc.cluster.local
+"
+# verify opt-out
+snip_dns_auto_allocation_v2_2
+_verify_contains snip_dns_auto_allocation_v2_3  "$snip_dns_auto_allocation_v2_3_out"
+
 # @cleanup
 
 snip_cleanup_1