libnetwork

package module
v0.0.0-...-ede31dc Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 6, 2015 License: Apache-2.0 Imports: 20 Imported by: 0

README

libnetwork - networking for containers

Circle CI Coverage Status GoDoc

Libnetwork provides a native Go implementation for connecting containers

The goal of libnetwork is to deliver a robust Container Network Model that provides a consistent programming interface and the required network abstractions for applications.

NOTE: libnetwork project is under heavy development and is not ready for general use.

Current Status

Please watch this space for updates on the progress.

Currently libnetwork is nothing more than an attempt to modularize the Docker platform's networking subsystem by moving it into libnetwork as a library.

Please refer to the roadmap for more information.

Using libnetwork

There are many networking solutions available to suit a broad range of use-cases. libnetwork uses a driver / plugin model to support all of these solutions while abstracting the complexity of the driver implementations by exposing a simple and consistent Network Model to users.

        // Create a new controller instance
        controller := libnetwork.New()

        // Select and configure the network driver
        networkType := "bridge"

        driverOptions := options.Generic{}
        genericOption := make(map[string]interface{})
        genericOption[options.GenericData] = driverOptions
        err := controller.ConfigureNetworkDriver(networkType, genericOption)
        if err != nil {
                return
        }

        // Create a network for containers to join.
        // NewNetwork accepts Variadic optional arguments that libnetwork and Drivers can make of
        network, err := controller.NewNetwork(networkType, "network1")
        if err != nil {
                return
        }

        // For each new container: allocate IP and interfaces. The returned network
        // settings will be used for container infos (inspect and such), as well as
        // iptables rules for port publishing. This info is contained or accessible
        // from the returned endpoint.
        ep, err := network.CreateEndpoint("Endpoint1")
        if err != nil {
                return
        }

        // A container can join the endpoint by providing the container ID to the join
        // api which returns the sandbox key which can be used to access the sandbox
        // created for the container during join.
        // Join acceps Variadic arguments which will be made use of by libnetwork and Drivers
        _, err = ep.Join("container1",
                libnetwork.JoinOptionHostname("test"),
                libnetwork.JoinOptionDomainname("docker.io"))
        if err != nil {
                return
        }

		// libentwork client can check the endpoint's operational data via the Info() API
		epInfo, err := ep.Info()
		mapData, ok := epInfo[options.PortMap]
		if ok {
			portMapping, ok := mapData.([]netutils.PortBinding)
			if ok {
				fmt.Printf("Current port mapping for endpoint %s: %v", ep.Name(), portMapping)
			}
		}

Future

See the roadmap.

Contributing

Want to hack on libnetwork? Docker's contributions guidelines apply.

Code and documentation copyright 2015 Docker, inc. Code released under the Apache 2.0 license. Docs released under Creative commons.

Documentation

Overview

Package libnetwork provides the basic functionality and extension points to create network namespaces and allocate interfaces for containers to use.

// Create a new controller instance
controller := libnetwork.New()

// Select and configure the network driver
networkType := "bridge"

driverOptions := options.Generic{}
genericOption := make(map[string]interface{})
genericOption[options.GenericData] = driverOptions
err := controller.ConfigureNetworkDriver(networkType, genericOption)
if err != nil {
        return
}

// Create a network for containers to join.
// NewNetwork accepts Variadic optional arguments that libnetwork and Drivers can make of
network, err := controller.NewNetwork(networkType, "network1")
if err != nil {
        return
}

// For each new container: allocate IP and interfaces. The returned network
// settings will be used for container infos (inspect and such), as well as
// iptables rules for port publishing. This info is contained or accessible
// from the returned endpoint.
ep, err := network.CreateEndpoint("Endpoint1")
if err != nil {
        return
}

// A container can join the endpoint by providing the container ID to the join
// api which returns the sandbox key which can be used to access the sandbox
// created for the container during join.
// Join acceps Variadic arguments which will be made use of by libnetwork and Drivers
_, err = ep.Join("container1",
        libnetwork.JoinOptionHostname("test"),
        libnetwork.JoinOptionDomainname("docker.io"))
if err != nil {
        return
}

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrNilNetworkDriver is returned if a nil network driver
	// is passed to NewNetwork api.
	ErrNilNetworkDriver = errors.New("nil NetworkDriver instance")
	// ErrInvalidNetworkDriver is returned if an invalid driver
	// instance is passed.
	ErrInvalidNetworkDriver = errors.New("invalid driver bound to network")
	// ErrInvalidJoin is returned if a join is attempted on an endpoint
	// which already has a container joined.
	ErrInvalidJoin = errors.New("A container has already joined the endpoint")
)

Functions

This section is empty.

Types

type ActiveEndpointsError

type ActiveEndpointsError struct {
	// contains filtered or unexported fields
}

ActiveEndpointsError is returned when a network is deleted which has active endpoints in it.

