embedded

package
v0.1.0-alpha.41 Latest Latest
Warning

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

Go to latest
Published: Nov 22, 2026 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Overview

Package embedded runs containers on Armada's own containerd instance (ADR 0011). Release builds carry containerd, runc, the CNI plugins, and tini in the binary; this file pins exactly which upstream artifacts.

Index

Constants

View Source
const (
	BinContainerd = "containerd"
	BinShim       = "containerd-shim-runc-v2"
	BinRunc       = "runc"
	BinTini       = "tini"
	// BinLogger is Armada's own log writer (logger/), built from source
	// rather than pinned here; packs without it use `armadad runtime-log`.
	BinLogger = "armada-log"
	// BinArmadaShim supervises containers without containerd (shim/,
	// ADR 0046), built from source like armada-log.
	BinArmadaShim = "armada-shim"
	DirCNI        = "cni"
)

Names of the bundled files the runtime uses.

View Source
const BridgeName = "armada0"

BridgeName is the per-node container bridge.

View Source
const (

	// DefaultLogRetention is how long history is kept unless the cluster
	// says otherwise.
	DefaultLogRetention = 7 * 24 * time.Hour
)
View Source
const Namespace = "armada"

Namespace is the containerd namespace holding Armada's containers.

Variables

View Source
var DefaultSubnet = netip.MustParsePrefix("10.121.0.0/24")

DefaultSubnet is the container bridge subnet unless configured otherwise.

View Source
var Lock = []Artifact{
	{
		Name:    "containerd",
		Version: "2.4.2",
		URL:     "https://github.com/containerd/containerd/releases/download/v2.4.2/containerd-static-2.4.2-linux-{arch}.tar.gz",
		SHA256: map[string]string{
			"amd64": "da656542e754c699a0f438eab925e6ffdbd6346a4428e659f83dc058f04dcffe",
			"arm64": "37b84b9534533672528141b9d815f58621a2fe5deee2daa84317800255756689",
		},
		Files: map[string]string{
			"bin/containerd":              "containerd",
			"bin/containerd-shim-runc-v2": "containerd-shim-runc-v2",
		},
	},
	{
		Name:    "runc",
		Version: "1.5.2",
		URL:     "https://github.com/opencontainers/runc/releases/download/v1.5.2/runc.{arch}",
		SHA256: map[string]string{
			"amd64": "599f6f94ff8c5057241eff0d54c3c74f95c34935b6457b33fe545defc61e9488",
			"arm64": "d10ecae898361832a059be2089bab92d158aec54661b18ed7346ed79628b46b0",
		},
	},
	{
		Name:    "cni-plugins",
		Version: "1.9.1",
		URL:     "https://github.com/containernetworking/plugins/releases/download/v1.9.1/cni-plugins-linux-{arch}-v1.9.1.tgz",
		SHA256: map[string]string{
			"amd64": "b98f74a0f8522f0a83867178729c1aa70f2158f90c45a2ca8fa791db1c76b303",
			"arm64": "56171987d3947707c3563db2f4001bccaf50fd63468611b9f3cbecb1375ee7ec",
		},
		Files: map[string]string{
			"./bridge":     "cni/bridge",
			"./host-local": "cni/host-local",
			"./loopback":   "cni/loopback",
			"./portmap":    "cni/portmap",
			"./firewall":   "cni/firewall",
		},
	},
	{
		Name:    "tini",
		Version: "0.19.0",
		URL:     "https://github.com/krallin/tini/releases/download/v0.19.0/tini-static-{arch}",
		SHA256: map[string]string{
			"amd64": "c5b0666b4cb676901f90dfcb37106783c5fe2077b04590973b885950611b30ee",
			"arm64": "eae1d3aa50c48fb23b8cbdf4e369d0910dfc538566bfd09df89a774aa84a48b9",
		},
	},
}

Lock lists every artifact in the bundle.

Functions

func Bundled

func Bundled() []byte

Bundled returns the pack compiled into this binary, or nil if it was built without the bundle tag.

func CheckHost

func CheckHost() error

CheckHost verifies what the embedded runtime needs from the kernel.

func ContainerdConfig

func ContainerdConfig(p Paths) string

ContainerdConfig renders containerd's configuration (format 4): its own root, state, and socket, nothing imported from the host's /etc/containerd, no listeners besides the socket.

func DefaultHistoryBytes

func DefaultHistoryBytes(dir string) int64

DefaultHistoryBytes is the history size when the cluster sets none: 10% of the file system holding dir, between 64 MiB and 5 GiB.

func DisableIPv6

func DisableIPv6(link string) error

DisableIPv6 turns IPv6 off on the bridge link. Containers get only IPv4 addresses, and the space isolation firewall filters only IPv4: with IPv6 on, the bridge would have a link-local address through which every container reaches the host's IPv6 listeners (T13). A kernel without IPv6 has nothing to turn off.

func Exec

func Exec(p Paths, pack []byte, binDir string) error

Exec prepares the bundle and configuration and replaces the current process with containerd, so systemd supervises containerd directly. pack is the embedded bundle; without one, binDir (development) must hold the binaries.

func IPv6Off

func IPv6Off(link string) (bool, error)

IPv6Off reports whether link has IPv6 turned off (or the kernel has none).

func InstalledPack

func InstalledPack(root string) string

InstalledPack returns the ID of the pack root/current points at ("dev" for development binaries, "" when none was installed yet).

func LogPath

func LogPath(dir, id string) (string, error)

LogPath returns the current log file of container id.

func Pack

func Pack(arch string, versions map[string]string, files map[string][]byte) ([]byte, error)

