container

package
v0.16.4 Latest Latest
Warning

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

 Go to latest Published: May 10, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// MaxContainerNameLength is the maximum allowed length for container names
	// This follows DNS label standards (RFC 1035)
	MaxContainerNameLength = 63

	// SystemContainerPrefix is the reserved prefix for system containers
	SystemContainerPrefix = "_"
)

Variables

View Source 
var (

	// ErrReservedPrefix is returned when container name starts with underscore
	ErrReservedPrefix = fmt.Errorf("container names starting with '_' are reserved for system use")

	// ErrInvalidFormat is returned when container name has invalid format
	ErrInvalidFormat = fmt.Errorf("container name must contain only lowercase letters, numbers, and hyphens")

	// ErrEmpty is returned when container name is empty
	ErrEmpty = fmt.Errorf("container name cannot be empty")

	// ErrTooLong is returned when container name exceeds maximum length
	ErrTooLong = fmt.Errorf("container name cannot exceed 63 characters")
)

Functions

func CreateJumpServerAccount 

func CreateJumpServerAccount(username string, sshPublicKey string, verbose bool) error

CreateJumpServerAccount creates a proxy-only user account on the jump server The account is configured with /usr/sbin/nologin shell, preventing direct shell access while still allowing SSH ProxyJump to work for accessing containers.

func DeleteJumpServerAccount 

func DeleteJumpServerAccount(username string, verbose bool) error

DeleteJumpServerAccount removes a user account from the jump server

func EnsureJumpServerAccount added in v0.16.0 

func EnsureJumpServerAccount(username string) error

EnsureJumpServerAccount creates a host-level user with containarium-shell as the login shell, enabling SSH access through sshpiper into the user's Incus container. This is called automatically when a container is created. It is idempotent — if the account already exists, it just ensures the shell and permissions are correct.

func ExtractSSHKeyFromContainer 

func ExtractSSHKeyFromContainer(containerName, username string, verbose bool) (string, error)

ExtractSSHKeyFromContainer extracts the SSH public key from inside a container The key is read from /home/{username}/.ssh/authorized_keys inside the container

func IsSystemContainer 

func IsSystemContainer(name string) bool

IsSystemContainer returns true if the container name is a system container (starts with underscore prefix).

func UserExists 

func UserExists(username string) bool

UserExists is the exported version of userExists for use by CLI commands

func ValidateContainerName 

func ValidateContainerName(name string) error

ValidateContainerName validates a container name according to Containarium rules.

Rules: 1. Cannot start with underscore (_) - reserved for system containers 2. Must contain only lowercase letters, numbers, and hyphens 3. Cannot be empty 4. Cannot exceed 63 characters (DNS label limit)

Examples:

  • Valid: "alice", "bob-dev", "team-api-prod"
  • Invalid: "_containarium-core", "Alice", "my_app", ""

func ValidateSSHPublicKey added in v0.16.0 

func ValidateSSHPublicKey(key string) error

ValidateSSHPublicKey verifies that the given string is a well-formed SSH public key (in OpenSSH authorized_keys format). Rejects obvious placeholder strings and keys with malformed base64 payloads.

func ValidateSystemContainerName 

func ValidateSystemContainerName(name string) error

ValidateSystemContainerName validates a system container name. System containers MUST start with underscore prefix.

func ValidateUserContainerName 

func ValidateUserContainerName(name string) error

ValidateUserContainerName validates a user-provided container name. This is an alias for ValidateContainerName with clearer naming.

Types

type CollaboratorManager 

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

CollaboratorManager handles collaborator operations for containers

func NewCollaboratorManager 

func NewCollaboratorManager(manager *Manager, store *collaborator.Store) *CollaboratorManager

NewCollaboratorManager creates a new collaborator manager

func (*CollaboratorManager) AddCollaborator 

func (cm *CollaboratorManager) AddCollaborator(ownerUsername, collaboratorUsername, sshPublicKey string, grantSudo, grantContainerRuntime bool) (*collaborator.Collaborator, error)

AddCollaborator adds a collaborator to a container This creates: 1. A user in the container with the name {container-name}-{collaborator-username} 2. Sudoers configuration allowing passwordless sudo su to the container owner 3. Session logging for audit trail 4. Jump server account for SSH ProxyJump access 5. Persistence record in PostgreSQL

func (*CollaboratorManager) GenerateSSHCommand 

func (cm *CollaboratorManager) GenerateSSHCommand(ownerUsername, collaboratorUsername, jumpServerHost string) string

GenerateSSHCommand generates the SSH command for a collaborator

func (*CollaboratorManager) GetCollaborator 

func (cm *CollaboratorManager) GetCollaborator(ownerUsername, collaboratorUsername string) (*collaborator.Collaborator, error)

GetCollaborator returns a specific collaborator

func (*CollaboratorManager) GetStore 

func (cm *CollaboratorManager) GetStore() *collaborator.Store

GetStore returns the collaborator store (for server handlers)

func (*CollaboratorManager) ListCollaborators 

func (cm *CollaboratorManager) ListCollaborators(ownerUsername string) ([]*collaborator.Collaborator, error)

ListCollaborators returns all collaborators for a container