func (*ActiveEndpointsError) Error

func (aee *ActiveEndpointsError) Error() string

type ContainerData

type ContainerData struct {
	SandboxKey string
}

ContainerData is a set of data returned when a container joins an endpoint.

type Endpoint

type Endpoint interface {
	// A system generated id for this endpoint.
	ID() string

	// Name returns the name of this endpoint.
	Name() string

	// Network returns the name of the network to which this endpoint is attached.
	Network() string

	// Join creates a new sandbox for the given container ID and populates the
	// network resources allocated for the endpoint and joins the sandbox to
	// the endpoint. It returns the sandbox key to the caller
	Join(containerID string, options ...EndpointOption) (*ContainerData, error)

	// Leave removes the sandbox associated with  container ID and detaches
	// the network resources populated in the sandbox
	Leave(containerID string, options ...EndpointOption) error

	// SandboxInfo returns the sandbox information for this endpoint.
	SandboxInfo() *sandbox.Info

	// Info returns a collection of operational data related to this endpoint retrieved from the driver
	Info() (map[string]interface{}, error)

	// Delete and detaches this endpoint from the network.
	Delete() error
}

Endpoint represents a logical connection between a network and a sandbox.

type EndpointOption

type EndpointOption func(ep *endpoint)

EndpointOption is a option setter function type used to pass varios options to Network and Endpoint interfaces methods. The various setter functions of type EndpointOption are provided by libnetwork, they look like <Create|Join|Leave>Option[...](...)

func CreateOptionExposedPorts

func CreateOptionExposedPorts(exposedPorts []netutils.TransportPort) EndpointOption

CreateOptionExposedPorts function returns an option setter for the container exposed ports option to be passed to network.CreateEndpoint() method.

func CreateOptionPortMapping

func CreateOptionPortMapping(portBindings []netutils.PortBinding) EndpointOption

CreateOptionPortMapping function returns an option setter for the mapping ports option to be passed to network.CreateEndpoint() method.

func EndpointOptionGeneric

func EndpointOptionGeneric(generic map[string]interface{}) EndpointOption

EndpointOptionGeneric function returns an option setter for a Generic option defined in a Dictionary of Key-Value pair

func JoinOptionDNS

func JoinOptionDNS(dns string) EndpointOption

JoinOptionDNS function returns an option setter for dns entry option to be passed to endpoint Join method.

func JoinOptionDNSSearch

func JoinOptionDNSSearch(search string) EndpointOption

JoinOptionDNSSearch function returns an option setter for dns search entry option to be passed to endpoint Join method.

func JoinOptionDomainname

func JoinOptionDomainname(name string) EndpointOption

JoinOptionDomainname function returns an option setter for domainname option to be passed to endpoint Join method.

func JoinOptionExtraHost

func JoinOptionExtraHost(name string, IP string) EndpointOption

JoinOptionExtraHost function returns an option setter for extra /etc/hosts options which is a name and IP as strings.

func JoinOptionGeneric

func JoinOptionGeneric(generic map[string]interface{}) EndpointOption

JoinOptionGeneric function returns an option setter for Generic configuration that is not managed by libNetwork but can be used by the Drivers during the call to endpoint join method. Container Labels are a good example.

func JoinOptionHostname

func JoinOptionHostname(name string) EndpointOption

JoinOptionHostname function returns an option setter for hostname option to be passed to endpoint Join method.

func JoinOptionHostsPath

func JoinOptionHostsPath(path string) EndpointOption

JoinOptionHostsPath function returns an option setter for hostspath option to be passed to endpoint Join method.

func JoinOptionParentUpdate

func JoinOptionParentUpdate(eid string, name, ip string) EndpointOption

JoinOptionParentUpdate function returns an option setter for parent container which needs to update the IP address for the linked container.

func JoinOptionResolvConfPath

func JoinOptionResolvConfPath(path string) EndpointOption

JoinOptionResolvConfPath function returns an option setter for resolvconfpath option to be passed to endpoint Join method.

func JoinOptionUseDefaultSandbox

func JoinOptionUseDefaultSandbox() EndpointOption

JoinOptionUseDefaultSandbox function returns an option setter for using default sandbox to be passed to endpoint Join method.

func LeaveOptionGeneric

func LeaveOptionGeneric(context map[string]interface{}) EndpointOption

LeaveOptionGeneric function returns an option setter for Generic configuration that is not managed by libNetwork but can be used by the Drivers during the call to endpoint leave method. Container Labels are a good example.

type EndpointWalker

type EndpointWalker func(ep Endpoint) bool

EndpointWalker is a client provided function which will be used to walk the Endpoints. When the function returns true, the walk will stop.

type InvalidContainerIDError

type InvalidContainerIDError string

InvalidContainerIDError is returned when an invalid container id is passed in Join/Leave

