#Libnetwork plugin for Calico
This plugin for Docker networking (libnetwork) is intended for use with Project Calico. Calico can be deployed on Docker using guides from the calico-containers repository.
When deployed using calicoctl (see calico-docker) simply pass in the --libnetwork flag.
- To run a specific version of the plugin use the
--libnetwork-imageflag.
Prebuilt docker images are available on DockerHub with tags available for each libnetwork-plugin release.
The container needs to be run using
docker run -d --privileged --net=host -v /run/docker/plugins:/run/docker/plugins calico/node-libnetwork
- Privileged is required since the container creates network devices.
- Host network is used since the network changes need to occur in the host namespace
- The /run/docker/plugins volume is used to allow the plugin to communicate with Docker.
If you don't have etcd available at localhost:4001 then you need to pass in the location as an environment variable e.g. -e ETCD_AUTHORITY=1.2.3.4:2379
To run the plugin from source use gunicorn e.g.
sudo gunicorn -b unix:///run/docker/plugins/calico.sock libnetwork.driver_plugin:app
For the full list of recommended options for use in production, see start.sh
For testing out changes, add the --reload flag or use make run-plugin-local
Install the dependencies from requirements.txt using pip install -r requirements.txt
The plugin provides Calico driver support for both networking, and IPAM. When
creating a network in Docker, use the -d calico to use the Calico network
driver, and the --ipam-driver calico to use the Calico IPAM driver.
The following is a list of known limitations when using the Calico libnetwork driver:
- Creating a mix of containers which use both the Calico IPAM driver and the default IPAM driver is not recommended. In this case, isolation between containers on a "default IPAM" network may not be correctly isolated from containers on a "Calico IPAM" network running on the same host.
- It is not possible to add multiple networks to a single container. However, once a container endpoint is created, it is possible to manually add additional Calico profiles to that endpoint (effectively adding the container into another network).
- When using the Calico IPAM driver, it is not yet possible to select which IP Pool an IP is assigned from. Make sure all of your configured IP Pools have the same ipip and nat-outgoing settings.
Logs are sent to STDOUT. If using Docker these can be viewed with the
docker logs command.
This currently requires a rebuild. Change the following line towards the top of the plugin code
app.logger.setLevel(logging.DEBUG)
This uses the standard Python logging module, so logging level may be set to any of the values defined in the logging module.
These don't include interactions from the Docker daemon or felix. These are interactions from the libnetwork-plugin only.
The number of reads and writes is dependent on whether Calico IPAM driver is also used.
Datastore interactions using default IPAM:
| Operation | Reads | Writes | Deletes | Notes |
|---|---|---|---|---|
| DiscoverNew | 0 | 0 | 0 | None |
| CreateNetwork | 0 | 4 (5 if IPv4 and IPv6) | 0 | 2 for creating profile (tags and rules), 1 per IP Pool, and 1 to store the request JSON |
| CreateEndpoint | 1 | 1 | 0 | Read CreateNetwork JSON and write Endpoint |
| Join | 1 | 0 | 0 | Read CreateNetwork JSON |
| DiscoverDelete | 0 | 0 | 0 | None |
| DeleteNetwork | 1 | 0 | 3 (4 if IPv4 and IPv6) | Delete profile, pool and stored CreateNetwork JSON |
| DeleteEndpoint | 0 | 0 | 1 | Delete endpoint |
| Leave | 0 | 0 | 0 | None |
Datastore interactions using Calico IPAM:
| Operation | Reads | Writes | Deletes | Notes |
|---|---|---|---|---|
| DiscoverNew | 0 | 0 | 0 | None |
| RequestPool | 0 | 0 or 1 | 0 | 1 for verifying Calico pool if subnet explicitly specified |
| CreateNetwork | 0 | 3 | 0 | 2 for creating profile (tags and rules), and 1 to store the request JSON |
| RequestAddress | >=2 | >=1 | >=0 | May have multiple reads/writes/deletes depending on contention (see libcalico IPAM), Reads IP pools if subnet is specified on network. |
| CreateEndpoint | 3 | 1 | 0 | Read CreateNetwork JSON and IPv4/IPv6 next hops, and write Endpoint |
| Join | 2 | 0 | 0 | Read CreateNetwork JSON and Endpoint |
| DiscoverDelete | 0 | 0 | 0 | None |
| ReleasePool | 0 | 0 | 0 | None |
| DeleteNetwork | 1 | 0 | 3 (4 if IPv4 and IPv6) | Delete profile, pool and stored CreateNetwork JSON |
| ReleaseAddress | >=1 | >=1 | >=0 | May have multiple reads/writes/deletes depending on contention (see libcalico IPAM) |
| DeleteEndpoint | 0 | 0 | 1 | Delete endpoint |
| Leave | 0 | 0 | 0 | None |
See the main Calico documentation
Further sources of getting help are listed in the calico-docker repository.