Pack builds a pack (gzipped tar, manifest first) from files, which maps bundle names to their contents.

func PackID

func PackID(pack []byte) string

PackID names a pack: the directory Install extracts it into.

func PruneLogs

func PruneLogs(dir string, retention time.Duration, maxBytes int64, now time.Time) error

PruneLogs removes history older than retention, then the oldest files until it holds at most maxBytes, and meta files of removed containers with no history left.

func ReadLogs

func ReadLogs(ctx context.Context, dir, id string, opts runtime.LogOptions) (runtime.LogStream, error)

ReadLogs returns a container's stored output, oldest first; Tail keeps only the last lines, Follow keeps reading new output until the stream is closed or ctx ends.

func RemoveLogs

func RemoveLogs(dir, id string) error

RemoveLogs moves a removed container's log files into history, oldest first, or deletes them when it keeps none (ADR 0043).

func SearchLogs

func SearchLogs(ctx context.Context, dir string, q runtime.LogQuery) ([]runtime.LogRecord, string, error)

SearchLogs searches the history and live logs of q.App's containers (ADR 0043): the newest q.Limit entries in the window, oldest first. Files are read newest first, so a search cut short by its budget keeps the latest output.

func TailLogs

func TailLogs(ctx context.Context, dir, target string, maxBytes int64, now time.Time) (runtime.LogTail, error)

TailLogs reads the output of app containers written since the last committed tail for target, at most about maxBytes (ADR 0044). Containers created before target was first used start at the end of their output. When a container's file is gone (pruned while the destination was unreachable), it goes on from the time of the last entry sent.

func UseBinDir

func UseBinDir(root, dir string) error

UseBinDir points root/current at binaries in dir instead of an extracted pack (development builds without the bundle tag).

func WriteLogMeta

func WriteLogMeta(dir, id string, m LogMeta) error

WriteLogMeta records whose container id is, so its output is kept in history when it rotates out or the container is removed.

func WriteLogs

func WriteLogs(dir, id string, stdout, stderr io.Reader) error

WriteLogs stores a container's output until both streams end, at most runtime.LogRate bytes per second (runtime.LogBurst at once); the rest is dropped. It is what `armadad runtime-log` runs inside the shim's logging process.

Types

type Artifact

type Artifact struct {
	Name    string
	Version string
	// URL has {arch} replaced by amd64 or arm64.
	URL    string
	SHA256 map[string]string // by arch
	// Files maps a path inside the downloaded gzipped tar to its name in the
	// bundle. An empty map means the download is the file itself, named
	// Name.
	Files map[string]string
}

Artifact is one upstream download that contributes files to the bundle.

When bumping a version: verify the upstream signature first (runc and tini publish GPG signatures; containerd and the CNI plugins publish checksums with the release), then record the SHA-256 here. The hash, not the URL, is what the bundle trusts.

func (Artifact) URLFor

func (a Artifact) URLFor(arch string) string

URLFor returns a's download URL for arch.

type LogMeta

type LogMeta struct {
	App       string    `json:"app"`
	Replica   string    `json:"replica"`
	Revision  string    `json:"revision,omitempty"`
	Container string    `json:"container,omitempty"`
	Created   time.Time `json:"created"`
}

LogMeta says which container a log history belongs to.

type Manifest

type Manifest struct {
	Arch     string            `json:"arch"`
	Versions map[string]string `json:"versions"`
	Files    map[string]string `json:"files"` // name -> sha256
}

Manifest describes a pack.

func Install

func Install(root string, pack []byte) (string, Manifest, error)

Install extracts pack under root (created 0700) unless an identical, intact copy is there already, points root/current at it, and returns the directory holding the binaries (always root/current/bin, a stable path that keeps working across upgrades). Every file is checked against the pack's manifest on every call.

type Paths

type Paths struct {
	DataDir string // Armada's data directory, e.g. /var/lib/armada
	RunDir  string // e.g. /run/armada
}

Paths locates everything the embedded runtime keeps on disk.

func (Paths) Bin

func (p Paths) Bin() string

Bin holds containerd, the shim, runc, tini, and cni/.

func (Paths) Bundle

func (p Paths) Bundle() string

Bundle is where packs are extracted; Bin is the stable binary path.

func (Paths) CNI

func (p Paths) CNI() string

CNI holds IPAM state and the plugin cache; on tmpfs because network namespaces do not survive a reboot either.

func (Paths) Config

func (p Paths) Config() string

Config is containerd's configuration file.

func (Paths) Containers

func (p Paths) Containers() string

Containers holds per-container files (resolv.conf, hosts, hostname).

func (Paths) FIFO

func (p Paths) FIFO() string

FIFO holds the pipes of exec'd processes.

func (Paths) Logs

func (p Paths) Logs() string

Logs holds container output.

func (Paths) NetNS

func (p Paths) NetNS() string

NetNS holds the containers' pinned network namespaces.

func (Paths) Root

func (p Paths) Root() string

Root is containerd's persistent root (images, snapshots, metadata).

func (Paths) Sandboxes

func (p Paths) Sandboxes() string

Sandboxes holds the pinned network namespaces of network sandboxes, one file named after each sandbox (ADR 0040).

func (Paths) Socket

func (p Paths) Socket() string

Socket is containerd's gRPC socket.

func (Paths) State

func (p Paths) State() string

State is containerd's runtime state.

Directories

Path Synopsis
Command mkbundle downloads the artifacts pinned in embedded.Lock, checks their SHA-256, and writes the runtime pack that release builds embed.
Command mkbundle downloads the artifacts pinned in embedded.Lock, checks their SHA-256, and writes the runtime pack that release builds embed.

Jump to

Keyboard shortcuts

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