container

Documentation

Index

• Constants
• func GenerateBaseInitramfs(ctx context.Context, arch apko_types.Architecture, cfg MicrovmConfig, ...) error
• func LogObservabilityEvents(ctx context.Context, events *ObservabilityEvents)
• type BindMount
• type Capabilities
• type Config
• type Debugger
• type Loader
• type MicrovmConfig
  • func DefaultMicrovmConfig() MicrovmConfig
• type NetworkConnection
• type ObservabilityEvents
  • func RetrieveObservabilityEvents(ctx context.Context, cfg *Config) (*ObservabilityEvents, error)
• type Runner
  • func BubblewrapRunner(remove bool) Runner
  • func QemuRunner() Runner

Constants

const (
	// DefaultWorkspaceDir is the default path to the workspace directory in the runner's environment.
	DefaultWorkspaceDir = "/home/build"
	// DefaultCacheDir is the default path to the cache directory in the runner's environment.
	DefaultCacheDir = "/var/cache/melange"
	// DefaultResolvConfPath is the default path to the resolv.conf file in the runner's environment.
	DefaultResolvConfPath = "/etc/resolv.conf"
)

const (
	KB = 1 << (10 * iota)
	MB
	GB
	TB
)

Use binary values for all units

const (
	BubblewrapName = "bubblewrap"
)

const QemuName = "qemu"

Functions

func GenerateBaseInitramfs

func GenerateBaseInitramfs(ctx context.Context, arch apko_types.Architecture, cfg MicrovmConfig, outputPath string) error

GenerateBaseInitramfs generates a base initramfs suitable for the QEMU runner. This can be reused via QEMU_BASE_INITRAMFS, but is cached if not.

The generated initramfs does NOT contain SSH host keys or kernel modules, those are injected at runtime by the QEMU runner.

func LogObservabilityEvents

func LogObservabilityEvents(ctx context.Context, events *ObservabilityEvents)

LogObservabilityEvents writes all observability events to melange's stdout via the structured logger. Each raw event is logged as a separate line with an [OBSERVABILITY] prefix for filtering. Network connections get a dedicated summary section. In the elastic build environment, these log lines flow to Cloud Logging via GKE pod stdout and are individually searchable.

Types

type BindMount

type BindMount struct {
	Source      string
	Destination string
}

type Capabilities

type Capabilities struct {
	Networking bool
	Add        []string // List of kernel capabilities to add to the container.
	Drop       []string // List of kernel capabilities to drop from the container.
}

type Config

type Config struct {
	PackageName              string
	Mounts                   []BindMount
	Capabilities             Capabilities
	Environment              map[string]string
	ImgRef                   string
	PodID                    string
	Arch                     apko_types.Architecture
	RunAsUID                 string
	RunAs                    string
	WorkspaceDir             string
	CacheDir                 string
	CPU, CPUModel, Memory    string
	SSHKey                   ssh.Signer
	SSHAddress               string             // SSH address for the build / chrooted environment
	SSHControlAddress        string             // SSH address for the control / management environment
	SSHHostKey               string             // Path to known_hosts file containing the VM's host key
	VMHostKeySigner          ssh.Signer         // VM's SSH host key (private signer)
	VMHostKeyPublic          ssh.PublicKey      // VM's SSH host key (public) - for verification
	VMHostKeyPrivateKeyBytes []byte             // VM's SSH host key (raw private key bytes) - for injection
	VMHostKeyPrivate         ed25519.PrivateKey // VM's SSH host key (raw private key) - for explicit zeroing
	InitramfsPath            string             // Path to temp initramfs file (contains sensitive key material)
	Disk                     string
	Timeout                  time.Duration
	SSHBuildClient           *ssh.Client // SSH client for the build environment, may not have privileges
	SSHControlBuildClient    *ssh.Client // SSH client for control operations in the build environment, has privileges
	SSHControlClient         *ssh.Client // SSH client for unrestricted control environment, has privileges
	QemuProcess              *os.Process // QEMU process handle (not just PID, to avoid PID reuse issues)
	RunAsGID                 string

	// Virtiofs-related fields for cache directory
	VirtiofsEnabled     bool   // Whether virtiofs is enabled for cache
	VirtiofsdPID        int    // PID of virtiofsd daemon for cleanup
	VirtiofsdSocketPath string // Path to Unix socket for virtiofsd

	// ObservabilityHook is true when the observability hook's sentinel file
	// was found in the initramfs CPIO during VM setup. When false,
	// RetrieveObservabilityEvents returns immediately without probing the VM.
	ObservabilityHook bool
}

