standalone-dns-proxy

Active contributors: aanm, jrajahalme, gandro

Purpose

The standalone DNS proxy (standalone-dns-proxy/) runs Cilium's FQDN policy DNS interception as an out-of-process binary, so that DNS resolution does not block on agent restarts and so that scaling tactics differ from the agent's. It is an optional alternative to the in-agent DNS proxy embedded in pkg/fqdn/.

When enabled, the agent forwards DNS proxy responsibilities to this binary over a local socket, and the binary publishes IP-to-FQDN mappings back to the agent so that toFQDNs policy can be enforced in BPF.

Directory layout

standalone-dns-proxy/
├── main.go
├── cmd/        # cobra root + cell graph
└── pkg/        # proxy implementation, gRPC bridge to agent

How it works

sequenceDiagram
    participant Pod
    participant SDP as standalone-dns-proxy
    participant Upstream as Upstream DNS
    participant Agent as cilium-agent
    Pod->>SDP: DNS query
    SDP->>Upstream: forward
    Upstream-->>SDP: response
    SDP->>Agent: gRPC: IP->FQDN mapping
    Agent->>Agent: program ipcache + policy maps
    SDP-->>Pod: DNS response (after policy approval)

The proxy enforces the toFQDNs allow list before returning a response: if the resolved IP is not allowed for the source pod's identity, the response is held until the agent has programmed BPF maps for the new IP.

Integration points

• Agent: speaks the FQDN gRPC service defined in pkg/fqdn/.
• K8s: does not talk to the API server directly; the agent remains the policy source.
• Helm: controlled via install/kubernetes/cilium/values.yaml (dnsProxy.standalone).

Key source files

File	Purpose
standalone-dns-proxy/main.go	Entry point.
standalone-dns-proxy/cmd/	Cell graph.
standalone-dns-proxy/pkg/	Proxy server + agent bridge.
pkg/fqdn/	Agent-side DNS proxy (in-process variant).

See features/network-policy.md for the FQDN policy story end-to-end.