func (*CollaboratorManager) RemoveAllCollaborators 

func (cm *CollaboratorManager) RemoveAllCollaborators(ownerUsername string) error

RemoveAllCollaborators removes all collaborators for a container This is called when deleting a container

func (*CollaboratorManager) RemoveCollaborator 

func (cm *CollaboratorManager) RemoveCollaborator(ownerUsername, collaboratorUsername string) error

RemoveCollaborator removes a collaborator from a container

func (*CollaboratorManager) SyncCollaboratorAccounts 

func (cm *CollaboratorManager) SyncCollaboratorAccounts(verbose, force bool) (restored, skipped, failed int)

SyncCollaboratorAccounts recreates jump server accounts for all collaborators. When force is true, accounts are recreated even if they already exist.

type CreateOptions 

type CreateOptions struct {
	Username               string
	Image                  string
	CPU                    string
	Memory                 string
	Disk                   string // Disk size (e.g., "20GB")
	GPU                    string // GPU device ID for passthrough (e.g., "0", PCI address, or empty for none)
	StaticIP               string // Static IP address (e.g., "10.100.0.100") - empty for DHCP
	SSHKeys                []string
	Labels                 map[string]string // Kubernetes-style labels
	EnablePodman           bool
	EnablePodmanPrivileged bool // Full Docker support (privileged + AppArmor disabled)
	AutoStart              bool
	Verbose                bool
	Stack                  string            // Software stack to install (e.g., "nodejs", "python")
	StackParameters        map[string]string // Stack parameters — passed to install scripts as CONTAINARIUM_STACK_<name> env vars
	OSType                 pb.OSType         // Operating system type for the container
	OnProvisioning         func()            // Called when container is running but still provisioning (installing packages/stack)
	RDPPassword            string            // Generated RDP password for Windows VMs (output, set by Create)
}

CreateOptions holds options for creating a container

type Manager 

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

Manager handles container lifecycle operations

func New 

func New() (*Manager, error)

New creates a new container manager

func (*Manager) AddLabel 

func (m *Manager) AddLabel(username, key, value string) error

AddLabel adds or updates a single label on a container

func (*Manager) CleanupDisk 

func (m *Manager) CleanupDisk(username string) (string, int64, error)

CleanupDisk frees disk space inside a user's container

func (*Manager) ContainerExists 

func (m *Manager) ContainerExists(containerName string) bool

ContainerExists checks if a container exists

func (*Manager) Create 

func (m *Manager) Create(opts CreateOptions) (*incus.ContainerInfo, error)

Create creates a new container with full setup

func (*Manager) Delete 

func (m *Manager) Delete(username string, force bool) error

Delete deletes a container

func (*Manager) Get 

func (m *Manager) Get(username string) (*incus.ContainerInfo, error)

Get gets information about a specific container

func (*Manager) GetAllMetrics 

func (m *Manager) GetAllMetrics() ([]*incus.ContainerMetrics, error)

GetAllMetrics returns runtime metrics for all containers

func (*Manager) GetInfo 

func (m *Manager) GetInfo(containerName string) (*incus.ContainerInfo, error)

GetInfo returns detailed information about a container

func (*Manager) GetLabels 

func (m *Manager) GetLabels(username string) (map[string]string, error)

GetLabels retrieves labels from a container

func (*Manager) GetMetrics 

func (m *Manager) GetMetrics(username string) (*incus.ContainerMetrics, error)

GetMetrics returns runtime metrics for a container

func (*Manager) GetServerInfo 

func (m *Manager) GetServerInfo() (*incus.ServerInfo, error)

GetServerInfo gets information about the Incus server

func (*Manager) InstallStack added in v0.11.0 

func (m *Manager) InstallStack(username, stackID string) error

InstallStack installs a stack or base script on a running container

func (*Manager) List 

func (m *Manager) List() ([]incus.ContainerInfo, error)

List lists all containers

func (*Manager) ListWithLabels 

func (m *Manager) ListWithLabels(labelFilter map[string]string) ([]incus.ContainerInfo, error)

ListWithLabels lists containers filtered by labels

func (*Manager) RemoveLabel 

func (m *Manager) RemoveLabel(username, key string) error

RemoveLabel removes a single label from a container

func (*Manager) Resize 

func (m *Manager) Resize(containerName, cpu, memory, disk string, verbose bool) error

Resize dynamically adjusts container resources (CPU, memory, disk) without downtime

func (*Manager) SetLabels 

func (m *Manager) SetLabels(username string, labels map[string]string) error

SetLabels sets labels on a container, replacing all existing labels

func (*Manager) Start 

func (m *Manager) Start(username string) error

Start starts a stopped container

func (*Manager) Stop 

func (m *Manager) Stop(username string, force bool) error

Stop stops a running container

func (*Manager) UpgradeCgroupWrappers added in v0.12.0 

func (m *Manager) UpgradeCgroupWrappers() (int, error)

UpgradeCgroupWrappers installs cgroup wrapper scripts on all running user containers. This is intended to be called on daemon startup to retrofit existing containers that were created before the wrapper feature existed. It is idempotent — WriteFile with overwrite mode replaces existing wrappers.

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.