nsplugin

package
v1.9.0-alpha Latest Latest
Warning

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

Go to latest
Published: Dec 12, 2018 License: Apache-2.0 Imports: 18 Imported by: 0

README

Linux namespace plugin

Auxiliary plugin used mainly by other plugins to handle namespaces and microservices.

Namespaces

Agent has full support for Linux network namespaces. It is possible to attach Linux interface into a new, existing or even yet-to-be-created network namespace via the namespace configuration section inside the LinuxInterfaces configuration data model.

Namespace can be referenced in multiple ways. The most low-level link to a namespace is a file descriptor associated with the symbolic link automatically created in the proc filesystem, pointing to the definition of the namespace used by a given process (/proc/<PID>/ns/net) or by a task of a given process (/proc/<PID>/task/<TID>/ns/net). A more common approach to reference namespace is to use just the PID of the process whose namespace we want to attach to, or to create a bind-mount of the symbolic link into /var/run/netns directory and use the filename of that mount. The latter is called named namespace and it is created and managed for example by the ip netns command line tool from the iproute2 package. The advantage of named namespace is that it can outlive the process it was originally created by.

namespace configuration section should be seen as a union of values. First, set the type and then store the reference into the appropriate field (pid vs. name vs microservice). Agent supports both PID-based references as well as named namespaces.

Microservices

Additionally, we provide a non-standard namespace reference, denoted as MICROSERVICE_REF_NS, which is specific to ecosystems with microservices. It is possible to attach interface into the namespace of a container that runs microservice with a given label. To make it even simpler, it is not required to start the microservice before the interface is configured. The agent will postpone interface (re)configuration until the referenced microservice gets launched. Behind the scenes, the agent communicates with the docker daemon to construct and maintain an up-to-date map of microservice labels to PIDs and IDs of their corresponding containers. Whenever a new microservice is detected, all pending interfaces are moved to its namespace.

Documentation

Index

Constants

View Source
const (
	// NewMicroservice event type
	NewMicroservice = "new-ms"
	// TerminatedMicroservice event type
	TerminatedMicroservice = "term-ms"
)

Microservice event types

View Source
const (

	// Namespace types
	PidRefNs          = 0
	MicroserviceRefNs = 1
	NamedNs           = 2
	FileRefNs         = 3
)

Namespace-related constants

Variables

This section is empty.

Functions

This section is empty.

Types

type Microservice

type Microservice struct {
	Label string
	PID   int
	ID    string
}

Microservice is used to store PID and ID of the container running a given microservice.

type MicroserviceCtx

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

MicroserviceCtx contains all data required to handle microservice changes

type MicroserviceEvent

type MicroserviceEvent struct {
	*Microservice
	EventType string
}

MicroserviceEvent contains microservice object and event type

type Microservices

type Microservices interface {
	// HandleMicroservices handles microservice changes
	HandleMicroservices(ctx *MicroserviceCtx)
}

Microservices defines all methods needed to manage microservices

type Namespace

type Namespace struct {
	Type         int32
	Pid          uint32
	Microservice string
	Name         string
	FilePath     string
}

Namespace is a generic representation of typed namespace (interface, arp, etc...)

func (*Namespace) CompareNamespaces

func (ns *Namespace) CompareNamespaces(nsToCompare *Namespace) int

CompareNamespaces is a comparison function for "Namespace" type.

func (*Namespace) GenericNsToString

func (ns *Namespace) GenericNsToString() string

GenericNsToString returns a string representation of a namespace suitable for logging purposes.

func (*Namespace) GenericToIfaceNs

func (ns *Namespace) GenericToIfaceNs() (*intf.LinuxInterfaces_Interface_Namespace, error)

GenericToIfaceNs converts generic namespace to interface-type namespace

type NamespaceAPI

type NamespaceAPI interface {
	NsManagement
	NsConvertor
	Microservices
}

NamespaceAPI defines all methods required for managing namespaces and microservices

type NamespaceMgmtCtx

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

NamespaceMgmtCtx represents context of an ongoing management of Linux namespaces. The same context should not be used concurrently.

func NewNamespaceMgmtCtx

func NewNamespaceMgmtCtx() *NamespaceMgmtCtx

NewNamespaceMgmtCtx creates and returns a new context for management of Linux namespaces.

type NetNsNamespace

type NetNsNamespace interface {
	// NewNetworkNamespace crates new namespace and returns handle to manage it further
	NewNetworkNamespace() (ns netns.NsHandle, err error)
	// GetNamespaceFromName returns namespace handle from its name
	GetNamespaceFromName(name string) (ns netns.NsHandle, err error)
	// SetNamespace sets the current namespace to the namespace represented by the handle
	SetNamespace(ns netns.NsHandle) (err error)
}

