# Set up DNS Proxy

> [!NOTE]
> **Note:** This guide only supports Cloud Service Mesh with Istio APIs and does not support Google Cloud APIs. For more information see, [Cloud Service Mesh overview](https://docs.cloud.google.com/service-mesh/v1.26/docs/overview.md.txt).

DNS Proxy is a feature for providing the following capabilities:

1. Propagating DNS entries of `Services` across clusters in a [multi-cluster setup](https://docs.cloud.google.com/service-mesh/v1.26/docs/gke-install-multi-cluster).
2. Populating DNS entries for `ServiceEntry`.

Kubernetes provides DNS resolution only for `Services` in the local cluster.
When you need to provide name resolution for `Services` in a remote clusters or
use an internal-only hostname with `ServiceEntry` without having an additional
internal-only DNS server, DNS Proxy provides a way to resolve DNS names for such
cases.

> [!NOTE]
> **Note:** This feature is available from `1.21.5-asm.39` dataplane.

## Configuring DNS Proxy

### Cluster wide configuration

To configure DNS proxy in the cluster, add `ISTIO_META_DNS_CAPTURE` proxy
metadata to the `ConfigMap` for `MeshConfig`. The name of the `ConfigMap` has a format
of `istio-<revision_name>`. For the details of revision, refer to [the overview
of the revision](https://docs.cloud.google.com/service-mesh/v1.26/docs/revisions-overview)

```yaml
apiVersion: v1
data:
  mesh: |-
    ...
    defaultConfig:
      proxyMetadata:
        ISTIO_META_DNS_CAPTURE: "true"        
    ...
kind: ConfigMap
metadata:
  name: istio-<revision_name>
  namespace: istio-system
```

### Per-proxy configuration

To configure DNS proxy for a proxy, add the `ISTIO_META_DNS_CAPTURE` proxy metadata
annotation as follows:

```yaml
kind: Deployment
metadata:
  name: app1
  namespace: ns1
spec:
...
  template:
    metadata:
      annotations:
        proxy.istio.io/config: |
          proxyMetadata:
            ISTIO_META_DNS_CAPTURE: "true"
...
```

### Verifying

#### Name resolution for `Service` across clusters

After the [multi-cluster setup](https://docs.cloud.google.com/service-mesh/v1.26/docs/gke-install-multi-cluster),
deploy a `Service` only in one of the clusters to verify the cross-cluster name
resolution.

When you have the following example `Service` `ns1/svc1`,
you can find `ClusterIP` in `Service`.

```bash
$ kubectl get -n ns1 svc1
kind: Service
metadata:
  name: svc1
  namespace: ns1
spec:
...
  ClusterIP: 210.200.1.1
...
```

Then, when using `curl` from the *other* cluster to the `Service`, it should show
the `ClusterIP` as follows.

```bash
curl -sS -v svc1.ns1.svc.cluster.local
*   Trying 210.200.1.1:80...
```

#### Name resolution for `ServiceEntry`

Add a `ServiceEntry` with a hostname not registered in your DNS.
To verify the name resolution the following example has explicit address `192.168.123.123`.

```bash
$ kubectl apply -f - <<EOF
apiVersion: networking.istio.io/v1beta1
kind: ServiceEntry
metadata:
  name: test-service-entry
spec:
  addresses:
  - "192.168.123.123"
  hosts:
  - not-existing-hostname.internal
  ports:
  - name: http
    number: 80
    protocol: HTTP
EOF
```

Then, try DNS resolution in a Pod where DNS Proxy is enabled. For example, if
you run a `curl` in the Pod, it should display the IP address as follows:

```bash
curl -sS -v not-existing-hostname.internal
*   Trying 192.168.123.123:80...
```