# DNS

> Octelium documentation. Canonical page: <https://octelium.com/docs/octelium/latest/management/core/service/dns>.

The `DNS` mode is an application-layer aware mode for DNS-based *Services*. In fact, the *Cluster* private DNS itself is exposed as an ordinary *Service* in `DNS` mode that can be unconditionally accessed by all *Users*. Here is simple example:

```yaml
kind: Service
metadata:
  name: google-dns
spec:
  port: 53
  mode: DNS
  config:
    upstream:
      url: dns://8.8.8.8
```

The `DNS` mode also supports DNS-over-TLS (DoT) upstreams. Here is an example:

```yaml
kind: Service
metadata:
  name: google-dns-tls
spec:
  port: 53
# !mark
  mode: DNS
  config:
    upstream:
      url: tls://8.8.8.8:853
```

## Access Control

The `DNS` mode allows you to allow DNS requests based on the request's question name or type ID. Here is an example:

```yaml
kind: Service
metadata:
  name: google-dns
spec:
  config:
    upstream:
      url: dns://8.8.8.8
  mode: DNS
  authorization:
    inlinePolicies:
      - spec:
          rules:
            - effect: ALLOW
              condition:
                # Only allow .com domains with type A requests
                match: ctx.request.dns.name.endsWith(".com.") && ctx.request.dns.typeID == 1
```

> **Note:**
>
> You can get an extensive list of DNS type IDs [here](https://en.wikipedia.org/wiki/List_of_DNS_record_types)

## Dynamic Configuration

You can use dynamic configuration in order to, for example, route to different upstreams depending on the request's context (read more about dynamic configuration [here](https://octelium.com/docs/octelium/latest/management/core/service/dynamic-config.md)). Here is an example:

```yaml
kind: Service
metadata:
  name: example-svc
spec:
  mode: DNS
  config:
    upstream:
      url: dns://8.8.8.8
  dynamicConfig:
    configs:
    - name: cloudflare
      upstream:
        url: dns://1.1.1.1
    - name: secure-cloudflare
      upstream:
        url: tls://1.1.1.1:853
    rules:
    - condition:
        match: '"ops" in ctx.user.spec.groups'
      configName: cloudflare
    - condition:
        match: '"dev" in ctx.user.spec.groups'
      configName: secure-cloudflare
```

## Visibility

The *Service* emits `DNS` *AccessLogs* in real time to an OpenTelemetry receiver (read more [here](https://octelium.com/docs/octelium/latest/management/core/visibility.md)). Here is an example:

```json
{
  "apiVersion": "core/v1",
  "kind": "AccessLog",
  "metadata": {
    "id": "bv0w-oliu-73rsmyhjq3ru12r4qz80ahho-tk5l-wxzm",
    "createdAt": "2025-09-10T22:30:15.184524267Z",
    "actorRef": {
      "apiVersion": "core/v1",
      "kind": "Session",
      "uid": "b1bc6aaa-df51-456d-aa37-b77377ea26f0",
      "name": "root-1x09ce",
      "resourceVersion": "019935bf-8271-704d-b079-9af18e29037a"
    },
    "targetRef": {
      "apiVersion": "core/v1",
      "kind": "Service",
      "uid": "8ca3d118-a507-405f-8592-12a5fe1e16cb",
      "name": "dns.octelium",
      "resourceVersion": "019934ca-9270-7480-8d96-230a538cb6a6"
    }
  },
  "entry": {
    "common": {
      "startedAt": "2025-09-10T22:30:15.182784369Z",
      "endedAt": "2025-09-10T22:30:15.184526057Z",
      "status": "ALLOWED",
      "mode": "DNS",
      "reason": {
        "type": "POLICY_MATCH",
        "details": {
          "policyMatch": {
            "inlinePolicy": {
              "resourceRef": {
                "apiVersion": "core/v1",
                "kind": "Service",
                "uid": "8ca3d118-a507-405f-8592-12a5fe1e16cb",
                "name": "dns.octelium",
                "resourceVersion": "019934ca-9270-7480-8d96-230a538cb6a6"
              }
            }
          }
        }
      },
      "sessionRef": {
        "apiVersion": "core/v1",
        "kind": "Session",
        "uid": "b1bc6aaa-df51-456d-aa37-b77377ea26f0",
        "name": "root-1x09ce",
        "resourceVersion": "019935bf-8271-704d-b079-9af18e29037a"
      },
      "userRef": {
        "apiVersion": "core/v1",
        "kind": "User",
        "uid": "d72a39da-6f1c-43f7-ad75-dbaf76111b10",
        "name": "root",
        "resourceVersion": "019934c7-3d99-7864-8ccf-abe9eadfe023"
      },
      "serviceRef": {
        "apiVersion": "core/v1",
        "kind": "Service",
        "uid": "8ca3d118-a507-405f-8592-12a5fe1e16cb",
        "name": "dns.octelium",
        "resourceVersion": "019934ca-9270-7480-8d96-230a538cb6a6"
      },
      "namespaceRef": {
        "apiVersion": "core/v1",
        "kind": "Namespace",
        "uid": "659a016d-aa9b-45c5-aae7-4212e7d4da3d",
        "name": "octelium",
        "resourceVersion": "019934c7-6d7e-76d0-89c7-2966e41f2e5b"
      },
      "regionRef": {
        "apiVersion": "core/v1",
        "kind": "Region",
        "uid": "85477de2-67d3-48ed-bda7-6c914489badf",
        "name": "default"
      }
    },
    "info": {
      "dns": {
        "type": "A",
        "typeID": 1,
        "name": "mail.google.com.",
        "answer": "142.250.185.133"
      }
    }
  }
}
```