type Debugger

type Debugger interface {
	Debug(ctx context.Context, cfg *Config, envOverride map[string]string, cmd ...string) error
}

type Loader

type Loader interface {
	LoadImage(ctx context.Context, layer v1.Layer, arch apko_types.Architecture, bc *apko_build.Context) (ref string, err error)
	RemoveImage(ctx context.Context, ref string) error
}

type MicrovmConfig

type MicrovmConfig struct {
	Package            string   // Main init package (default: "microvm-init")
	Repositories       []string // APK repositories
	AdditionalPackages []string // Extra packages to include
	ExtraKeys          []string // Extra keys for APK signature verification
}

MicrovmConfig configures how the microvm initramfs is built. This is used by both the QEMU runner's auto-generation and the `melange build-qemu-initramfs` command.

func DefaultMicrovmConfig

func DefaultMicrovmConfig() MicrovmConfig

DefaultMicrovmConfig returns the default microvm configuration. This uses the "microvm-init" package from the Chainguard APK repository.

type NetworkConnection

type NetworkConnection struct {
	Process   string `json:"process"`
	Protocol  string `json:"protocol"`
	SrcAddr   string `json:"src_addr"`
	SrcPort   uint32 `json:"src_port"`
	DstAddr   string `json:"dst_addr"`
	DstPort   uint32 `json:"dst_port"`
	Family    string `json:"family"`
	Function  string `json:"function"` // tcp_connect, tcp_close, etc.
	Timestamp string `json:"timestamp"`
}

NetworkConnection represents a single observed network connection.

type ObservabilityEvents

type ObservabilityEvents struct {
	// RawData is the raw NDJSON event data.
	RawData []byte

	// EventCount is the total number of events.
	EventCount int

	// NetworkConnections is the list of network connections observed.
	NetworkConnections []NetworkConnection
}

ObservabilityEvents holds parsed event data retrieved from the build VM.

func RetrieveObservabilityEvents

func RetrieveObservabilityEvents(ctx context.Context, cfg *Config) (*ObservabilityEvents, error)

RetrieveObservabilityEvents fetches observability events from the build VM via the SSHControlClient (port 2223, unchrooted root access). This should be called after the build completes but before TerminatePod.

If cfg.ObservabilityHook is false the function returns immediately without probing the VM. If true, a missing events file is treated as an error.

type Runner

type Runner interface {
	Close() error
	Name() string
	TestUsability(ctx context.Context) bool
	// OCIImageLoader returns a Loader that will load an OCI image from a stream.
	// It should return the Loader, which will be used to load the provided image
	// as a tar stream into the Loader. That image will be used as the root when StartPod() the container.
	OCIImageLoader() Loader
	StartPod(ctx context.Context, cfg *Config) error
	Run(ctx context.Context, cfg *Config, envOverride map[string]string, cmd ...string) error
	TerminatePod(ctx context.Context, cfg *Config) error
	// TempDir returns the base for temporary directory, or "" if whatever is provided by the system is fine
	TempDir() string
	// WorkspaceTar returns an io.ReadCloser that can be used to read the status of the workspace.
	// The io.ReadCloser itself is a tar stream, which can be written to an io.Writer as is,
	// or passed to an fs.FS processor
	WorkspaceTar(ctx context.Context, cfg *Config, extraFiles []string) (io.ReadCloser, error)
	// GetReleaseData returns the release data for the container's OS (os-release)
	GetReleaseData(ctx context.Context, cfg *Config) (*apko_build.ReleaseData, error)
}

func BubblewrapRunner

func BubblewrapRunner(remove bool) Runner

BubblewrapRunner returns a Bubblewrap Runner implementation.

func QemuRunner

func QemuRunner() Runner

QemuRunner returns a Qemu Runner implementation.