container

package
v0.0.8 Latest Latest
Warning

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

 Go to latest Published: Feb 3, 2026 License: EUPL-1.2 Imports: 18 Imported by: 0

Documentation

Overview

Package container provides a runtime for managing LinuxKit containers. It supports running LinuxKit images (ISO, qcow2, vmdk, raw) using available hypervisors (QEMU on Linux, Hyperkit on macOS).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ApplyTemplate 

func ApplyTemplate(name string, vars map[string]string) (string, error)

ApplyTemplate applies variable substitution to a template. It supports two syntaxes:

  • ${VAR} - required variable, returns error if not provided
  • ${VAR:-default} - variable with default value

func ApplyVariables 

func ApplyVariables(content string, vars map[string]string) (string, error)

ApplyVariables applies variable substitution to content string. It supports two syntaxes:

  • ${VAR} - required variable, returns error if not provided
  • ${VAR:-default} - variable with default value

func DefaultLogsDir 

func DefaultLogsDir() (string, error)

DefaultLogsDir returns the default directory for container logs.

func DefaultStateDir 

func DefaultStateDir() (string, error)

DefaultStateDir returns the default directory for state files (~/.core).

func DefaultStatePath 

func DefaultStatePath() (string, error)

DefaultStatePath returns the default path for the state file.

func EnsureLogsDir 

func EnsureLogsDir() error

EnsureLogsDir ensures the logs directory exists.

func ExtractVariables 

func ExtractVariables(content string) (required []string, optional map[string]string)

ExtractVariables extracts all variable names from a template. Returns two slices: required variables and optional variables (with defaults).

func GenerateID 

func GenerateID() (string, error)

GenerateID creates a new unique container ID (8 hex characters).

func GetTemplate 

func GetTemplate(name string) (string, error)

GetTemplate returns the content of a template by name. It first checks embedded templates, then user templates.

func LogPath 

func LogPath(id string) (string, error)

LogPath returns the log file path for a given container ID.

Types

type Container 

type Container struct {
	// ID is a unique identifier for the container (8 character hex string).
	ID string `json:"id"`
	// Name is the optional human-readable name for the container.
	Name string `json:"name,omitempty"`
	// Image is the path to the LinuxKit image being run.
	Image string `json:"image"`
	// Status represents the current state of the container.
	Status Status `json:"status"`
	// PID is the process ID of the hypervisor running this container.
	PID int `json:"pid"`
	// StartedAt is when the container was started.
	StartedAt time.Time `json:"started_at"`
	// Ports maps host ports to container ports.
	Ports map[int]int `json:"ports,omitempty"`
	// Memory is the amount of memory allocated in MB.
	Memory int `json:"memory,omitempty"`
	// CPUs is the number of CPUs allocated.
	CPUs int `json:"cpus,omitempty"`
}

Container represents a running LinuxKit container/VM instance.

type HyperkitHypervisor 

type HyperkitHypervisor struct {
	// Binary is the path to the hyperkit binary.
	Binary string
}

HyperkitHypervisor implements Hypervisor for macOS Hyperkit.

func NewHyperkitHypervisor 

func NewHyperkitHypervisor() *HyperkitHypervisor

NewHyperkitHypervisor creates a new Hyperkit hypervisor instance.

func (*HyperkitHypervisor) Available 

func (h *HyperkitHypervisor) Available() bool

Available checks if Hyperkit is installed and accessible.

func (*HyperkitHypervisor) BuildCommand 

func (h *HyperkitHypervisor) BuildCommand(ctx context.Context, image string, opts *HypervisorOptions) (*exec.Cmd, error)

BuildCommand creates the Hyperkit command for running a VM.

func (*HyperkitHypervisor) Name 

func (h *HyperkitHypervisor) Name() string

Name returns the hypervisor name.

type Hypervisor 

