DNS - Octelium Docs

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:

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:

kind: Service
metadata:
  name: google-dns-tls
spec:
  port: 53
  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:

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

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). Here is an example:

kind: Service
metadata:
  name: example-svc
spec:
  mode: UDP
  port: 1234
  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). Here is an example:

{
  "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"
      }
    }
  }
}