README
¶
ipvlan-docker-plugin (Deprecated)
UPDATE: Both Ipvlan and Macvlan are now upstream and currently experimental. Give them a try and please don't hesitate to give us feedback in libnetwork issues. Macvlan and Ipvlan Network Drivers. Thanks gohper-netters!
--
ipvlan is a lightweight L2 and L3 network implementation that does not require traditional bridges and is generally pretty kewl.
Pre-Requisites
Kernel Dependencies
The kernel dependency is the ipvlan kernel module support. You can verify if you have it compiled in or not with the following:
$ modprobe ipvlan
$ lsmod | grep ipvlan
ipvlan 24576 0
If you get any errors or it doesn't show up from lsmod then you probably need to simply upgrade the kernel version. Here is an example upgrade to v4.3-rc2 that works on both Ubuntu 15.04 and 14.10 along with the similar Debian distributions.
$ wget http://kernel.ubuntu.com/~kernel-ppa/mainline/v4.3-rc2-unstable/linux-headers-4.3.0-040300rc2_4.3.0-040300rc2.201509201830_all.deb
$ wget http://kernel.ubuntu.com/~kernel-ppa/mainline/v4.3-rc2-unstable/linux-headers-4.3.0-040300rc2-generic_4.3.0-040300rc2.201509201830_amd64.deb
$ wget http://kernel.ubuntu.com/~kernel-ppa/mainline/v4.3-rc2-unstable/linux-image-4.3.0-040300rc2-generic_4.3.0-040300rc2.201509201830_amd64.deb
$ dpkg -i linux-headers-4.3*.deb linux-image-4.3*.deb
$ reboot
As of Docker v1.9 the docker/libnetwork APIs are packaged by default in Docker. Grab the latest or v1.9+ version of Docker from Latest Linux
binary from Docker. Alternatively curl -sSL https://get.docker.com/ | sh or from your
distribution repo or docker repos.
Ipvlan L2 Mode Instructions
1. Start Docker with the following or simply start the service. Version 1.9+ is required.
$ docker -v
Docker version 1.9.1, build a34a1d5
# -D is optional debugging
$ docker daemon -D
2. Start the driver.
In the repo directory, use the binary named ipvlan-docker-plugin-0.3-Linux-x86_64. The binary can of course be renamed.
$ cd binaries
$ ./ipvlan-docker-plugin-0.3-Linux-x86_64 -d
# (optional debug flag) -d
3. Create a network with Docker
Note, the subnet needs to correspond to the master interface.
The mode and host interface options are required. Use the interface on the subnet you want the containers to be on. In the following example, eth1 of the host OS is on 192.168.1.0/24.
-o host_iface=eth1-o mode=l2
$ docker network create -d ipvlan --subnet=192.168.1.0/24 --gateway=192.168.1.1 -o host_iface=eth1 -o mode=l2 net1
4. Start some docker containers
Run some containers, specify the network and verify they can ping one another
$ docker run --net=net1 -it --rm ubuntu
Ipvlan 802.1q Trunk L2 Mode Example Usage
This example can also be run up to a ToR switch with a .1q trunk. To test on a localhost, Vlan 20 should not be able to ping Vlan 30 without being routed by an upstream router/gateway. All containers inside of the Vlan should be able to ping one another. The default namespace (example: eth0 on docker host) is not reachable via icmp per ipvlan arch.
Start the plugin the same as the above example (-d for debug) along with the Docker daemon running $ docker daemon:
$ ./ipvlan-docker-plugin-0.3-Linux-x86_64 -d
Vlan ID 20
# create a new subinterface tied to dot1q vlan 20
ip link add link eth1 name eth1.20 type vlan id 20
# enable the new sub-interface
$ ip link set eth1.20 up
# now add networks and hosts as you would normally by attaching to the master (sub)interface that is tagged
$ docker network create -d ipvlan --subnet=192.168.20.0/24 --gateway=192.168.20.1 -o host_iface=eth1.20 ipvlan20
$ docker run --net=ipvlan20 -it --name ivlan_test1 --rm ubuntu
$ docker run --net=ipvlan20 -it --name ivlan_test2 --rm ubuntu
# ivlan_test1 should be able to ping ivlan_test2 now.
Vlan ID 30
# create a new subinterface tied to dot1q vlan 30
$ ip link add link eth1 name eth1.30 type vlan id 30
# enable the new sub-interface
$ ip link set eth1.30 up
# now add networks and hosts as you would normally by attaching to the master (sub)interface that is tagged
$ docker network create -d ipvlan --subnet=192.168.30.0/24 --gateway=192.168.30.1 -o host_iface=eth1.30 ipvlan130
$ docker run --net=ipvlan30 -it --name ivlan_test3 --rm ubuntu
$ docker run --net=ipvlan30 -it --name ivlan_test4 --rm ubuntu
# ivlan_test3 should be able to ping ivlan_test4 now.
Docker networks are now persistant after a reboot. The plugin does not currently support dealing with unknown networks. That is a priority next. To remove all of the network configs on a docker daemon restart you can simply delete the directory with: rm /var/lib/docker/network/files/*
Example L3 Mode
Ipvlan L3 mode requires a route to be added in the default namespace as well as be advertised or summarized to the rest of the network. This makes it both highly scalable and very attractive to integrate into either the underlay IGP/EGPs or exchange prefixes into overlays with distributed datastores or gateway protos. You can simply replace L2 with L3 to do so but since the routes need to be orchestrated throughout a cluster take a look at the next section for the Go-BGP L3 mode integration.
Go-BGP L3 mode integration
See the README in the Go-BGP integration section (killer next-gen BGP daemon from our friends at github.com/osrg/gobgp).
Notes and General IPVlan Caveats
- There can only be one network type bound to the host interface at any given time. Example: Macvlan Bridge or IPVlan L2. There is no mixing.
- The specified gateway is external to the host or at least not defined by the driver itself.
- Multiple drivers can be active at any time. However, Macvlan and Ipvlan are not compatable on the same master interface (e.g. eth0).
- You can create multiple networks and have active containers in each network as long as they are all of the same mode type.
- Each network is isolated from one another. Any container inside the network/subnet can talk to one another without a reachable gateway.
- Containers on separate networks cannot reach one another without an external process routing between the two networks/subnets.
Dev and issues
Use Godep for dependencies.
Install and use Godep with the following:
$ go get github.com/tools/godep
# From inside the plugin directory where the Godep directory is restore the snapshotted dependencies used by libnetwork:
$ godep restore
There is a godbus/dbus version that conflicts with vishvananda/netlink that will lead to this error at build time. This can appear as libnetwork issues when in fact it is 3rd party drivers. Libnetwork also uses Godep for versioning so using those versions would be just as good or even better if keeping with the latest experimental nightly Docker builds:
Example of the godbus error:
../../../docker/libnetwork/iptables/firewalld.go:75: cannot use c.sysconn.Object(dbusInterface, dbus.ObjectPath(dbusPath)) (type dbus.BusObject) as type *dbus.
Object in assignment: need type assertion
- If you dont want to use godep @Orivej graciously pointed out the godbus dependency in issue #5:
"You need a stable godbus that you can probably get with:"
cd $GOPATH/src/github.com/godbus/dbus
git checkout v2
- Another option would be to use godep and sync your library with libnetworks.
go get github.com/tools/godep
git clone https://github.com/docker/libnetwork.git
cd libnetwork
godep restore
Directories
¶
| Path | Synopsis |
|---|---|
|
Godeps/_workspace/src/github.com/Sirupsen/logrus
Package logrus is a structured logger for Go, completely API compatible with the standard library logger.
|
Package logrus is a structured logger for Go, completely API compatible with the standard library logger. |
|
Godeps/_workspace/src/github.com/codegangsta/cli
Package cli provides a minimal framework for creating and organizing command line Go applications.
|
Package cli provides a minimal framework for creating and organizing command line Go applications. |
|
Godeps/_workspace/src/github.com/docker/go-units
Package units provides helper function to parse and print size and time units in human-readable format.
|
Package units provides helper function to parse and print size and time units in human-readable format. |
|
Godeps/_workspace/src/github.com/docker/libnetwork/types
Package types contains types that are common across libnetwork project
|
Package types contains types that are common across libnetwork project |
|
Godeps/_workspace/src/github.com/godbus/dbus
Package dbus implements bindings to the D-Bus message bus system.
|
Package dbus implements bindings to the D-Bus message bus system. |
|
Godeps/_workspace/src/github.com/godbus/dbus/introspect
Package introspect provides some utilities for dealing with the DBus introspection format.
|
Package introspect provides some utilities for dealing with the DBus introspection format. |
|
Godeps/_workspace/src/github.com/godbus/dbus/prop
Package prop provides the Properties struct which can be used to implement org.freedesktop.DBus.Properties.
|
Package prop provides the Properties struct which can be used to implement org.freedesktop.DBus.Properties. |
|
Godeps/_workspace/src/github.com/golang/protobuf/proto
Package proto converts data structures to and from the wire format of protocol buffers.
|
Package proto converts data structures to and from the wire format of protocol buffers. |
|
Godeps/_workspace/src/github.com/golang/protobuf/proto/proto3_proto
Package proto3_proto is a generated protocol buffer package.
|
Package proto3_proto is a generated protocol buffer package. |
|
Godeps/_workspace/src/github.com/gorilla/context
Package context stores values shared during a request lifetime.
|
Package context stores values shared during a request lifetime. |
|
Godeps/_workspace/src/github.com/gorilla/mux
Package gorilla/mux implements a request router and dispatcher.
|
Package gorilla/mux implements a request router and dispatcher. |
|
Godeps/_workspace/src/github.com/osrg/gobgp/api
Package gobgpapi is a generated protocol buffer package.
|
Package gobgpapi is a generated protocol buffer package. |
|
Godeps/_workspace/src/github.com/vishvananda/netlink
Package netlink provides a simple library for netlink.
|
Package netlink provides a simple library for netlink. |
|
Godeps/_workspace/src/github.com/vishvananda/netlink/nl
Package nl has low level primitives for making Netlink calls.
|
Package nl has low level primitives for making Netlink calls. |
|
Godeps/_workspace/src/golang.org/x/net/context
Package context defines the Context type, which carries deadlines, cancelation signals, and other request-scoped values across API boundaries and between processes.
|
Package context defines the Context type, which carries deadlines, cancelation signals, and other request-scoped values across API boundaries and between processes. |
|
Godeps/_workspace/src/golang.org/x/net/context/ctxhttp
Package ctxhttp provides helper functions for performing context-aware HTTP requests.
|
Package ctxhttp provides helper functions for performing context-aware HTTP requests. |
|
Godeps/_workspace/src/golang.org/x/net/http2
Package http2 implements the HTTP/2 protocol.
|
Package http2 implements the HTTP/2 protocol. |
|
Godeps/_workspace/src/golang.org/x/net/http2/h2i
The h2i command is an interactive HTTP/2 console.
|
The h2i command is an interactive HTTP/2 console. |
|
Godeps/_workspace/src/golang.org/x/net/http2/hpack
Package hpack implements HPACK, a compression format for efficiently representing HTTP header fields in the context of HTTP/2.
|
Package hpack implements HPACK, a compression format for efficiently representing HTTP header fields in the context of HTTP/2. |
|
Godeps/_workspace/src/golang.org/x/net/internal/timeseries
Package timeseries implements a time series structure for stats collection.
|
Package timeseries implements a time series structure for stats collection. |
|
Godeps/_workspace/src/golang.org/x/net/trace
Package trace implements tracing of requests and long-lived objects.
|
Package trace implements tracing of requests and long-lived objects. |
|
Godeps/_workspace/src/google.golang.org/grpc
Package grpc implements an RPC system called gRPC.
|
Package grpc implements an RPC system called gRPC. |
|
Godeps/_workspace/src/google.golang.org/grpc/benchmark
Package benchmark implements the building blocks to setup end-to-end gRPC benchmarks.
|
Package benchmark implements the building blocks to setup end-to-end gRPC benchmarks. |
|
Godeps/_workspace/src/google.golang.org/grpc/benchmark/grpc_testing
Package grpc_testing is a generated protocol buffer package.
|
Package grpc_testing is a generated protocol buffer package. |
|
Godeps/_workspace/src/google.golang.org/grpc/codes
Package codes defines the canonical error codes used by gRPC.
|
Package codes defines the canonical error codes used by gRPC. |
|
Godeps/_workspace/src/google.golang.org/grpc/credentials
Package credentials implements various credentials supported by gRPC library, which encapsulate all the state needed by a client to authenticate with a server and make various assertions, e.g., about the client's identity, role, or whether it is authorized to make a particular call.
|
Package credentials implements various credentials supported by gRPC library, which encapsulate all the state needed by a client to authenticate with a server and make various assertions, e.g., about the client's identity, role, or whether it is authorized to make a particular call. |
|
Godeps/_workspace/src/google.golang.org/grpc/credentials/oauth
Package oauth implements gRPC credentials using OAuth.
|
Package oauth implements gRPC credentials using OAuth. |
|
Godeps/_workspace/src/google.golang.org/grpc/examples/helloworld/helloworld
Package helloworld is a generated protocol buffer package.
|
Package helloworld is a generated protocol buffer package. |
|
Godeps/_workspace/src/google.golang.org/grpc/examples/route_guide/client
Package main implements a simple gRPC client that demonstrates how to use gRPC-Go libraries to perform unary, client streaming, server streaming and full duplex RPCs.
|
Package main implements a simple gRPC client that demonstrates how to use gRPC-Go libraries to perform unary, client streaming, server streaming and full duplex RPCs. |
|
Godeps/_workspace/src/google.golang.org/grpc/examples/route_guide/routeguide
Package routeguide is a generated protocol buffer package.
|
Package routeguide is a generated protocol buffer package. |
|
Godeps/_workspace/src/google.golang.org/grpc/examples/route_guide/server
Package main implements a simple gRPC server that demonstrates how to use gRPC-Go libraries to perform unary, client streaming, server streaming and full duplex RPCs.
|
Package main implements a simple gRPC server that demonstrates how to use gRPC-Go libraries to perform unary, client streaming, server streaming and full duplex RPCs. |
|
Godeps/_workspace/src/google.golang.org/grpc/grpclog
Package grpclog defines logging for grpc.
|
Package grpclog defines logging for grpc. |
|
Godeps/_workspace/src/google.golang.org/grpc/grpclog/glogger
Package glogger defines glog-based logging for grpc.
|
Package glogger defines glog-based logging for grpc. |
|
Godeps/_workspace/src/google.golang.org/grpc/health
Package health provides some utility functions to health-check a server.
|
Package health provides some utility functions to health-check a server. |
|
Godeps/_workspace/src/google.golang.org/grpc/health/grpc_health_v1alpha
Package grpc_health_v1alpha is a generated protocol buffer package.
|
Package grpc_health_v1alpha is a generated protocol buffer package. |
|
Godeps/_workspace/src/google.golang.org/grpc/interop/grpc_testing
Package grpc_testing is a generated protocol buffer package.
|
Package grpc_testing is a generated protocol buffer package. |
|
Godeps/_workspace/src/google.golang.org/grpc/metadata
Package metadata define the structure of the metadata supported by gRPC library.
|
Package metadata define the structure of the metadata supported by gRPC library. |
|
Godeps/_workspace/src/google.golang.org/grpc/naming
Package naming defines the naming API and related data structures for gRPC.
|
Package naming defines the naming API and related data structures for gRPC. |
|
Godeps/_workspace/src/google.golang.org/grpc/peer
Package peer defines various peer information associated with RPCs and corresponding utils.
|
Package peer defines various peer information associated with RPCs and corresponding utils. |
|
Godeps/_workspace/src/google.golang.org/grpc/test/codec_perf
Package codec_perf is a generated protocol buffer package.
|
Package codec_perf is a generated protocol buffer package. |
|
Godeps/_workspace/src/google.golang.org/grpc/test/grpc_testing
Package grpc_testing is a generated protocol buffer package.
|
Package grpc_testing is a generated protocol buffer package. |
|
Godeps/_workspace/src/google.golang.org/grpc/transport
Package transport defines and implements message oriented communication channel to complete various transactions (e.g., an RPC).
|
Package transport defines and implements message oriented communication channel to complete various transactions (e.g., an RPC). |