Protocol Documentation

Table of Contents

• standalone-dns-proxy/standalone-dns-proxy.proto

  • DNSPolicy

  • DNSResponseData

  • DNSServer

  • EndpointInfo

  • FQDNMapping

  • IdentityToEndpointMapping

  • IdentityToPrefixMapping

  • MetricsData

  • PolicyState

  • PolicyStateResponse

  • ProcessingStats

  • UpdateMappingResponse

  • ProxyErrorType

  • ResponseCode

  • FQDNData

• Scalar Value Types

Top

standalone-dns-proxy/standalone-dns-proxy.proto

DNSPolicy

L7 DNS policy specifying which requests are permitted to which DNS server

Field	Type	Label	Description
source_endpoint_id	uint32		Endpoint ID of the workload this L7 DNS policy should apply to
dns_pattern	string	repeated	Allowed DNS pattern this identity is allowed to resolve.
dns_servers	DNSServer	repeated	List of DNS servers to be allowed to connect.

DNSResponseData

DNSResponseData holds the DNS message details extracted from the response that are needed for access logging on the agent side.

Field	Type	Label	Description
is_response	bool		Whether this is a DNS response (true) or request (false)
cnames	string	repeated	CNAME records from the DNS response
qtypes	uint32	repeated	DNS question types
answer_types	uint32	repeated	DNS answer record types

DNSServer

DNServer identity, port and protocol the requests be allowed to

Field	Type	Label	Description
dns_server_identity	uint32		Identity of destination DNS server
dns_server_port	uint32
dns_server_proto	uint32

EndpointInfo

cilium endpoint ipaddress and ID

Field	Type	Label	Description
id	uint64
ip	bytes	repeated

FQDNMapping

FQDN-IP mapping goalstate sent from SDP to agent

Field	Type	Label	Description
fqdn	string		dns name
record_ip	bytes	repeated	List of IPs corresponding to dns name
ttl	uint32		TTL of DNS record
source_identity	uint32		Identity of the client making the DNS request
source_ip	bytes		IP address of the client making the DNS request
response_code	uint32		DNS Response code as specified in RFC2316
metrics_data	MetricsData		Metrics and access logging data collected by the standalone DNS proxy.

IdentityToEndpointMapping

Cilium Identity ID to IP address mapping

Field	Type	Label	Description
identity	uint32
endpoint_info	EndpointInfo	repeated

IdentityToPrefixMapping

Cilium Identity ID to IP prefix mapping

Field	Type	Label	Description
identity	uint32
prefix	bytes	repeated

MetricsData

MetricsData carries the flow context and timing statistics that the agent needs to emit proxy metrics and access log records for DNS events originating from the standalone DNS proxy.

Field	Type	Label	Description
processing_stats	ProcessingStats		Proxy request processing timing statistics
dns_response_data	DNSResponseData		DNS response metadata extracted from the DNS message
source_port	uint32		Source port of the endpoint making the DNS request
server_addr	string		IP:port of the destination DNS server as “ip:port” string (e.g., “8.8.8.8:53”)
server_identity	uint32		Security identity of the destination DNS server
protocol	string		L4 protocol used for the DNS request (e.g., “udp”, “tcp”)
allowed	bool		Whether the DNS request was allowed by policy
error_message	string		Error message if the DNS request encountered an error (empty if no error)
error_type	ProxyErrorType		Structured error classification for metrics without relying on string matching.

PolicyState

L7 DNS policy snapshot of all local endpoints and identity to ip mapping of source and destinatione egress endpoints enforcing fqdn rules.

Field	Type	Label	Description
egress_l7_dns_policy	DNSPolicy	repeated
request_id	string		Random UUID based identifier which will be referenced in ACKs
identity_to_endpoint_mapping	IdentityToEndpointMapping	repeated	Identity to Endpoint mapping for the DNS server and the source identity
identity_to_prefix_mapping	IdentityToPrefixMapping	repeated	Identity to Prefix mapping for the identity

PolicyStateResponse

Ack sent from SDP to Agent on processing DNS policy rules

Field	Type	Label	Description
response	ResponseCode
request_id	string		Request ID for which response is sent to

ProcessingStats

ProcessingStats carries proxy request timing statistics collected by the standalone DNS proxy. All durations are in nanoseconds. Only fields actually measured by the standalone proxy are included here; agent-side timings (policy generation, dataplane, cache updates, etc.) are measured directly by the agent after receiving the gRPC message.

Field	Type	Label	Description
total_time_ns	int64
processing_time_ns	int64
upstream_time_ns	int64
semaphore_acquire_time_ns	int64
policy_check_time_ns	int64

UpdateMappingResponse

Ack returned by cilium agent to SDP on receiving FQDN-IP mapping update

Field	Type	Label	Description
response	ResponseCode

ProxyErrorType

ProxyErrorType classifies the error that occurred during DNS proxy processing. The agent uses this to reconstruct the correct error type for metrics reporting (metric label, semaphore-rejected counter, etc.) without relying on Go error-type information that is lost during gRPC serialization.

Name	Number	Description
PROXY_ERROR_TYPE_NONE	0	No error occurred.
PROXY_ERROR_TYPE_PROXY	1	A generic proxy-side error (e.g. failed to parse, forward, etc.).
PROXY_ERROR_TYPE_TIMEOUT	2	An upstream network timeout (e.g. DNS server did not respond).
PROXY_ERROR_TYPE_SEMAPHORE_FAILED	3	The DNS proxy concurrency semaphore could not be acquired immediately.
PROXY_ERROR_TYPE_SEMAPHORE_TIMED_OUT	4	The DNS proxy concurrency semaphore timed out during the grace period.

ResponseCode

Response code returned by RPC methods.

Name	Number	Description
RESPONSE_CODE_UNSPECIFIED	0
RESPONSE_CODE_NO_ERROR	1
RESPONSE_CODE_FORMAT_ERROR	2
RESPONSE_CODE_SERVER_FAILURE	3
RESPONSE_CODE_NOT_IMPLEMENTED	4
RESPONSE_CODE_ERROR_INVALID_ARGUMENT	6	Invalid argument passed to the RPC method
RESPONSE_CODE_ERROR_ENDPOINT_NOT_FOUND	5	Endpoint not found for the given IP
RESPONSE_CODE_REFUSED	7

FQDNData

Cilium agent runs the FQDNData service and Standalone DNS proxy connects to it to get the DNS Policy rules. Standalone DNS proxy sends FQDN-IP mapping updates to Cilium Agent. CFP: https://github.com/cilium/design-cfps/pull/54

Method Name	Request Type	Response Type	Description
StreamPolicyState	PolicyStateResponse stream	PolicyState stream	StreamPolicyState is used by the Standalone DNS proxy to get the current policy state. Policy state includes the DNS policies and the identity to IP mapping. Cilium agent will stream DNS policies state to Standalone DNS proxy. In case of any client side error, cilium agent will cancel the stream and SDP will have to re-subscribe. In case of any server side error, cilium agent will send an error response and SDP will have to re-subscribe.
UpdateMappingRequest	FQDNMapping	UpdateMappingResponse	UpdateMappingRequest is used by the Standalone DNS proxy to update ciliium agent with FQDN-IP mappings which in turn update L3/L4 policy maps. In case of any error, SDP will either retry the connection if the error is server side or will error out. Note: In case of concurrent updates, since this is called in a callback(notifyDNSMsg) from the DNS server it follows the same behavior as the inbuilt dns proxy in cilium.

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)