NetNsNamespace defines method for namespace handling from netns package

type NetlinkNamespace

type NetlinkNamespace interface {
	// LinkSetNsFd puts the device into a new network namespace.
	LinkSetNsFd(link netlink.Link, fd int) (err error)
}

NetlinkNamespace defines method for namespace handling from netlink package

type NsConvertor

type NsConvertor interface {
	// IfaceNsToString returns a string representation of namespace
	IfaceNsToString(namespace *interfaces.LinuxInterfaces_Interface_Namespace) string
	// IfNsToGeneric converts interface-specific type namespace to generic type
	IfNsToGeneric(ns *interfaces.LinuxInterfaces_Interface_Namespace) *Namespace
	// ArpNsToGeneric converts arp-specific type namespace to generic type
	ArpNsToGeneric(ns *l3.LinuxStaticArpEntries_ArpEntry_Namespace) *Namespace
	// GenericToArpNs converts generic namespace to arp-specific type
	GenericToArpNs(ns *Namespace) (*l3.LinuxStaticArpEntries_ArpEntry_Namespace, error)
	// RouteNsToGeneric converts route-specific type namespace to generic type
	RouteNsToGeneric(ns *l3.LinuxStaticRoutes_Route_Namespace) *Namespace
}

NsConvertor defines common methods to convert namespace types

type NsHandler

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

NsHandler is a plugin to handle namespaces and microservices for other linux plugins (ifplugin, l3plugin ...). It does not follow the standard concept of CRUD, but provides a set of methods other plugins can use to manage namespaces

func (*NsHandler) ArpNsToGeneric

ArpNsToGeneric converts arp-type namespace to generic type namespace. Such an object can be used to call common namespace-related methods

func (*NsHandler) Close

func (h *NsHandler) Close() error

Close pre-configured namespace

func (*NsHandler) ConvertMicroserviceNsToPidNs

func (h *NsHandler) ConvertMicroserviceNsToPidNs(microserviceLabel string) (pidNs *Namespace)

ConvertMicroserviceNsToPidNs converts microservice-referenced namespace into the PID-referenced namespace.

func (*NsHandler) GenericToArpNs

GenericToArpNs converts generic namespace to arp-type namespace

func (*NsHandler) GenericToRouteNs

func (h *NsHandler) GenericToRouteNs(ns *Namespace) (*l3.LinuxStaticRoutes_Route_Namespace, error)

GenericToRouteNs converts generic namespace to arp-type namespace

func (*NsHandler) GetConfigNamespace

func (h *NsHandler) GetConfigNamespace() *intf.LinuxInterfaces_Interface_Namespace

GetConfigNamespace return configuration namespace object

func (*NsHandler) GetMicroserviceByID

func (h *NsHandler) GetMicroserviceByID() map[string]*Microservice

GetMicroserviceByID returns internal microservice-by-id mapping

func (*NsHandler) GetMicroserviceByLabel

func (h *NsHandler) GetMicroserviceByLabel() map[string]*Microservice

GetMicroserviceByLabel returns internal microservice-by-label mapping

func (*NsHandler) GetOrCreateNamespace

func (h *NsHandler) GetOrCreateNamespace(ns *Namespace) (netns.NsHandle, error)

GetOrCreateNamespace returns an existing Linux network namespace or creates a new one if it doesn't exist yet. It is, however, only possible to create "named" namespaces. For PID-based namespaces, process with the given PID must exists, otherwise the function returns an error.

func (*NsHandler) HandleMicroservices

func (h *NsHandler) HandleMicroservices(ctx *MicroserviceCtx)

HandleMicroservices handles microservice changes

func (*NsHandler) IfNsToGeneric

IfNsToGeneric converts interface-type namespace to generic type namespace. Such an object can be used to call common namespace-related methods

func (*NsHandler) IfaceNsToString

func (h *NsHandler) IfaceNsToString(namespace *intf.LinuxInterfaces_Interface_Namespace) string

IfaceNsToString returns a string representation of a namespace suitable for logging purposes.

func (*NsHandler) Init

func (h *NsHandler) Init(logger logging.PluginLogger, sysHandler SystemAPI, msChan chan *MicroserviceCtx,
	ifNotif chan *MicroserviceEvent) error

Init namespace handler caches and create config namespace

func (*NsHandler) IsNamespaceAvailable

func (h *NsHandler) IsNamespaceAvailable(ns *intf.LinuxInterfaces_Interface_Namespace) bool

IsNamespaceAvailable returns true if the destination namespace is available.

func (*NsHandler) RouteNsToGeneric

