devcontainer

package
v1.201.0 Latest Latest
Warning

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

 Go to latest Published: Dec 10, 2025 License: Apache-2.0 Imports: 31 Imported by: 0

Documentation

Overview

Package devcontainer provides naming and validation for devcontainer instances.

Naming Convention

Devcontainer names use dot separators to avoid parsing ambiguity: 

Format: atmos-devcontainer.{name}.{instance}
Example: atmos-devcontainer.backend-api.test-1

Both name and instance can contain hyphens and underscores without ambiguity. The dot separator ensures unambiguous parsing when splitting container names.

For backward compatibility, the parser also supports the legacy hyphen format: 

Legacy: atmos-devcontainer-{name}-{instance}
Note: Legacy parsing is best-effort and may be ambiguous with hyphenated names.

Index

Constants

View Source 
const (
	// ContainerPrefix is the prefix for all Atmos devcontainer names.
	ContainerPrefix = "atmos-devcontainer"

	// DefaultInstance is the default instance name.
	DefaultInstance = "default"

	// LabelType is the label key for container type.
	LabelType = "com.atmos.type"

	// LabelDevcontainerName is the label key for devcontainer name.
	LabelDevcontainerName = "com.atmos.devcontainer.name"

	// LabelDevcontainerInstance is the label key for devcontainer instance.
	LabelDevcontainerInstance = "com.atmos.devcontainer.instance"

	// LabelWorkspace is the label key for workspace path.
	LabelWorkspace = "com.atmos.workspace"

	// LabelCreated is the label key for creation timestamp.
	LabelCreated = "com.atmos.created"
)

Variables

This section is empty.

Functions

func DetectRuntime 

func DetectRuntime(runtimeSetting string) (container.Runtime, error)

DetectRuntime detects the container runtime based on settings. If runtimeSetting is specified ("docker" or "podman"), it uses that. Otherwise, it auto-detects the runtime.

func FormatPortBindings 

func FormatPortBindings(bindings []container.PortBinding) string

FormatPortBindings formats port bindings for display.

func GenerateContainerName 

func GenerateContainerName(name, instance string) (string, error)

GenerateContainerName generates a container name from devcontainer name and instance. Format: atmos-devcontainer.{name}.{instance}.

func IsAtmosDevcontainer 

func IsAtmosDevcontainer(containerName string) bool

IsAtmosDevcontainer checks if a container name is an Atmos devcontainer. Supports both new dot format and legacy hyphen format.

func LoadAllConfigs 

func LoadAllConfigs(atmosConfig *schema.AtmosConfiguration) (map[string]*Config, error)

LoadAllConfigs loads all devcontainer configurations from atmos.yaml.

func LoadConfig 

func LoadConfig(
	atmosConfig *schema.AtmosConfiguration,
	name string,
) (*Config, *Settings, error)

LoadConfig loads a devcontainer configuration by name from atmos.yaml devcontainer section.

func ParseContainerName 

func ParseContainerName(containerName string) (name, instance string)

ParseContainerName parses a container name into devcontainer name and instance. Returns empty strings if the name doesn't match the expected format.

Supports both new dot format and legacy hyphen format for backward compatibility:

  • New format: atmos-devcontainer.{name}.{instance}
  • Legacy format: atmos-devcontainer-{name}-{instance} (best-effort, may be ambiguous)

func ParsePorts 

func ParsePorts(forwardPorts []interface{}, portsAttributes map[string]PortAttributes) ([]container.PortBinding, error)

ParsePorts parses the forwardPorts configuration into PortBinding structs. Supports both simple port numbers and explicit host:container mappings.

func ToCreateConfig 

func ToCreateConfig(config *Config, containerName, devcontainerName, instance string) *container.CreateConfig

ToCreateConfig converts a devcontainer config to container.CreateConfig.

func ValidateName 

func ValidateName(name string) error

func ValidateNotImported 

func ValidateNotImported(importPath string) error

ValidateNotImported checks that devcontainers are not used as component dependencies. Devcontainers are workspace-level tools and should not be imported by components.

Types

type Build 

type Build struct {
	Dockerfile string            `yaml:"dockerfile" json:"dockerfile" mapstructure:"dockerfile"`
	Context    string            `yaml:"context,omitempty" json:"context,omitempty" mapstructure:"context"`
	Args       map[string]string `yaml:"args,omitempty" json:"args,omitempty" mapstructure:"args"`
}