func (InvalidContainerIDError) Error

func (id InvalidContainerIDError) Error() string

type Network

type Network interface {
	// A user chosen name for this network.
	Name() string

	// A system generated id for this network.
	ID() string

	// The type of network, which corresponds to its managing driver.
	Type() string

	// Create a new endpoint to this network symbolically identified by the
	// specified unique name. The options parameter carry driver specific options.
	// Labels support will be added in the near future.
	CreateEndpoint(name string, options ...EndpointOption) (Endpoint, error)

	// Delete the network.
	Delete() error

	// Endpoints returns the list of Endpoint(s) in this network.
	Endpoints() []Endpoint

	// WalkEndpoints uses the provided function to walk the Endpoints
	WalkEndpoints(walker EndpointWalker)

	// EndpointByName returns the Endpoint which has the passed name, if it exists otherwise nil is returned
	EndpointByName(name string) Endpoint

	// EndpointByID returns the Endpoint which has the passed id, if it exists otherwise nil is returned
	EndpointByID(id string) Endpoint
}

A Network represents a logical connectivity zone that containers may join using the Link method. A Network is managed by a specific driver.

type NetworkController

type NetworkController interface {
	// ConfigureNetworkDriver applies the passed options to the driver instance for the specified network type
	ConfigureNetworkDriver(networkType string, options map[string]interface{}) error

	// Create a new network. The options parameter carries network specific options.
	// Labels support will be added in the near future.
	NewNetwork(networkType, name string, options ...NetworkOption) (Network, error)

	// Networks returns the list of Network(s) managed by this controller.
	Networks() []Network

	// WalkNetworks uses the provided function to walk the Network(s) managed by this controller.
	WalkNetworks(walker NetworkWalker)

	// NetworkByName returns the Network which has the passed name, if it exists otherwise nil is returned
	NetworkByName(name string) Network

	// NetworkByID returns the Network which has the passed id, if it exists otherwise nil is returned
	NetworkByID(id string) Network
}

NetworkController provides the interface for controller instance which manages networks.

func New

func New() NetworkController

New creates a new instance of network controller.

type NetworkNameError

type NetworkNameError string

NetworkNameError is returned when a network with the same name already exists.

func (NetworkNameError) Error

func (name NetworkNameError) Error() string

type NetworkOption

type NetworkOption func(n *network)

NetworkOption is a option setter function type used to pass varios options to NewNetwork method. The various setter functions of type NetworkOption are provided by libnetwork, they look like NetworkOptionXXXX(...)

func NetworkOptionGeneric

func NetworkOptionGeneric(generic map[string]interface{}) NetworkOption

NetworkOptionGeneric function returns an option setter for a Generic option defined in a Dictionary of Key-Value pair

type NetworkTypeError

type NetworkTypeError string

NetworkTypeError type is returned when the network type string is not known to libnetwork.

func (NetworkTypeError) Error

func (nt NetworkTypeError) Error() string

type NetworkWalker

type NetworkWalker func(nw Network) bool

NetworkWalker is a client provided function which will be used to walk the Networks. When the function returns true, the walk will stop.

type UnknownEndpointError

type UnknownEndpointError struct {
	// contains filtered or unexported fields
}

UnknownEndpointError is returned when libnetwork could not find in it's database an endpoint with the same name and id.

func (*UnknownEndpointError) Error

func (uee *UnknownEndpointError) Error() string

type UnknownNetworkError

type UnknownNetworkError struct {
	// contains filtered or unexported fields
}

UnknownNetworkError is returned when libnetwork could not find in it's database a network with the same name and id.

func (*UnknownNetworkError) Error

func (une *UnknownNetworkError) Error() string

Directories

Path Synopsis
Godeps
_workspace/src/github.com/docker/docker/pkg/mflag
Package flag implements command-line flag parsing.
Package flag implements command-line flag parsing.
_workspace/src/github.com/docker/docker/pkg/resolvconf
Package resolvconf provides utility code to query and update DNS configuration in /etc/resolv.conf
Package resolvconf provides utility code to query and update DNS configuration in /etc/resolv.conf
_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.
_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.
_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.
_workspace/src/github.com/vishvananda/netlink
Package netlink provides a simple library for netlink.
Package netlink provides a simple library for netlink.
_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.
_workspace/src/github.com/vishvananda/netns
Package netns allows ultra-simple network namespace handling.
Package netns allows ultra-simple network namespace handling.
cmd
readme_test command
test command
drivers
Package ipallocator defines the default IP allocator.
Package ipallocator defines the default IP allocator.
pkg
options
Package options provides a way to pass unstructured sets of options to a component expecting a strongly-typed configuration structure.
Package options provides a way to pass unstructured sets of options to a component expecting a strongly-typed configuration structure.
Package types contains types that are common across libnetwork project
Package types contains types that are common across libnetwork project

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL