Skip to content
Container Network Interface - networking for Linux containers
Go Shell
Branch: master
Clone or download
bboreham Merge pull request #724 from squeed/readme-update
Update README to sunset slack and call out kubecon presentations
Latest commit 46b9d6f Nov 13, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Documentation Update cnitool docs Sep 17, 2019
cnitool Update cnitool docs Sep 17, 2019
libcni When the CNI version isn't supplied in config, use default. Oct 16, 2019
pkg Merge pull request #712 from mars1024/modify/ifname_validation Oct 9, 2019
plugins/test add err handling in plugins/test/noop/ Sep 12, 2019
scripts Release: bump go to v1.12 May 29, 2019
.appveyor.yml ci: add appveyor file for Windows CI coverage Oct 23, 2017
.gitignore add the timeout context Sep 25, 2018
.travis.yml Bump golang Sep 19, 2019
CODE-OF-CONDUCT.md Add Code of Conduct Jun 2, 2017
CONTRIBUTING.md Merge pull request #624 from annp1987/remove_duplicate_worlds Feb 20, 2019
CONVENTIONS.md docs: add ips and mac to well-known capabilities and fix some typo Jul 16, 2019
DCO
GOVERNANCE.md governance: add notes about public voting Sep 13, 2017
LICENSE Initial commit Apr 5, 2015
MAINTAINERS Update Casey's email address. Jan 31, 2019
README.md Update README to sunset slack and call out kubecon presentations Nov 13, 2019
RELEASING.md Update and document release process Jun 28, 2017
ROADMAP.md Update roadmap with change from GET to CHECK Dec 6, 2018
SPEC.md Merge pull request #712 from mars1024/modify/ifname_validation Oct 9, 2019
Vagrantfile bump linux to Bionic 18.04 in Travis and Vagrant Jul 10, 2019
logo.png Add CNI Logo to README May 15, 2017
test.sh tests: sudo not actually required Feb 16, 2018

README.md

Linux Build Status Windows Build Status Coverage Status

CNI Logo


CNI at KubeCon / CloudNativeCon

The CNI maintainers are hosting two sessions at KubeCon / CloudNativeCon 2019:


CNI Slack

The CNI slack has been sunsetted - please join us in #cni and #cni-dev on the CNCF slack


CNI - the Container Network Interface

What is CNI?

CNI (Container Network Interface), a Cloud Native Computing Foundation project, consists of a specification and libraries for writing plugins to configure network interfaces in Linux containers, along with a number of supported plugins. CNI concerns itself only with network connectivity of containers and removing allocated resources when the container is deleted. Because of this focus, CNI has a wide range of support and the specification is simple to implement.

As well as the specification, this repository contains the Go source code of a library for integrating CNI into applications and an example command-line tool for executing CNI plugins. A separate repository contains reference plugins and a template for making new plugins.

The template code makes it straight-forward to create a CNI plugin for an existing container networking project. CNI also makes a good framework for creating a new container networking project from scratch.

Why develop CNI?

Application containers on Linux are a rapidly evolving area, and within this area networking is not well addressed as it is highly environment-specific. We believe that many container runtimes and orchestrators will seek to solve the same problem of making the network layer pluggable.

To avoid duplication, we think it is prudent to define a common interface between the network plugins and container execution: hence we put forward this specification, along with libraries for Go and a set of plugins.

Who is using CNI?

Container runtimes

3rd party plugins

The CNI team also maintains some core plugins in a separate repository.

Contributing to CNI

We welcome contributions, including bug reports, and code and documentation improvements. If you intend to contribute to code or documentation, please read CONTRIBUTING.md. Also see the contact section in this README.

How do I use CNI?

Requirements

The CNI spec is language agnostic. To use the Go language libraries in this repository, you'll need a recent version of Go. You can find the Go versions covered by our automated tests in .travis.yaml.

Reference Plugins

The CNI project maintains a set of reference plugins that implement the CNI specification. NOTE: the reference plugins used to live in this repository but have been split out into a separate repository as of May 2017.

Running the plugins

After building and installing the reference plugins, you can use the priv-net-run.sh and docker-run.sh scripts in the scripts/ directory to exercise the plugins.

note - priv-net-run.sh depends on jq

Start out by creating a netconf file to describe a network:

$ mkdir -p /etc/cni/net.d
$ cat >/etc/cni/net.d/10-mynet.conf <<EOF
{
	"cniVersion": "0.2.0",
	"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
$ cat >/etc/cni/net.d/99-loopback.conf <<EOF
{
	"cniVersion": "0.2.0",
	"name": "lo",
	"type": "loopback"
}
EOF

The directory /etc/cni/net.d is the default location in which the scripts will look for net configurations.

Next, build the plugins:

$ cd $GOPATH/src/github.com/containernetworking/plugins
$ ./build_linux.sh # or build_windows.sh

Finally, execute a command (ifconfig in this example) in a private network namespace that has joined the mynet network:

$ CNI_PATH=$GOPATH/src/github.com/containernetworking/plugins/bin
$ cd $GOPATH/src/github.com/containernetworking/cni/scripts
$ sudo CNI_PATH=$CNI_PATH ./priv-net-run.sh ifconfig
eth0      Link encap:Ethernet  HWaddr f2:c2:6f:54:b8:2b  
          inet addr:10.22.0.2  Bcast:0.0.0.0  Mask:255.255.0.0
          inet6 addr: fe80::f0c2:6fff:fe54:b82b/64 Scope:Link
          UP BROADCAST MULTICAST  MTU:1500  Metric:1
          RX packets:1 errors:0 dropped:0 overruns:0 frame:0
          TX packets:0 errors:0 dropped:1 overruns:0 carrier:0
          collisions:0 txqueuelen:0
          RX bytes:90 (90.0 B)  TX bytes:0 (0.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)

The environment variable CNI_PATH tells the scripts and library where to look for plugin executables.

Running a Docker container with network namespace set up by CNI plugins

Use the instructions in the previous section to define a netconf and build the plugins. Next, docker-run.sh script wraps docker run, to execute the plugins prior to entering the container:

$ CNI_PATH=$GOPATH/src/github.com/containernetworking/plugins/bin
$ cd $GOPATH/src/github.com/containernetworking/cni/scripts
$ sudo CNI_PATH=$CNI_PATH ./docker-run.sh --rm busybox:latest ifconfig
eth0      Link encap:Ethernet  HWaddr fa:60:70:aa:07:d1  
          inet addr:10.22.0.2  Bcast:0.0.0.0  Mask:255.255.0.0
          inet6 addr: fe80::f860:70ff:feaa:7d1/64 Scope:Link
          UP BROADCAST MULTICAST  MTU:1500  Metric:1
          RX packets:1 errors:0 dropped:0 overruns:0 frame:0
          TX packets:0 errors:0 dropped:1 overruns:0 carrier:0
          collisions:0 txqueuelen:0
          RX bytes:90 (90.0 B)  TX bytes:0 (0.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)

What might CNI do in the future?

CNI currently covers a wide range of needs for network configuration due to its simple model and API. However, in the future CNI might want to branch out into other directions:

  • Dynamic updates to existing network configuration
  • Dynamic policies for network bandwidth and firewall rules

If these topics are of interest, please contact the team via the mailing list or IRC and find some like-minded people in the community to put a proposal together.

Where are the binaries?

The plugins moved to a separate repo: https://github.com/containernetworking/plugins, and the releases there include binaries and checksums.

Prior to release 0.7.0 the cni release also included a cnitool binary; as this is a developer tool we suggest you build it yourself.

Contact

For any questions about CNI, please reach out on the mailing list:

  • Email: cni-dev
  • IRC: #containernetworking channel on freenode.org
  • #cni on the CNCF slack
You can’t perform that action at this time.