Protocol Documentation

Table of Contents

standalone-dns-proxy/standalone-dns-proxy.proto
Scalar Value Types

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.

DNSServer

DNServer identity, port and protocol the requests be allowed to

Field	Type	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

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

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

UpdateMappingResponse

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

Field	Type	Label	Description
response	ResponseCode

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)