As per the official GitHub repository (https://github.com/appc/cni), the parameters that the CNI plugin need in order to add a container to the network are:
- Version: The version of CNI spec that the caller is using (container call invoking the plugin).
- Container ID: This is optional, but recommended, and defines that there should be a unique ID across an administrative domain while the container is live. For example, the IPAM system may require that each container is allocated a unique ID so that it can be correlated properly to a container running in the background.
- Network namespace path: This represents the path to the network namespace to be added, for example,
/proc/[pid]/ns/netor abind-mount/linkto it. - Network configuration: It is the JSON document that describes a network to which a container can be joined and is explained in the following section.
- Extra arguments: It allows granular configuration of CNI plugins on a per-container basis.
- Name of the interface inside the container: It is the name that gets assigned to the container and complies with Linux restriction, which exists for interface names.
The results achieved are as follows:
The network configuration is in the JSON format that can be stored on disk or generated from other sources by container runtime. The following fields in the JSON have importance, as explained in the following:
- cniVersion (string): It is Semantic Version 2.0 of the CNI specification to which this configuration meets.
- name (string): It is the network name. It is unique across all containers on the host (or other administrative domain).
- type (string): Refers to the filename of the CNI plugin executable.
- ipMasq (boolean): Optional, sets up an IP masquerade on the host as it is necessary for the host to act as a gateway to subnets that are not able to route to the IP assigned to the container.
- ipam: Dictionary with IPAM-specific values.
- type (string): Refers to the filename of the IPAM plugin executable.
- routes (list): List of subnets (in CIDR notation) that the CNI plugin should make sure are reachable by routing through the network. Each entry is a dictionary containing:
An example configuration for plugin-specific OVS is as follows:
{
"cniVersion": "0.1.0",
"name": "pci",
"type": "ovs",
// type (plugin) specific
"bridge": "ovs0",
"vxlanID": 42,
"ipam": {
"type": "dhcp",
"routes": [ { "dst": "10.3.0.0/16" }, { "dst": "10.4.0.0/16" } ]
}
}The CNI plugin assigns an IP address to the interface and installs necessary routes for the interface, thus it provides great flexibility for the CNI plugin and many CNI plugins internally have the same code to support several IP management schemes.
To lessen the burden on the CNI plugin, a second type of plugin, IP address management plugin (IPAM), is defined, which determines the interface IP/subnet, gateway, and routes and returns this information to the main plugin to apply. The IPAM plugin obtains information via a protocol, ipam section defined in the network configuration file, or data stored on the local filesystem.
The IPAM plugin is invoked by running an executable, which is searched in a predefined path and is indicated by a CNI plugin via CNI_PATH. The IPAM plugin receives all the system environment variables from this executable, which are passed to the CNI plugin.
IPAM receives a network configuration file via stdin. Success is indicated by a zero return code and the following JSON, which gets printed to stdout (in the case of the ADD command):
{
"cniVersion": "0.1.0",
"ip4": {
"ip": <ipv4-and-subnet-in-CIDR>,
"gateway": <ipv4-of-the-gateway>, (optional)
"routes": <list-of-ipv4-routes> (optional)
},
"ip6": {
"ip": <ipv6-and-subnet-in-CIDR>,
"gateway": <ipv6-of-the-gateway>, (optional)
"routes": <list-of-ipv6-routes> (optional)
},
"dns": <list-of-DNS-nameservers> (optional)
}The following is an example of running Docker networking with CNI:
- First, install Go Lang 1.4+ and jq (command line JSON processor) to build the CNI plugins:
$ wget https://storage.googleapis.com/golang/go1.5.2.linux-amd64.tar.gz $ tar -C /usr/local -xzf go1.5.2.linux-amd64.tar.gz $ export PATH=$PATH:/usr/local/go/bin $ go version go version go1.5.2 linux/amd64 $ sudo apt-get install jq
- Clone the official CNI GitHub repository:
$ git clone https://github.com/appc/cni.git Cloning into 'cni'... remote: Counting objects: 881, done. remote: Total 881 (delta 0), reused 0 (delta 0), pack-reused 881 Receiving objects: 100% (881/881), 543.54 KiB | 313.00 KiB/s, done. Resolving deltas: 100% (373/373), done. Checking connectivity... done.
- We will now create a
netconffile in order to describe the network:mkdir -p /etc/cni/net.d root@rajdeepd-virtual-machine:~# cat >/etc/cni/net.d/10-mynet.conf <<EOF >{ > "name": "mynet", > "type": "bridge", > "bridge": "cni0", > "isGateway": true, > "ipMasq": true, > "ipam": { > "type": "host-local", > "subnet": "10.22.0.0/16", > "routes": [ > { "dst": "0.0.0.0/0" } > ] > } >} > EOF
- Build the CNI plugins:
~/cni$ ./build Building API Building reference CLI Building plugins flannel bridge ipvlan macvlan ptp dhcp host-local
- Now we will execute the
priv-net-run.shscript in order to create the private network with the CNI plugin:~/cni/scripts$ sudo CNI_PATH=$CNI_PATH ./priv-net-run.sh ifconfig eth0 Link encap:Ethernet HWaddr 8a:72:75:7d:6d:6c inet addr:10.22.0.2 Bcast:0.0.0.0 Mask:255.255.0.0 inet6 addr: fe80::8872:75ff:fe7d:6d6c/64 Scope:Link UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 RX packets:1 errors:0 dropped:0 overruns:0 frame:0 TX packets:1 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:0 RX bytes:90 (90.0 B) TX bytes:90 (90.0 B) lo Link encap:Local Loopback inet addr:127.0.0.1 Mask:255.0.0.0 inet6 addr: ::1/128 Scope:Host UP LOOPBACK RUNNING MTU:65536 Metric:1 RX packets:0 errors:0 dropped:0 overruns:0 frame:0 TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:0 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B)
- Run a Docker container with the network namespace, which was set up previously using the CNI plugin:
~/cni/scripts$ sudo CNI_PATH=$CNI_PATH ./docker-run.sh --rm busybox:latest /bin/ifconfig eth0 Link encap:Ethernet HWaddr 92:B2:D3:E5:BA:9B inet addr:10.22.0.2 Bcast:0.0.0.0 Mask:255.255.0.0 inet6 addr: fe80::90b2:d3ff:fee5:ba9b/64 Scope:Link UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 RX packets:2 errors:0 dropped:0 overruns:0 frame:0 TX packets:2 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:0 RX bytes:180 (180.0 B) TX bytes:168 (168.0 B) lo Link encap:Local Loopback inet addr:127.0.0.1 Mask:255.0.0.0 inet6 addr: ::1/128 Scope:Host UP LOOPBACK RUNNING MTU:65536 Metric:1 RX packets:0 errors:0 dropped:0 overruns:0 frame:0 TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:0 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B)
