Document DNS Auto Allocation Version 2 (#15931)

* Document DNS Auto Allocation Version 2 Signed-off-by: Faseela K <[email protected]> * fix gencheck Signed-off-by: Faseela K <[email protected]> * fix tests Signed-off-by: Faseela K <[email protected]> * fix lint Signed-off-by: Faseela K <[email protected]> * review comments Signed-off-by: Faseela K <[email protected]> * review comments Signed-off-by: Faseela K <[email protected]> * fix lint Signed-off-by: Faseela K <[email protected]> * Update index.md * Update index.md --------- Signed-off-by: Faseela K <[email protected]>
istio · Nov 15, 2024 · 2e90b6c · 2e90b6c
1 parent 9c0119c
commit 2e90b6c
Show file tree

Hide file tree

Showing 3 changed files with 126 additions and 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
@@ -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
@@ -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
@@ -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