runtime

package
v0.1.0-alpha.1.1 Latest Latest
Warning

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

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

Documentation

Overview

Package runtime wraps the containerd client and nerdctl libraries.

All container operations performed by nerdui go through this package so that containers created from the UI stay fully compatible with the nerdctl CLI.

Index

Constants

View Source 
const (
	// DefaultAddress is the default containerd socket path.
	DefaultAddress = "/run/containerd/containerd.sock"
	// DefaultNamespace is the default containerd namespace used by nerdctl.
	DefaultNamespace = "default"
)
View Source 
const (
	StateCreated    = "created"
	StateRunning    = "running"
	StatePaused     = "paused"
	StateRestarting = "restarting"
	StateExited     = "exited"
	StateUnknown    = "unknown"
)

Container states (API).

View Source 
const (
	PluginOK    = "ok"
	PluginSkip  = "skip"
	PluginError = "error"
)

Plugin statuses.

Variables

View Source 
var Actions = []Action{ActionStart, ActionStop, ActionRestart, ActionKill, ActionPause, ActionUnpause, ActionRemove}

Actions lists all container actions.

View Source 
var ErrNotConnected error = notConnected{}

ErrNotConnected is returned when containerd cannot be reached. It satisfies errdefs.IsUnavailable, so the API maps it to 503 (ADR-0006).

Functions

func ActionContext 

func ActionContext(ctx context.Context) (context.Context, context.CancelFunc)

ActionContext detaches an action from the HTTP request: a closed browser tab must not abort a stop or remove halfway. The action is still bounded by actionTimeout.

func ContainerName 

func ContainerName(lbls map[string]string) string

ContainerName returns the nerdctl container name stored in labels.

func ContainerdSupported 

func ContainerdSupported(version string) bool

ContainerdSupported reports whether this build supports a containerd version (e.g. "v2.3.7").

func LoadNerdctlConfig 

func LoadNerdctlConfig() (*config.Config, string, error)

LoadNerdctlConfig reads nerdctl.toml exactly like the nerdctl CLI does ($NERDCTL_TOML or the platform default, e.g. /etc/nerdctl/nerdctl.toml) so nerdui uses the same data root and CNI paths as the CLI. A missing file yields nerdctl's defaults.

func NerdctlLibraryVersion 

func NerdctlLibraryVersion() string

NerdctlLibraryVersion returns the version of the nerdctl module linked into the binary.

func SupportedContainerdMinors 

func SupportedContainerdMinors() []string

SupportedContainerdMinors returns the containerd minors supported by this build.

Types

type Action 

type Action string

Action is a container lifecycle operation (#11, #12). 

const (
	ActionStart   Action = "start"
	ActionStop    Action = "stop"
	ActionRestart Action = "restart"
	ActionKill    Action = "kill"
	ActionPause   Action = "pause"
	ActionUnpause Action = "unpause"
	ActionRemove  Action = "remove"
)

Container actions.

func (Action) Valid 

func (a Action) Valid() bool

Valid reports whether a is a known action.

type ActionOptions 

type ActionOptions struct {
	// Force removes a running or paused container (killing it first).
	Force bool
	// Volumes also removes anonymous volumes of the container.
	Volumes bool
}

ActionOptions tune an action. Force and Volumes apply to remove only.

type CNIInfo 

type CNIInfo struct {
	Path    string   `json:"path"`
	NetConf string   `json:"netConfPath"`
	Version string   `json:"version,omitempty"`
	Plugins []string `json:"plugins"`
	Error   string   `json:"error,omitempty"`
}

CNIInfo describes the CNI plugins nerdctl uses for container networks.

type Client 

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

Client is a lazily connected containerd client.

func New 

func New(address, namespace string, opts ...Option) *Client

New creates a client. The connection is established on first use, so nerdui can start even when containerd is temporarily unavailable.

func (*Client) Address 

func (c *Client) Address() string

Address returns the containerd socket address.

func (*Client) Close 

func (c *Client) Close() error

Close closes the underlying connection, if any.

func (*Client) Containers 

func (c *Client) Containers() Containers

Containers returns container operations of the local containerd.

func (*Client) Events 

func (c *Client) Events() EventSource

Events returns the event source of the local containerd.

func (*Client) Info 

func (c *Client) Info(ctx context.Context) (Info, error)

Info collects host and runtime information like `nerdctl info` and `nerdctl version`, plus the containerd plugin list (`ctr plugins ls`) and CNI plugin versions.

func (*Client) Namespace 

func (c *Client) Namespace() string

Namespace returns the default containerd namespace.

func (*Client) Namespaces 

func (c *Client) Namespaces(ctx context.Context) ([]string, error)

Namespaces lists containerd namespaces in sorted order.

func (*Client) Nerdctl 

func (c *Client) Nerdctl(ctx context.Context) NerdctlStatus

Nerdctl reports the host nerdctl binary and whether mutations are allowed (ADR-0011).

func (*Client) System 

func (c *Client) System() System

System returns system-level operations (versions, namespaces).

func (*Client) Versions 

func (c *Client) Versions(ctx context.Context) (Versions, error)

Versions returns containerd server and nerdctl library versions.

type Component 

type Component struct {
	Name    string `json:"name"`
	Version string `json:"version,omitempty"`
	Commit  string `json:"commit,omitempty"`
	// Error explains why the version is unknown (binary missing, unexpected output).
	Error string `json:"error,omitempty"`
}

Component is the version of a runtime component (containerd, runc, buildctl).

type ComposeRef 

type ComposeRef struct {
	Project string `json:"project"`
	Service string `json:"service,omitempty"`
}

ComposeRef links a container to its compose project and service.

type Container 

type Container struct {
	ID        string `json:"id"`
	Name      string `json:"name"`
	Namespace string `json:"namespace"`
	Image     string `json:"image"`
	Command   string `json:"command"`
	// State is one of created, running, paused, restarting, exited, unknown.
	State string `json:"state"`
	// Health is healthy, unhealthy or starting when a healthcheck is configured.
	Health    string     `json:"health,omitempty"`
	ExitCode  *int       `json:"exitCode,omitempty"`
	ExitedAt  *time.Time `json:"exitedAt,omitempty"`
	StartedAt *time.Time `json:"startedAt,omitempty"`
	CreatedAt time.Time  `json:"createdAt"`
	Ports     []Port     `json:"ports"`
	// Compose is set for containers that belong to a compose project (ADR-0008).
	Compose  *ComposeRef       `json:"compose,omitempty"`
	Platform string            `json:"platform,omitempty"`
	Runtime  string            `json:"runtime,omitempty"`
	Labels   map[string]string `json:"labels"`
}

Container is the list representation of a container. Keep in sync with api/openapi.yaml.

type Containers 

type Containers interface {
	// List returns all containers of a namespace (any state), newest first.
	List(ctx context.Context, namespace string) ([]Container, error)
	// Do performs a lifecycle action on the container with the exact id (#11, #12).
	Do(ctx context.Context, namespace, id string, action Action, opts ActionOptions) error
	// Inspect returns the container as `nerdctl inspect` shows it (#13).
	Inspect(ctx context.Context, namespace, ref string, size bool) (any, error)
	// Logs passes the log lines of the container with the exact id to emit (#14).
	Logs(ctx context.Context, namespace, id string, opts LogOptions, emit LogEmitter) error
}

Containers covers container operations of an environment.

type Deprecation 

type Deprecation struct {
	ID             string    `json:"id"`
	Message        string    `json:"message"`
	LastOccurrence time.Time `json:"lastOccurrence,omitzero"`
}

Deprecation is a containerd warning about a deprecated feature in use.

type Event 

type Event struct {
	Timestamp time.Time `json:"ts"`
	Namespace string    `json:"namespace,omitempty"`
	// Topic is the containerd topic, e.g. "/containers/create" or "/tasks/exit".
	Topic string `json:"topic"`
	// Kind and Action are derived from the topic: "container"/"create", "task"/"exit".
	Kind   string `json:"kind"`
	Action string `json:"action"`
	// ID is the container ID for container and task events, the name for image and
	// namespace events.
	ID         string            `json:"id,omitempty"`
	Attributes map[string]string `json:"attributes,omitempty"`
}

Event is a containerd event in the API representation (ADR-0007). Keep in sync with api/openapi.yaml.

type EventSource 

type EventSource interface {
	// Subscribe verifies the connection and starts a subscription. A non-nil error means
	// the subscription could not be established. Otherwise events are delivered until ctx
	// ends or the connection breaks; the error channel then receives the reason and both
	// channels are closed.
	Subscribe(ctx context.Context) (<-chan Event, <-chan error, error)
}

EventSource streams events of an environment.

type Features 

type Features struct {
	MemoryLimit    bool `json:"memoryLimit"`
	SwapLimit      bool `json:"swapLimit"`
	CPUCfsPeriod   bool `json:"cpuCfsPeriod"`
	CPUCfsQuota    bool `json:"cpuCfsQuota"`
	CPUShares      bool `json:"cpuShares"`
	CPUSet         bool `json:"cpuSet"`
	PidsLimit      bool `json:"pidsLimit"`
	OomKillDisable bool `json:"oomKillDisable"`
	IPv4Forwarding bool `json:"ipv4Forwarding"`
}

Features are the resource limits and kernel settings available to containers.

type Info 

type Info struct {
	// ID is the containerd server UUID.
	ID              string `json:"id"`
	Hostname        string `json:"hostname"`
	OperatingSystem string `json:"operatingSystem"`
	OSType          string `json:"osType"`
	Architecture    string `json:"architecture"`
	KernelVersion   string `json:"kernelVersion"`
	CPUs            int    `json:"cpus"`
	MemoryBytes     int64  `json:"memoryBytes"`
	CgroupDriver    string `json:"cgroupDriver"`
	CgroupVersion   string `json:"cgroupVersion"`
	Rootless        bool   `json:"rootless"`
	// Snapshotter is nerdctl's default snapshotter; Snapshotters are those containerd loaded.
	Snapshotter     string   `json:"snapshotter"`
	Snapshotters    []string `json:"snapshotters"`
	LogDrivers      []string `json:"logDrivers"`
	SecurityOptions []string `json:"securityOptions"`
	// Features are the cgroup and kernel capabilities reported by `nerdctl info`.
	Features   Features    `json:"features"`
	Components []Component `json:"components"`
	CNI        CNIInfo     `json:"cni"`
	// Warnings are `nerdctl info` warnings (missing limits, IP forwarding…).
	Warnings     []string      `json:"warnings"`
	Deprecations []Deprecation `json:"deprecations"`
	Plugins      []Plugin      `json:"plugins"`
}

Info describes the host and the container runtime of an environment (#66, ADR-0015). Host fields come from the machine nerdui runs on, which is the containerd host.

type LogEmitter 

type LogEmitter func(LogLine) error

LogEmitter receives log lines in order; an error stops reading.

type LogLine 

type LogLine struct {
	// Stream is "stdout" or "stderr".
	Stream string `json:"stream"`
	// Time is when the line was logged; zero when the log driver does not record it
	// (journald).
	Time time.Time `json:"ts,omitzero"`
	// Line is the text without the trailing newline, ANSI sequences preserved.
	Line string `json:"line"`
}

LogLine is one log entry.

type LogOptions 

type LogOptions struct {
	// Follow keeps streaming new entries while the container runs.
	Follow bool
	// Tail limits the output to the last n entries (0 = all).
	Tail uint
	// Since and Until bound the entries by time: RFC 3339 or relative ("10m").
	Since, Until string
}

LogOptions select the log entries, like `nerdctl logs`.

type NerdctlStatus 

type NerdctlStatus struct {
	// Path is the configured binary (--nerdctl-path).
	Path string `json:"path"`
	// Version is the host binary's version, empty when it could not be determined.
	Version string `json:"version,omitempty"`
	// Required is the major.minor that must match, e.g. "2.4" (the linked packages).
	Required string `json:"required"`
	// Compatible is true when major.minor of Version equals Required.
	Compatible bool `json:"compatible"`
	// CheckSkipped is true with --skip-nerdctl-version-check (unsupported configuration).
	CheckSkipped bool `json:"checkSkipped,omitempty"`
	// Error explains why the binary is missing or its version unknown.
	Error string `json:"error,omitempty"`
}

NerdctlStatus is the result of the nerdctl compatibility check (ADR-0011).

func (NerdctlStatus) Writable 

func (s NerdctlStatus) Writable() bool

Writable reports whether mutating operations are allowed.

type Option 

type Option func(*Client)

Option configures a Client.

func WithNerdctl 

func WithNerdctl(path string, skipVersionCheck bool) Option

WithNerdctl sets the host nerdctl binary and whether its version check is skipped (ADR-0003, ADR-0011).

func WithNerdctlConfig 

func WithNerdctlConfig(cfg *config.Config) Option

WithNerdctlConfig sets nerdctl's configuration (see LoadNerdctlConfig), so data_root, CNI paths and other settings match the nerdctl CLI on the host.

type Plugin 

type Plugin struct {
	Type         string   `json:"type"`
	ID           string   `json:"id"`
	Platforms    []string `json:"platforms,omitempty"`
	Capabilities []string `json:"capabilities,omitempty"`
	// Status is ok, skip (not applicable to this host) or error.
	Status string `json:"status"`
	Error  string `json:"error,omitempty"`
}

Plugin is a containerd plugin as `ctr plugins ls` shows it.

type Port 

type Port struct {
	HostIP        string `json:"hostIp,omitempty"`
	HostPort      int32  `json:"hostPort"`
	ContainerPort int32  `json:"containerPort"`
	Protocol      string `json:"protocol"`
}

Port is a published port.

type Runtime 

type Runtime interface {
	System() System
	Containers() Containers
	Events() EventSource
	Close() error
}

Runtime is everything nerdui can do with one environment (ADR-0006). It is split into small interfaces so handlers depend only on what they use and can be tested with fakes. The local implementation is *Client; a remote agent implements the same interface in v2.

New capabilities (Containers, Images, Volumes, Networks, Stacks, Events) are added here together with the features that need them.

type System 

type System interface {
	// Versions reports containerd and nerdctl versions.
	Versions(ctx context.Context) (Versions, error)
	// Namespaces lists containerd namespaces.
	Namespaces(ctx context.Context) ([]string, error)
	// Nerdctl reports the nerdctl compatibility check; mutations require Writable().
	Nerdctl(ctx context.Context) NerdctlStatus
	// Info describes the host, runtime components and containerd plugins (#66).
	Info(ctx context.Context) (Info, error)
}

System covers host-level information of an environment.

type Versions 

type Versions struct {
	Containerd         string `json:"containerd"`
	ContainerdRevision string `json:"containerdRevision"`
	// ContainerdSupported is false for versions outside SupportedContainerdMinors (ADR-0012).
	ContainerdSupported bool `json:"containerdSupported"`
	// SupportedContainerd are the containerd minors this build supports (ADR-0017).
	SupportedContainerd []string      `json:"supportedContainerd"`
	NerdctlLibrary      string        `json:"nerdctlLibrary"`
	Nerdctl             NerdctlStatus `json:"nerdctl"`
}

Versions describes the versions of the underlying runtime components.

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.