Build represents build configuration for a devcontainer.

type Config 

type Config struct {
	Name            string                    `yaml:"name" json:"name" mapstructure:"name"`
	Image           string                    `yaml:"image" json:"image" mapstructure:"image"`
	Build           *Build                    `yaml:"build,omitempty" json:"build,omitempty" mapstructure:"build"`
	WorkspaceFolder string                    `yaml:"workspaceFolder,omitempty" json:"workspaceFolder,omitempty" mapstructure:"workspacefolder"`
	WorkspaceMount  string                    `yaml:"workspaceMount,omitempty" json:"workspaceMount,omitempty" mapstructure:"workspacemount"`
	Mounts          []string                  `yaml:"mounts,omitempty" json:"mounts,omitempty" mapstructure:"mounts"`
	ForwardPorts    []interface{}             `yaml:"forwardPorts,omitempty" json:"forwardPorts,omitempty" mapstructure:"forwardports"`
	PortsAttributes map[string]PortAttributes `yaml:"portsAttributes,omitempty" json:"portsAttributes,omitempty" mapstructure:"portsattributes"`
	ContainerEnv    map[string]string         `yaml:"containerEnv,omitempty" json:"containerEnv,omitempty" mapstructure:"containerenv"`
	RemoteUser      string                    `yaml:"remoteUser,omitempty" json:"remoteUser,omitempty" mapstructure:"remoteuser"`

	// Runtime configuration
	RunArgs         []string `yaml:"runArgs,omitempty" json:"runArgs,omitempty" mapstructure:"runargs"`
	OverrideCommand bool     `yaml:"overrideCommand,omitempty" json:"overrideCommand,omitempty" mapstructure:"overridecommand"`
	Init            bool     `yaml:"init,omitempty" json:"init,omitempty" mapstructure:"init"`
	Privileged      bool     `yaml:"privileged,omitempty" json:"privileged,omitempty" mapstructure:"privileged"`
	CapAdd          []string `yaml:"capAdd,omitempty" json:"capAdd,omitempty" mapstructure:"capadd"`
	SecurityOpt     []string `yaml:"securityOpt,omitempty" json:"securityOpt,omitempty" mapstructure:"securityopt"`
	UserEnvProbe    string   `yaml:"userEnvProbe,omitempty" json:"userEnvProbe,omitempty" mapstructure:"userenvprobe"`
}

Config represents a complete devcontainer configuration.

type ConfigLoader 

type ConfigLoader interface {
	// LoadConfig loads configuration for a specific devcontainer by name.
	LoadConfig(atmosConfig *schema.AtmosConfiguration, name string) (*Config, *Settings, error)

	// LoadAllConfigs loads all devcontainer configurations.
	LoadAllConfigs(atmosConfig *schema.AtmosConfiguration) (map[string]*Config, error)
}

ConfigLoader handles loading devcontainer configurations.

func NewConfigLoader 

func NewConfigLoader() ConfigLoader

NewConfigLoader creates a new ConfigLoader.

type ExecParams 

type ExecParams struct {
	Name        string
	Instance    string
	Interactive bool
	UsePTY      bool
	Command     []string
}

ExecParams encapsulates parameters for ExecuteExec.

type IdentityManager 

type IdentityManager interface {
	// InjectIdentityEnvironment injects identity environment variables into config.
	InjectIdentityEnvironment(ctx context.Context, config *Config, identityName string) error
}

IdentityManager handles identity-related operations for devcontainers.

func NewIdentityManager 

func NewIdentityManager() IdentityManager

NewIdentityManager creates a new IdentityManager.

type Info 

type Info struct {
	Name        string
	Image       string
	Description string
}

Info represents metadata about a registered devcontainer.

type Manager 

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

Manager handles devcontainer lifecycle operations with dependency injection. It provides methods for managing devcontainers: List, Start, Stop, Attach, Exec, Remove, Rebuild, Logs, ShowConfig, and instance management.

func NewManager 

func NewManager(opts ...Option) *Manager

NewManager creates a new Manager with default or custom dependencies. Use Option functions to provide custom implementations for testing.

func (*Manager) Attach 

func (m *Manager) Attach(atmosConfig *schema.AtmosConfiguration, name, instance string, usePTY bool) error

Attach attaches to a running devcontainer. TODO: Add --identity flag support. When implemented, ENV file paths from identity must be resolved relative to container paths (e.g., /localhost or bind mount location), not host paths, since the container runs in its own filesystem namespace.