type Hypervisor interface {
	// Name returns the name of the hypervisor.
	Name() string
	// Available checks if the hypervisor is available on the system.
	Available() bool
	// BuildCommand builds the command to run a VM with the given options.
	BuildCommand(ctx context.Context, image string, opts *HypervisorOptions) (*exec.Cmd, error)
}

Hypervisor defines the interface for VM hypervisors.

func DetectHypervisor 

func DetectHypervisor() (Hypervisor, error)

DetectHypervisor returns the best available hypervisor for the current platform.

func GetHypervisor 

func GetHypervisor(name string) (Hypervisor, error)

GetHypervisor returns a specific hypervisor by name.

type HypervisorOptions 

type HypervisorOptions struct {
	// Memory in MB.
	Memory int
	// CPUs count.
	CPUs int
	// LogFile path for output.
	LogFile string
	// SSHPort for SSH access.
	SSHPort int
	// Ports maps host ports to guest ports.
	Ports map[int]int
	// Volumes maps host paths to guest paths (9p shares).
	Volumes map[string]string
	// Detach runs in background (nographic mode).
	Detach bool
}

HypervisorOptions contains options for running a VM.

type ImageFormat 

type ImageFormat string

ImageFormat represents the format of a LinuxKit image. 

const (
	// FormatISO is an ISO image format.
	FormatISO ImageFormat = "iso"
	// FormatQCOW2 is a QEMU Copy-On-Write image format.
	FormatQCOW2 ImageFormat = "qcow2"
	// FormatVMDK is a VMware disk image format.
	FormatVMDK ImageFormat = "vmdk"
	// FormatRaw is a raw disk image format.
	FormatRaw ImageFormat = "raw"
	// FormatUnknown indicates an unknown image format.
	FormatUnknown ImageFormat = "unknown"
)

func DetectImageFormat 

func DetectImageFormat(path string) ImageFormat

DetectImageFormat determines the image format from its file extension.

type LinuxKitManager 

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

LinuxKitManager implements the Manager interface for LinuxKit VMs.

func NewLinuxKitManager 

func NewLinuxKitManager() (*LinuxKitManager, error)

NewLinuxKitManager creates a new LinuxKit manager with auto-detected hypervisor.

func NewLinuxKitManagerWithHypervisor 

func NewLinuxKitManagerWithHypervisor(state *State, hypervisor Hypervisor) *LinuxKitManager

NewLinuxKitManagerWithHypervisor creates a manager with a specific hypervisor.

func (*LinuxKitManager) Exec 

func (m *LinuxKitManager) Exec(ctx context.Context, id string, cmd []string) error

Exec executes a command inside the container via SSH.

func (*LinuxKitManager) Hypervisor 

func (m *LinuxKitManager) Hypervisor() Hypervisor

Hypervisor returns the manager's hypervisor (for testing).

func (*LinuxKitManager) List 

func (m *LinuxKitManager) List(ctx context.Context) ([]*Container, error)

List returns all known containers, verifying process state.

func (*LinuxKitManager) Logs 

func (m *LinuxKitManager) Logs(ctx context.Context, id string, follow bool) (goio.ReadCloser, error)

Logs returns a reader for the container's log output.

func (*LinuxKitManager) Run 

func (m *LinuxKitManager) Run(ctx context.Context, image string, opts RunOptions) (*Container, error)

Run starts a new LinuxKit VM from the given image.

func (*LinuxKitManager) State 

func (m *LinuxKitManager) State() *State

State returns the manager's state (for testing).

func (*LinuxKitManager) Stop 

func (m *LinuxKitManager) Stop(ctx context.Context, id string) error

Stop stops a running container by sending SIGTERM.

type Manager 

