Document DNS Auto Allocation Version 2

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.
+{{< /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 feature flag `ISTIO_META_DNS_AUTO_ALLOCATE`, which was used in the previous example, with `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 >}}

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

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