func (h *NsHandler) RouteNsToGeneric(ns *l3.LinuxStaticRoutes_Route_Namespace) *Namespace

RouteNsToGeneric converts route-type namespace to generic type namespace. Such an object can be used to call common namespace-related methods

func (*NsHandler) SwitchNamespace

func (h *NsHandler) SwitchNamespace(ns *Namespace, ctx *NamespaceMgmtCtx) (revert func(), err error)

SwitchNamespace switches the network namespace of the current thread. Caller should eventually call the returned "revert" function in order to get back to the original network namespace (for example using "defer revert()").

func (*NsHandler) SwitchToNamespace

func (h *NsHandler) SwitchToNamespace(nsMgmtCtx *NamespaceMgmtCtx, ns *intf.LinuxInterfaces_Interface_Namespace) (revert func(), err error)

SwitchToNamespace switches the network namespace of the current thread.

type NsManagement

type NsManagement interface {
	// GetOrCreateNamespace returns an existing Linux network namespace or creates a new one if it doesn't exist yet.
	// Only named namespaces can be created
	GetOrCreateNamespace(ns *Namespace) (netns.NsHandle, error)
	// IsNamespaceAvailable verifies whether required namespace exists and is accessible
	IsNamespaceAvailable(ns *interfaces.LinuxInterfaces_Interface_Namespace) bool
	// SwitchNamespace switches the network namespace of the current thread
	SwitchNamespace(ns *Namespace, ctx *NamespaceMgmtCtx) (revert func(), err error)
	// SwitchToNamespace switches the network namespace of the current thread // todo merge these two methods if possible
	SwitchToNamespace(nsMgmtCtx *NamespaceMgmtCtx, ns *interfaces.LinuxInterfaces_Interface_Namespace) (revert func(), err error)
	// GetConfigNamespace returns configuration namespace (used for VETHs)
	GetConfigNamespace() *interfaces.LinuxInterfaces_Interface_Namespace
	//ConvertMicroserviceNsToPidNs converts microservice-referenced namespace into the PID-referenced namespace
	ConvertMicroserviceNsToPidNs(msLabel string) (pidNs *Namespace)
}

NsManagement defines methods to manage namespaces

type OperatingSystem

type OperatingSystem interface {
	// Open file
	OpenFile(name string, flag int, perm os.FileMode) (*os.File, error)
	// MkDirAll creates a directory with all parent directories
	MkDirAll(path string, perm os.FileMode) error
	// Remove removes named file or directory
	Remove(name string) error
}

OperatingSystem defines all methods calling os package

type Syscall

type Syscall interface {
	// Mount makes resources available
	Mount(source string, target string, fsType string, flags uintptr, data string) error
	// Unmount resources
	Unmount(target string, flags int) (err error)
}

Syscall defines methods using low-level operating system primitives

type SystemAPI

SystemAPI defines all methods required for managing operating system, system calls and namespaces on system level

type SystemHandler

type SystemHandler struct{}

SystemHandler implements interfaces.

func NewSystemHandler

func NewSystemHandler() *SystemHandler

NewSystemHandler returns new handler.

func (*SystemHandler) GetNamespaceFromName

func (osh *SystemHandler) GetNamespaceFromName(name string) (ns netns.NsHandle, err error)

GetNamespaceFromName implements NetNsNamespace.

func (*SystemHandler) LinkSetNsFd

func (osh *SystemHandler) LinkSetNsFd(link netlink.Link, fd int) (err error)

LinkSetNsFd implements NetlinkNamespace.

func (*SystemHandler) MkDirAll

func (osh *SystemHandler) MkDirAll(path string, perm os.FileMode) error

MkDirAll implements OperatingSystem.

func (*SystemHandler) Mount

func (osh *SystemHandler) Mount(source string, target string, fsType string, flags uintptr, data string) error

Mount implements Syscall.

func (*SystemHandler) NewNetworkNamespace

func (osh *SystemHandler) NewNetworkNamespace() (ns netns.NsHandle, err error)

NewNetworkNamespace implements NetNsNamespace.

func (*SystemHandler) OpenFile

func (osh *SystemHandler) OpenFile(name string, flag int, perm os.FileMode) (*os.File, error)

OpenFile implements OperatingSystem.

func (*SystemHandler) Remove

func (osh *SystemHandler) Remove(name string) error

Remove implements OperatingSystem.

func (*SystemHandler) SetNamespace

func (osh *SystemHandler) SetNamespace(ns netns.NsHandle) (err error)

SetNamespace implements NetNsNamespace.

func (*SystemHandler) Unmount

func (osh *SystemHandler) Unmount(target string, flags int) error

Unmount implements Syscall.

Jump to

Keyboard shortcuts

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