nsplugin

package
v1.8.0-alpha Latest Latest
Warning

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

 Go to latest Published: Oct 4, 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 added in v1.8.1 

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 

func (h *NsHandler) ArpNsToGeneric(ns *l3.LinuxStaticArpEntries_ArpEntry_Namespace) *Namespace

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 added in v1.8.1 

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

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

func (*NsHandler) GenericToArpNs 

func (h *NsHandler) GenericToArpNs(ns *Namespace) (*l3.LinuxStaticArpEntries_ArpEntry_Namespace, error)

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 added in v1.8.1 

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 

func (h *NsHandler) IfNsToGeneric(ns *intf.LinuxInterfaces_Interface_Namespace) *Namespace

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 

type SystemAPI interface {
	OperatingSystem
	Syscall
	NetNsNamespace
	NetlinkNamespace
}

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

type SystemHandler added in v1.8.1 

type SystemHandler struct{}

SystemHandler implements interfaces.

func NewSystemHandler 

func NewSystemHandler() *SystemHandler

NewSystemHandler returns new handler.

func (*SystemHandler) GetNamespaceFromName added in v1.8.1 

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

GetNamespaceFromName implements NetNsNamespace.

func (*SystemHandler) LinkSetNsFd added in v1.8.1 

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

LinkSetNsFd implements NetlinkNamespace.

func (*SystemHandler) MkDirAll added in v1.8.1 

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

MkDirAll implements OperatingSystem.

func (*SystemHandler) Mount added in v1.8.1 

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

Mount implements Syscall.

func (*SystemHandler) NewNetworkNamespace added in v1.8.1 

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

NewNetworkNamespace implements NetNsNamespace.

func (*SystemHandler) OpenFile added in v1.8.1 

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

OpenFile implements OperatingSystem.

func (*SystemHandler) Remove added in v1.8.1 

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

Remove implements OperatingSystem.

func (*SystemHandler) SetNamespace added in v1.8.1 

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

SetNamespace implements NetNsNamespace.

func (*SystemHandler) Unmount added in v1.8.1 

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

Unmount implements Syscall.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.