type Manager interface {
	// Run starts a new container from the given image.
	Run(ctx context.Context, image string, opts RunOptions) (*Container, error)
	// Stop stops a running container by ID.
	Stop(ctx context.Context, id string) error
	// List returns all known containers.
	List(ctx context.Context) ([]*Container, error)
	// Logs returns a reader for the container's log output.
	// If follow is true, the reader will continue to stream new log entries.
	Logs(ctx context.Context, id string, follow bool) (io.ReadCloser, error)
	// Exec executes a command inside the container via SSH.
	Exec(ctx context.Context, id string, cmd []string) error
}

Manager defines the interface for container lifecycle management.

type QemuHypervisor 

type QemuHypervisor struct {
	// Binary is the path to the qemu binary (defaults to qemu-system-x86_64).
	Binary string
}

QemuHypervisor implements Hypervisor for QEMU.

func NewQemuHypervisor 

func NewQemuHypervisor() *QemuHypervisor

NewQemuHypervisor creates a new QEMU hypervisor instance.

func (*QemuHypervisor) Available 

func (q *QemuHypervisor) Available() bool

Available checks if QEMU is installed and accessible.

func (*QemuHypervisor) BuildCommand 

func (q *QemuHypervisor) BuildCommand(ctx context.Context, image string, opts *HypervisorOptions) (*exec.Cmd, error)

BuildCommand creates the QEMU command for running a VM.

func (*QemuHypervisor) Name 

func (q *QemuHypervisor) Name() string

Name returns the hypervisor name.

type RunOptions 

type RunOptions struct {
	// Name is an optional human-readable name for the container.
	Name string
	// Detach runs the container in the background.
	Detach bool
	// Memory is the amount of memory to allocate in MB (default: 1024).
	Memory int
	// CPUs is the number of CPUs to allocate (default: 1).
	CPUs int
	// Ports maps host ports to container ports.
	Ports map[int]int
	// Volumes maps host paths to container paths.
	Volumes map[string]string
	// SSHPort is the port to use for SSH access (default: 2222).
	SSHPort int
	// SSHKey is the path to the SSH private key for exec commands.
	SSHKey string
}

RunOptions configures how a container should be run.

type State 

type State struct {
	// Containers is a map of container ID to Container.
	Containers map[string]*Container `json:"containers"`
	// contains filtered or unexported fields
}

State manages persistent container state.

func LoadState 

func LoadState(filePath string) (*State, error)

LoadState loads the state from the given file path. If the file doesn't exist, returns an empty state.

func NewState 

func NewState(filePath string) *State

NewState creates a new State instance.

func (*State) Add 

func (s *State) Add(c *Container) error

Add adds a container to the state and persists it.

func (*State) All 

func (s *State) All() []*Container

All returns copies of all containers in the state. Returns copies to prevent data races when containers are modified.

func (*State) FilePath 

func (s *State) FilePath() string

FilePath returns the path to the state file.

func (*State) Get 

func (s *State) Get(id string) (*Container, bool)

Get retrieves a copy of a container by ID. Returns a copy to prevent data races when the container is modified.

func (*State) Remove 

func (s *State) Remove(id string) error

Remove removes a container from the state and persists it.

func (*State) SaveState 

func (s *State) SaveState() error

SaveState persists the state to the configured file path.

func (*State) Update 

func (s *State) Update(c *Container) error

Update updates a container in the state and persists it.

type Status 

type Status string

Status represents the state of a container. 

const (
	// StatusRunning indicates the container is running.
	StatusRunning Status = "running"
	// StatusStopped indicates the container has stopped.
	StatusStopped Status = "stopped"
	// StatusError indicates the container encountered an error.
	StatusError Status = "error"
)

type Template 

type Template struct {
	// Name is the template identifier (e.g., "core-dev", "server-php").
	Name string
	// Description is a human-readable description of the template.
	Description string
	// Path is the file path to the template (relative or absolute).
	Path string
}

Template represents a LinuxKit YAML template.

func ListTemplates 

func ListTemplates() []Template

ListTemplates returns all available LinuxKit templates. It combines embedded templates with any templates found in the user's .core/linuxkit directory.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.