sidecar

package
v0.0.0-...-1614f50 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: AGPL-3.0 Imports: 24 Imported by: 0

Documentation

Overview

Package sidecar runs the container that stands in for a cloud network's fixed addresses from inside the network: the resolver the cloud's DHCP hands out and the metadata endpoints, both forwarded to the simulator. One sidecar serves one engine network at the address the cloud reserves for them, so a workload on the network reaches them the way it reaches them in the cloud, and the simulator attributes what arrives through a sidecar to its network.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddLoopbackAddresses

func AddLoopbackAddresses(ctx context.Context, containerID string, addrs []netip.Addr) error

AddLoopbackAddresses adds each address to the loopback of a container's network namespace, through a one-shot sidecar holding NET_ADMIN alone.

func DNSUpstream

func DNSUpstream(host string, port int) string

DNSUpstream renders the simulator's per-network listener as the sidecar reaches it.

func EgressReports

func EgressReports(take func(network string, report egress.Report)) http.HandlerFunc

EgressReports is the handler a simulator mounts at egress.ReportPath: it hands each report to take with the network whose sidecar sent it, which the sidecar's token establishes, and refuses a report from anything else.

func EnsureImage

func EnsureImage(ctx context.Context, cli *client.Client) (string, string, error)

EnsureImage builds the sidecar image for the engine's own architecture, once per engine and source version, and returns the image and its platform.

func NamespacePID

func NamespacePID(hostPID int) (int, error)

NamespacePID is the id a process has inside the pid namespace it runs in, read from its host entry's NSpid line, which any process on the host may read. hostPID is the id the engine's process table reports.

func ReadProcess

func ReadProcess(ctx context.Context, containerID string, pid int, what string) ([]byte, error)

ReadProcess reads a workload process's mapping table (what "maps") or an ELF core of it (what "core"). The simulator's own host does not let an unprivileged process read another identity's /proc, and a core needs permission to trace, which no workload holds; so the sidecar program joins the container's pid namespace as a platform helper with that one permission, writes what it read into a directory only the simulator mounted, and ends. pid is the process's id inside the container.

func SetRoute

func SetRoute(ctx context.Context, containerID, gateway string, routes []sim.Route) error

SetRoute points the default route of a container's network namespace at gateway, removes it for sim.NoGateway or leaves it for the empty gateway, and adds each of routes, through a one-shot sidecar that joins the namespace holding NET_ADMIN alone.

func Start

func Start(ctx context.Context, spec Spec, sink sim.LogSink) (*sim.ContainerHandle, error)

Start runs a sidecar and returns its handle; the container goes with the handle's Cancel.

func StartEgress

func StartEgress(ctx context.Context, spec EgressSpec, sink sim.LogSink) (*sim.ContainerHandle, error)

StartEgress runs an egress sidecar and returns its handle once it carries connections, or when ctx ends first; the container goes with the handle's Cancel. The sidecar programs the redirect in its own network namespace, which the one capability it keeps allows and nothing else.

func StartForwarder

func StartForwarder(ctx context.Context, spec ForwarderSpec, sink sim.LogSink) (*sim.ContainerHandle, error)

StartForwarder runs a forwarder and returns its handle once its forwards listen, or an error when ctx ends first; the container goes with the handle's Cancel. It holds no capability: the listeners are unprivileged ports. A spec with no forwards starts a holder, which owns the namespace and relays nothing.

func StartGatewayLoadBalancerNode

func StartGatewayLoadBalancerNode(ctx context.Context, spec GatewayLoadBalancerNodeSpec, sink sim.LogSink) (*sim.ContainerHandle, error)

StartGatewayLoadBalancerNode runs a node and returns its handle once it carries traffic, or when ctx ends first; the container goes with the handle's Cancel. The node programs its routing and its TUN devices in its own network namespace, which the one capability it keeps and the TUN device it is handed allow, and nothing else.

func StartShares

func StartShares(ctx context.Context, spec SharesSpec, sink sim.LogSink) (*sim.ContainerHandle, error)

StartShares runs a share container and returns its handle once it serves, or when ctx ends first; the container goes with the handle's Cancel. The server reads and writes the volumes' files as their owners, which the capabilities it keeps allow and nothing else.

func WaitReady

func WaitReady(ctx context.Context, address netip.Addr) error

WaitReady returns once the sidecar answers DNS at its address from the simulator's side, or ctx ends. On a host that routes no container address it returns at once: nothing there can probe the sidecar but a workload.

Types

type EgressSpec

type EgressSpec struct {
	// Network is the engine network the gateway serves.
	Network string
	// Address is the gateway's address inside the network's range.
	Address netip.Addr
	Name    string
	// Gateway names the gateway in the sidecar's reports.
	Gateway string
	// Sources are the ranges whose connections the gateway carries.
	Sources []netip.Prefix
	// Local are the ranges a connection stays inside the network for; the
	// network's own range at least.
	Local []netip.Prefix
	// TCPIdle and UDPIdle are the gateway's idle timeouts.
	TCPIdle time.Duration
	UDPIdle time.Duration
	// HTTPUpstream is the simulator's HTTP origin as the sidecar reaches it,
	// where the reports go.
	HTTPUpstream string
	// Token is the credential the simulator minted for this sidecar.
	Token      string
	ExtraHosts []string
	Labels     map[string]string
}

EgressSpec places one egress sidecar: a cloud's NAT gateway from inside the network, at the gateway's address, carrying the connections the sources open toward the outside from that address.

type Forward

type Forward struct {
	Listen   string
	Upstream string
}

Forward is a TCP listener on a workload's own loopback, Listen, that relays each connection to Upstream, an address on the workload's network.

type ForwarderSpec

type ForwarderSpec struct {
	// Namespace is the network side of the workload's configuration: its
	// network, address, interface, aliases, hosts, resolvers, hostname and
	// published ports.
	Namespace sim.ContainerConfig
	Forwards  []Forward
	// Workload names the workload the forwarder serves, for its label.
	Workload string
}

ForwarderSpec places one forwarder: the sidecar program as the owner of a workload's network namespace, placed with the workload's network settings before the workload joins it, so the forwards listen before the workload's first process runs.

type GatewayLoadBalancerEndpoint

type GatewayLoadBalancerEndpoint struct {
	ID      string
	Network string
	Address netip.Prefix
}

GatewayLoadBalancerEndpoint is one Gateway Load Balancer endpoint a node serves: its identifier, and its address with the prefix length of the network it sits on.

type GatewayLoadBalancerNodeSpec

type GatewayLoadBalancerNodeSpec struct {
	// Node names the node in its state requests.
	Node      string
	Name      string
	Network   string
	Address   netip.Addr
	Endpoints []GatewayLoadBalancerEndpoint
	// HTTPUpstream is the simulator's HTTP origin as the node reaches it,
	// where it asks for its state.
	HTTPUpstream string
	// Token is the credential the simulator minted for this node.
	Token      string
	ExtraHosts []string
	Labels     map[string]string
}

GatewayLoadBalancerNodeSpec places one zone's node of a Gateway Load Balancer: on the load balancer's network at its address there, and on each endpoint's network at the endpoint's address.

type Manager

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

Manager keeps one sidecar per engine network a simulator places workloads on, each with its own listener on the simulator's resolver and its own token, and removes them with their networks.

func NewManager

func NewManager(resolver *dnsserver.Server, httpOrigin string, sink sim.LogSink) *Manager

NewManager serves sidecars that forward DNS to resolver and HTTP to the simulator at httpOrigin, as workloads reach it (workloadhost.CallbackAddr).

func (*Manager) Close

func (m *Manager) Close()

Close stops every sidecar.

func (*Manager) Ensure

func (m *Manager) Ensure(ctx context.Context, network string, address netip.Addr) (*Running, error)

Ensure runs the sidecar of an engine network that exists, at address — or, when address is the zero value, at the second host of the network's range, which every cloud reserves — and returns it; a network whose sidecar runs gets that one. A sidecar a previous simulator process left on the network is replaced: its token and listener died with that process.

func (*Manager) LinkLocal

func (m *Manager) LinkLocal() []netip.Addr

LinkLocal is what ServeLinkLocal set.

func (*Manager) Remove

func (m *Manager) Remove(network string)

Remove stops the network's sidecar, if one runs, so the network can go.

func (*Manager) ServeLinkLocal

func (m *Manager) ServeLinkLocal(addrs ...netip.Addr)

ServeLinkLocal has every sidecar the manager starts answer at addrs too: the fixed link-local addresses the cloud serves its metadata on, which a workload routes to its network's sidecar.

type Running

type Running struct {
	Network string
	Address netip.Addr
	// contains filtered or unexported fields
}

Running is a sidecar the manager started.

type ShareVolume

type ShareVolume struct {
	Volume   string
	Export   string
	ReadOnly bool
}

ShareVolume is one engine volume a share container serves, under Export, the name a guest mounts it by.

type SharesSpec

type SharesSpec struct {
	Name string
	// NamespaceOf is the container whose network namespace the share
	// container joins.
	NamespaceOf string
	// Port is the TCP port the shares are served on in that namespace.
	Port    int
	Volumes []ShareVolume
	Labels  map[string]string
}

SharesSpec places one share container: the sidecar program serving engine volumes over NFSv4 from inside another container's network namespace, the node agent's, where every guest reaches it at the agent's address.

type Spec

type Spec struct {
	// Network is the engine network the sidecar serves.
	Network string
	// Address is the sidecar's fixed address inside the network's range: the
	// address the cloud reserves for its resolver and metadata service.
	Address netip.Addr
	Name    string
	// DNSUpstream is the host:port of the simulator's listener for this
	// network (dnsserver.Server.ListenNetwork), as the sidecar reaches it.
	DNSUpstream string
	// HTTPUpstream is the simulator's HTTP origin as the sidecar reaches it.
	HTTPUpstream string
	// Token is the credential the simulator minted for this sidecar; the
	// simulator trusts the querier address a request carries only with it.
	Token string
	// ExtraHosts are the host entries the sidecar needs to reach the upstreams
	// by name (workloadhost.ExtraHosts on an engine that runs in a machine).
	ExtraHosts []string
	Labels     map[string]string
}

Spec places one sidecar.

Directories

Path Synopsis
cmd
sidecar command
Command sidecar stands in for a cloud network's fixed addresses from inside the network: it answers DNS at the cloud's resolver address and the metadata endpoints at the address the cloud serves them on, and forwards both to the simulator that started it.
Command sidecar stands in for a cloud network's fixed addresses from inside the network: it answers DNS at the cloud's resolver address and the metadata endpoints at the address the cloud serves them on, and forwards both to the simulator that started it.
sidecar-image command
Command sidecar-image builds the network sidecar's image on the engine, or finds it held, and prints its name.
Command sidecar-image builds the network sidecar's image on the engine, or finds it held, and prints its name.
Package egress is what an egress sidecar and the simulator that started it share: the report the sidecar sends about the connections it carried, and the names its configuration travels under.
Package egress is what an egress sidecar and the simulator that started it share: the report the sidecar sends about the connections it carried, and the names its configuration travels under.
Package gwlb is what a Gateway Load Balancer node sidecar and the simulator that starts it share: the environment that places the node, and the state it long-polls the simulator for.
Package gwlb is what a Gateway Load Balancer node sidecar and the simulator that starts it share: the environment that places the node, and the state it long-polls the simulator for.

Jump to

Keyboard shortcuts

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