Documentation
¶
Overview ¶
Package cni wraps the bridge+host-local CNI plugin for containerd sandboxes. Our topology is a single bridge plugin with host-local IPAM embedded in its config, so ADD/DEL invoke that one plugin over the standard CNI exec protocol (CNI_* env vars + the plugin netconf on stdin) rather than chaining a plugin list. DEL is idempotent by the CNI contract (DEL on a missing allocation is a no-op); ADD is NOT idempotent at this layer — callers must not re-ADD the same container into the same netns or host-local allocates a second IP.
Index ¶
- Constants
- func BridgeMTU() int
- func BridgeName(path string) (string, error)
- func EnsureBridgeConflist(path string, opts ConflistOptions) error
- func IPMasqChain(network, containerID string) string
- func IPMasqComment(network, containerID string) string
- func RenderBridgeConflist(opts ConflistOptions) ([]byte, error)
- func UplinkMTU() int
- type Config
- type ConflistOptions
- type ExecRunner
- type FakeRunner
- func (f *FakeRunner) Add(ctx context.Context, netnsPath, containerID string) (Result, error)
- func (f *FakeRunner) Adds() []call
- func (f *FakeRunner) Del(ctx context.Context, netnsPath, containerID string) error
- func (f *FakeRunner) Dels() []call
- func (f *FakeRunner) IPOf(containerID string) (string, bool)
- func (f *FakeRunner) MasqTeardowns() []MasqCall
- func (f *FakeRunner) SetAddError(err error)
- func (f *FakeRunner) SetDelError(err error)
- func (f *FakeRunner) SetMasqError(err error)
- func (f *FakeRunner) TeardownIPMasq(ctx context.Context, containerID, containerIP string) error
- type IPMasqTeardown
- type MasqCall
- type Result
- type Runner
Constants ¶
const ( // DefaultBridgeMTU is the fallback bridge veth MTU when the host uplink MTU // cannot be determined. Docker-parity default. DefaultBridgeMTU = 1500 )
const DefaultBridgeName = "aerolvm0"
DefaultBridgeName is the bridge the generated conflist attaches sandboxes to.
const DefaultBridgeSubnet = "10.88.0.0/16"
DefaultBridgeSubnet is the host-local IPAM subnet for the aerolvm0 bridge. Shared so the netrules FORWARD-accept rules target the same CIDR the conflist hands out.
const DefaultPluginBridge = "cni0"
DefaultPluginBridge is the bridge the CNI bridge plugin creates when its config names none (containerd's stock conflist relies on it).
Variables ¶
This section is empty.
Functions ¶
func BridgeMTU ¶
func BridgeMTU() int
BridgeMTU is the docker-parity default MTU. Callers that want uplink parity use UplinkMTU() and fall back to this.
func BridgeName ¶ added in v0.6.9
BridgeName is the Linux bridge the conflist at path attaches sandboxes to: the "bridge" field of the plugin the runner invokes (plugins[0], see singlePluginNetconf), or the plugin's own default when it names none. The node's IPv6 fence drops IPv6 on that bridge by name, so it must be the one CNI really uses, which an operator-provided conflist may call anything.
func EnsureBridgeConflist ¶
func EnsureBridgeConflist(path string, opts ConflistOptions) error
EnsureBridgeConflist writes a bridge+host-local CNI conflist to path if it is absent, so the containerd netns pool has a network to realize. This is the §4 owner for items dockerd's libnetwork used to provide: the bridge, IPAM, and outbound NAT (`ipMasq: true`). It never overwrites an operator-provided conflist. Returns the effective path.
NOTE: the generated JSON is validated offline (schema + round-trip), but the plugins that consume it run only on a live host with /opt/cni/bin populated — exercised by the containerd integration suite, not `make test`.
func IPMasqChain ¶ added in v0.6.9
IPMasqChain is the nat chain the bridge plugin creates for (network, containerID): containernetworking/plugins pkg/utils FormatChainName, i.e. "CNI-" + hex(sha512(network+containerID)), cut to 28 characters.
func IPMasqComment ¶ added in v0.6.9
IPMasqComment is the rule comment the bridge plugin tags those rules with (pkg/utils FormatComment).
func RenderBridgeConflist ¶
func RenderBridgeConflist(opts ConflistOptions) ([]byte, error)
RenderBridgeConflist produces the conflist JSON. Kept separate from the file write so it is unit-testable without touching disk.
func UplinkMTU ¶
func UplinkMTU() int
UplinkMTU returns the MTU of the host's default-route interface, or 0 when it cannot be determined (non-linux, or no default route). Sizing the bridge/veth to the uplink avoids two failure modes the hardcoded 1500 caused: on a jumbo-frame uplink (AWS ENA is 9001) a 1500 bridge caps throughput, and on a sub-1500 uplink (overlay/VPN/GRE) a 1500 bridge blackholes egress via PMTUD.
Types ¶
type Config ¶
type Config struct {
// PluginDir is typically /opt/cni/bin.
PluginDir string
// ConfPath is a .conflist or .conf consumed by the plugin.
ConfPath string
// IfName is the interface created inside the netns; defaults to eth0.
IfName string
}
Config locates plugin binaries and the bridge conf on disk.
type ConflistOptions ¶
type ConflistOptions struct {
Name string // network name, e.g. "aerolvm"
Bridge string // host bridge interface, e.g. "aerolvm0"
Subnet string // host-local IPAM subnet, e.g. "10.88.0.0/16"
Gateway string // optional explicit gateway; host-local derives .1 if empty
MTU int // bridge/veth MTU; <=0 falls back to DefaultBridgeMTU
}
ConflistOptions parameterizes the generated bridge+host-local conflist.
type ExecRunner ¶
type ExecRunner struct {
// contains filtered or unexported fields
}
ExecRunner shells out to the CNI plugin binary referenced by ConfPath's `type`, speaking the CNI exec protocol.
func NewExecRunner ¶
func NewExecRunner(cfg Config) (*ExecRunner, error)
func (*ExecRunner) Del ¶
func (r *ExecRunner) Del(ctx context.Context, netnsPath, containerID string) error
func (*ExecRunner) TeardownIPMasq ¶ added in v0.6.9
func (r *ExecRunner) TeardownIPMasq(ctx context.Context, containerID, containerIP string) error
TeardownIPMasq deletes the bridge plugin's masquerade chain for containerID and every POSTROUTING rule that jumps to it. It only touches the chain whose name is derived from this network + containerID, so it can never remove another container's rules. Idempotent: an absent chain is success. containerIP is accepted for symmetry with the ADD; the POSTROUTING jumps are found by their target chain, which also catches any jump left from an earlier ADD of the same id under a different address.
type FakeRunner ¶
type FakeRunner struct {
// contains filtered or unexported fields
}
FakeRunner is an in-memory CNI backend for unit tests.
func NewFakeRunner ¶
func NewFakeRunner() *FakeRunner
func (*FakeRunner) Adds ¶
func (f *FakeRunner) Adds() []call
func (*FakeRunner) Del ¶
func (f *FakeRunner) Del(ctx context.Context, netnsPath, containerID string) error
func (*FakeRunner) Dels ¶
func (f *FakeRunner) Dels() []call
func (*FakeRunner) IPOf ¶ added in v0.6.9
func (f *FakeRunner) IPOf(containerID string) (string, bool)
IPOf returns the address ADD gave containerID that no DEL has released: what a real netns realized under that id would hold.
func (*FakeRunner) MasqTeardowns ¶ added in v0.6.9
func (f *FakeRunner) MasqTeardowns() []MasqCall
MasqTeardowns returns the recorded TeardownIPMasq calls.
func (*FakeRunner) SetAddError ¶
func (f *FakeRunner) SetAddError(err error)
func (*FakeRunner) SetDelError ¶
func (f *FakeRunner) SetDelError(err error)
func (*FakeRunner) SetMasqError ¶ added in v0.6.9
func (f *FakeRunner) SetMasqError(err error)
SetMasqError makes TeardownIPMasq fail with err (nil clears it).
func (*FakeRunner) TeardownIPMasq ¶ added in v0.6.9
func (f *FakeRunner) TeardownIPMasq(ctx context.Context, containerID, containerIP string) error
TeardownIPMasq records the call; it implements IPMasqTeardown.
type IPMasqTeardown ¶ added in v0.6.9
type IPMasqTeardown interface {
TeardownIPMasq(ctx context.Context, containerID, containerIP string) error
}
IPMasqTeardown removes the outbound-NAT (ipMasq) state the bridge plugin's ADD installed for one container id, independent of the plugin's own DEL.
Why the plugin's DEL is not enough: it derives which masquerade rules to delete from the addresses it finds on the container interface at DEL time (plugins/main/bridge cmdDel → ip.DelLinkByNameAddr → TeardownIPMasq per address). gVisor's runsc, in its default network=sandbox mode, moves the interface address into its own netstack and deletes it from the interface when the sandbox starts, so DEL sees no address and leaves the NAT chain and its POSTROUTING jump behind: four iptables lines per gVisor sandbox.
type MasqCall ¶ added in v0.6.9
type MasqCall struct {
ContainerID, ContainerIP string
}
MasqCall records one TeardownIPMasq call.