func (*Manager) Exec 

func (m *Manager) Exec(atmosConfig *schema.AtmosConfiguration, params ExecParams) error

Exec executes a command in a running devcontainer. TODO: Add --identity flag support. When implemented, ENV file paths from identity must be resolved relative to container paths (e.g., /localhost or bind mount location), not host paths, since the container runs in its own filesystem namespace.

func (*Manager) GenerateNewInstance 

func (m *Manager) GenerateNewInstance(atmosConfig *schema.AtmosConfiguration, name, baseInstance string) (string, error)

GenerateNewInstance generates a new unique instance name by finding existing containers for the given devcontainer name and incrementing the highest number. Pattern: {baseInstance}-1, {baseInstance}-2, etc. Returns the new instance name (e.g., "default-1", "default-2").

func (*Manager) List 

func (m *Manager) List(atmosConfig *schema.AtmosConfiguration) error

List lists all available devcontainers with running status.

func (*Manager) Logs 

func (m *Manager) Logs(atmosConfig *schema.AtmosConfiguration, name, instance string, follow bool, tail string) error

Logs shows logs from a devcontainer.

func (*Manager) Rebuild 

func (m *Manager) Rebuild(atmosConfig *schema.AtmosConfiguration, name, instance, identityName string, noPull bool) error

Rebuild rebuilds a devcontainer from scratch.

func (*Manager) Remove 

func (m *Manager) Remove(atmosConfig *schema.AtmosConfiguration, name, instance string, force bool) error

Remove removes a devcontainer by name and instance. The operation is idempotent - returns nil if the container does not exist.

Reloads configuration, detects the container runtime, and generates the container name. Fails if the container is running unless force is true. When force is true, stops a running container before removal. Returns relevant errors for runtime or config failures.

Parameters:

  • atmosConfig: Atmos configuration for performance tracking
  • name: Devcontainer name from configuration
  • instance: Instance identifier (e.g., "default", "prod")
  • force: If true, stops running containers before removal; if false, fails on running containers

func (*Manager) ShowConfig 

func (m *Manager) ShowConfig(atmosConfig *schema.AtmosConfiguration, name string) error

ShowConfig shows the configuration for a devcontainer.

func (*Manager) Start 

func (m *Manager) Start(atmosConfig *schema.AtmosConfiguration, name, instance, identityName string) error

Start starts a devcontainer with optional identity.

func (*Manager) Stop 

func (m *Manager) Stop(atmosConfig *schema.AtmosConfiguration, name, instance string, timeout int) error

Stop stops a devcontainer.

type Option 

type Option func(*Manager)

Option configures the Manager.

func WithConfigLoader 

func WithConfigLoader(loader ConfigLoader) Option

WithConfigLoader sets a custom ConfigLoader.

func WithIdentityManager 

func WithIdentityManager(mgr IdentityManager) Option

WithIdentityManager sets a custom IdentityManager.

func WithRuntimeDetector 

func WithRuntimeDetector(detector RuntimeDetector) Option

WithRuntimeDetector sets a custom RuntimeDetector.

type PortAttributes 

type PortAttributes struct {
	Label    string `yaml:"label,omitempty" json:"label,omitempty" mapstructure:"label"`
	Protocol string `yaml:"protocol,omitempty" json:"protocol,omitempty" mapstructure:"protocol"`
}

PortAttributes represents metadata for a forwarded port.

type Registry 

type Registry interface {
	// Register a named devcontainer configuration
	Register(name string, config *Config) error

	// Get a devcontainer configuration by name
	Get(name string) (*Config, error)

	// List all registered devcontainer configurations
	List() ([]Info, error)

	// Exists checks if a devcontainer configuration exists
	Exists(name string) bool
}

Registry manages devcontainer configurations.

type RuntimeDetector 

type RuntimeDetector interface {
	// DetectRuntime detects and returns the appropriate container runtime.
	DetectRuntime(preferred string) (container.Runtime, error)
}

RuntimeDetector handles container runtime detection.

func NewRuntimeDetector 

func NewRuntimeDetector() RuntimeDetector

NewRuntimeDetector creates a new RuntimeDetector.

type Settings 

type Settings struct {
	Runtime string `yaml:"runtime,omitempty" json:"runtime,omitempty" mapstructure:"runtime"`
}

Settings represents Atmos-specific devcontainer settings.

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.