api/v1/standalone-dns-proxy/README.md
<a name="top"></a>
<a name="standalone-dns-proxy_standalone-dns-proxy-proto"></a>
<p align="right"><a href="#top">Top</a></p><a name="standalonednsproxy-DNSPolicy"></a>
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. |
<a name="standalonednsproxy-DNSResponseData"></a>
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 |
<a name="standalonednsproxy-DNSServer"></a>
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 |
<a name="standalonednsproxy-EndpointInfo"></a>
cilium endpoint ipaddress and ID
| Field | Type | Label | Description |
|---|---|---|---|
| id | uint64 | ||
| ip | bytes | repeated |
<a name="standalonednsproxy-FQDNMapping"></a>
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. |
<a name="standalonednsproxy-IdentityToEndpointMapping"></a>
Cilium Identity ID to IP address mapping
| Field | Type | Label | Description |
|---|---|---|---|
| identity | uint32 | ||
| endpoint_info | EndpointInfo | repeated |
<a name="standalonednsproxy-IdentityToPrefixMapping"></a>
Cilium Identity ID to IP prefix mapping
| Field | Type | Label | Description |
|---|---|---|---|
| identity | uint32 | ||
| prefix | bytes | repeated |
<a name="standalonednsproxy-MetricsData"></a>
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. |
<a name="standalonednsproxy-PolicyState"></a>
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 |
<a name="standalonednsproxy-PolicyStateResponse"></a>
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 |
<a name="standalonednsproxy-ProcessingStats"></a>
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 |
<a name="standalonednsproxy-UpdateMappingResponse"></a>
Ack returned by cilium agent to SDP on receiving FQDN-IP mapping update
| Field | Type | Label | Description |
|---|---|---|---|
| response | ResponseCode |
<a name="standalonednsproxy-ProxyErrorType"></a>
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. |
<a name="standalonednsproxy-ResponseCode"></a>
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 |
<a name="standalonednsproxy-FQDNData"></a>
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. |
| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
|---|---|---|---|---|---|---|---|---|
| <a name="double" /> double | double | double | float | float64 | double | float | Float | |
| <a name="float" /> float | float | float | float | float32 | float | float | Float | |
| <a name="int32" /> 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) |
| <a name="int64" /> 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 |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) |
| <a name="sint32" /> 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) |
| <a name="sint64" /> 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 |
| <a name="fixed32" /> 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) |
| <a name="fixed64" /> 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 |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| <a name="bool" /> bool | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |