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 ¶
- func AddLoopbackAddresses(ctx context.Context, containerID string, addrs []netip.Addr) error
- func DNSUpstream(host string, port int) string
- func EgressReports(take func(network string, report egress.Report)) http.HandlerFunc
- func EnsureImage(ctx context.Context, cli *client.Client) (string, string, error)
- func NamespacePID(hostPID int) (int, error)
- func ReadProcess(ctx context.Context, containerID string, pid int, what string) ([]byte, error)
- func SetRoute(ctx context.Context, containerID, gateway string, routes []sim.Route) error
- func Start(ctx context.Context, spec Spec, sink sim.LogSink) (*sim.ContainerHandle, error)
- func StartEgress(ctx context.Context, spec EgressSpec, sink sim.LogSink) (*sim.ContainerHandle, error)
- func StartForwarder(ctx context.Context, spec ForwarderSpec, sink sim.LogSink) (*sim.ContainerHandle, error)
- func StartGatewayLoadBalancerNode(ctx context.Context, spec GatewayLoadBalancerNodeSpec, sink sim.LogSink) (*sim.ContainerHandle, error)
- func StartShares(ctx context.Context, spec SharesSpec, sink sim.LogSink) (*sim.ContainerHandle, error)
- func WaitReady(ctx context.Context, address netip.Addr) error
- type EgressSpec
- type Forward
- type ForwarderSpec
- type GatewayLoadBalancerEndpoint
- type GatewayLoadBalancerNodeSpec
- type Manager
- type Running
- type ShareVolume
- type SharesSpec
- type Spec
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddLoopbackAddresses ¶
AddLoopbackAddresses adds each address to the loopback of a container's network namespace, through a one-shot sidecar holding NET_ADMIN alone.
func DNSUpstream ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
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 ¶
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 ¶
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 ¶
NewManager serves sidecars that forward DNS to resolver and HTTP to the simulator at httpOrigin, as workloads reach it (workloadhost.CallbackAddr).
func (*Manager) Ensure ¶
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) ServeLinkLocal ¶
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 ShareVolume ¶
type ShareVolume struct {
}
ShareVolume is one engine volume a share container serves, under Export, the name a guest mounts it by.
type SharesSpec ¶
type SharesSpec struct {
// container joins.
NamespaceOf string
// Port is the TCP port the shares are served on in that namespace.
}
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. |