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:

1kind: Service
2metadata:
3  name: google-dns
4spec:
5  port: 53
6  mode: DNS
7  config:
8    upstream:
9      url: dns://8.8.8.8

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

1kind: Service
2metadata:
3  name: google-dns-tls
4spec:
5  port: 53
6  mode: DNS
7  config:
8    upstream:
9      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:

1kind: Service
2metadata:
3  name: google-dns
4spec:
5  config:
6    upstream:
7      url: dns://8.8.8.8
8  mode: DNS
9  authorization:
10    inlinePolicies:
11      - spec:
12          rules:
13            - effect: ALLOW
14              condition:
15                # Only allow .com domains with type A requests
16                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:

1kind: Service
2metadata:
3  name: example-svc
4spec:
5  mode: UDP
6  port: 1234
7  config:
8    upstream:
9      url: dns://8.8.8.8
10  dynamicConfig:
11    configs:
12    - name: cloudflare
13      upstream:
14        url: dns://1.1.1.1
15    - name: secure-cloudflare
16      upstream:
17        url: tls://1.1.1.1:853
18    rules:
19    - condition:
20        match: '"ops" in ctx.user.spec.groups'
21      configName: cloudflare
22    - condition:
23        match: '"dev" in ctx.user.spec.groups'
24      configName: secure-cloudflare

Visibility

The Service emits DNS AccessLogs in real time to an OpenTelemetry receiver (read more here). Here is an example:

1{
2  "apiVersion": "core/v1",
3  "entry": {
4    "common": {
5      "endedAt": "2025-03-21T20:03:12.437986767Z",
6      "isAuthenticated": true,
7      "isAuthorized": true,
8      "namespaceRef": {
9        "apiVersion": "core/v1",
10        "kind": "Namespace",
11        "name": "octelium",
12        "resourceVersion": "0195b81d-43f3-772c-ab9b-cd97c33eb8c8",
13        "uid": "4ccef783-2dc8-4615-9f67-2f61ca1176bb"
14      },
15      "reason": {
16        "details": {
17          "policyMatch": {
18            "inlinePolicy": {
19              "name": "allow-all",
20              "resourceRef": {
21                "apiVersion": "core/v1",
22                "kind": "Group",
23                "name": "g1",
24                "resourceVersion": "0195b821-209b-76f7-bde9-b078e870621c",
25                "uid": "972e1808-7248-468a-ba7c-8da43d33c626"
26              }
27            }
28          }
29        },
30        "type": "POLICY_MATCH"
31      },
32      "regionRef": {
33        "apiVersion": "core/v1",
34        "kind": "Region",
35        "name": "default",
36        "uid": "6e233d12-2fd6-4670-a82d-8c712e1f7374"
37      },
38      "serviceRef": {
39        "apiVersion": "core/v1",
40        "kind": "Service",
41        "name": "dns.octelium",
42        "resourceVersion": "0195b820-15c4-7466-8e46-c289923b6191",
43        "uid": "e07f68c6-5ee1-474b-a2ae-bc3e0ecff38a"
44      },
45      "sessionRef": {
46        "apiVersion": "core/v1",
47        "kind": "Session",
48        "name": "usr1-3pt93j",
49        "resourceVersion": "0195ba4b-c10a-77fe-a0c1-f8d7b4992525",
50        "uid": "e8bea7be-b858-4457-a8ee-a0cb7f6c91da"
51      },
52      "startedAt": "2025-03-21T20:03:12.433421693Z",
53      "userRef": {
54        "apiVersion": "core/v1",
55        "kind": "User",
56        "name": "usr1",
57        "resourceVersion": "0195b821-228d-79b2-92f3-4bb458944f97",
58        "uid": "e0f251b2-6952-4a46-a771-2712a45c47f5"
59      }
60    },
61    "info": {
62      "dns": {
63        "answer": "216.58.210.174",
64        "name": "google.com.",
65        "type": "A",
66        "typeID": "1"
67      }
68    }
69  },
70  "kind": "AccessLog",
71  "metadata": {
72    "actorRef": {
73      "apiVersion": "core/v1",
74      "kind": "Session",
75      "name": "usr1-3pt93j",
76      "resourceVersion": "0195ba4b-c10a-77fe-a0c1-f8d7b4992525",
77      "uid": "e8bea7be-b858-4457-a8ee-a0cb7f6c91da"
78    },
79    "createdAt": "2025-03-21T20:03:12.437982584Z",
80    "id": "gusa-h5wl-yqkly31qfpmx6gywnfw9q2hi-5bdm-fyta",
81    "targetRef": {
82      "apiVersion": "core/v1",
83      "kind": "Service",
84      "name": "dns.octelium",
85      "resourceVersion": "0195b820-15c4-7466-8e46-c289923b6191",
86      "uid": "e07f68c6-5ee1-474b-a2ae-bc3e0ecff38a"
87    }
88  }
89}