From 8aeb066a585e0c0da49be0bd811362729f58c66b Mon Sep 17 00:00:00 2001 From: Eugene Yakubovich Date: Wed, 4 Nov 2015 11:31:35 -0800 Subject: [PATCH] spec: add "dns" field to the result JSON This adds an ability for networks to communicate about the DNS nameservers they know about to the container runtime. Fixes #67 --- SPEC.md | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/SPEC.md b/SPEC.md index 46d078c4..4880c030 100644 --- a/SPEC.md +++ b/SPEC.md @@ -2,7 +2,8 @@ ## Overview -This document proposes a generic plugin-based networking solution for application containers on Linux, the _Container Networking Interface_, or _CNI_. It is derived from the [rkt Networking Proposal][rkt-networking-proposal], which aimed to satisfy many of the [design considerations][rkt-networking-design] for networking in [rkt][rkt-github]. +This document proposes a generic plugin-based networking solution for application containers on Linux, the _Container Networking Interface_, or _CNI_. +It is derived from the [rkt Networking Proposal][rkt-networking-proposal], which aimed to satisfy many of the [design considerations][rkt-networking-design] for networking in [rkt][rkt-github]. For the purposes of this proposal, we define two terms very specifically: - _container_ can be considered synonymous with a [Linux _network namespace_][namespaces]. What unit this corresponds to depends on a particular container runtime implementation: for example, in implementations of the [App Container Spec][appc-github] like rkt, each _pod_ runs in a unique network namespace. In [Docker][docker], on the other hand, network namespaces generally exist for each separate Docker container. @@ -48,6 +49,7 @@ The operations that the CNI plugin needs to support are: - **Name of the interface inside the container**. This is the name that should be assigned to the interface created inside the container (network namespace); consequently it must comply with the standard Linux restrictions on interface names. - Result: - **IPs assigned to the interface**. This is either an IPv4 address, an IPv6 address, or both. + - **List of DNS nameservers**. This is a priority-ordered list of IPv4 and IPv6 addresses of DNS nameservers. - Delete container from network - Parameters: @@ -83,10 +85,17 @@ Success is indicated by a return code of zero and the following JSON printed to "ip": , "gateway": , (optional) "routes": (optional) - } + }, + "dns": (optional) } ``` +The "dns" field contains a list of a priority-ordered list of DNS nameservers that this network is aware of. +Each entry in the list is a string containing either an IPv4 or an IPv6 address. +Typically this value would just be the value returned by the IPAM plugin. +It is outside the scope of this specification how the container runtime uses the list of DNS nameservers from each of the networks to provide name resolution services to the container. +Examples of how this list could be used include generating an `/etc/resolv.conf` file to be injected into the container filesystem or running a DNS forwarder on the host. + Errors are indicated by a non-zero return code and the following JSON being printed to stdout: ``` { @@ -127,7 +136,7 @@ The network configuration is described in JSON form. The configuration can be st // ipam specific "subnet": "10.1.0.0/16", "gateway": "10.1.0.1" - }, + } } ``` @@ -153,7 +162,7 @@ The network configuration is described in JSON form. The configuration can be st "ipam": { "type": "dhcp", "routes": [ { "dst": "10.0.0.0/8", "gw": "10.0.0.1" } ] - }, + } } ``` @@ -181,7 +190,8 @@ Success is indicated by a zero return code and the following JSON being printed "ip": , "gateway": , (optional) "routes": (optional) - } + }, + "dns": (optional) } ``` @@ -193,6 +203,10 @@ Each route entry is a dictionary with the following fields: - `dst` (string): Destination subnet specified in CIDR notation. - `gw` (string): IP of the gateway. If omitted, a default gateway is assumed (as determined by the CNI plugin). +The "dns" field contains a list of a priority-ordered list of DNS nameservers that this network is aware of. +Each entry in the list is a string containing either an IPv4 or an IPv6 address. +See [CNI Plugin Result](#result) section for details. + Errors and logs are communicated in the same way as the CNI plugin. See [CNI Plugin Result](#result) section for details. IPAM plugin examples: @@ -200,10 +214,5 @@ IPAM plugin examples: - **dhcp**: Use DHCP protocol to acquire and maintain a lease. The DHCP requests will be sent via the created container interface; therefore, the associated network must support broadcast. #### Notes - - Routes are expected to be added with a 0 metric. - A default route may be specified via "0.0.0.0/0". Since another network might have already configured the default route, the CNI plugin should be prepared to skip over its default route definition. - -## Open Questions -- Should CNI define anything regarding DNS? For example, generating /etc/resolv.conf -- Should CNI provide /etc/hosts?