README
¶
instance
Persistent Apptainer instance management with state file persistence for configuration tracking.
Architecture
start.go Instance startup with container setup
exec.go Command execution in running instances
stop.go Instance termination
state.go State file persistence (JSON)
Key Types
Options - Name, Overlays, WritableImg, EnvSettings, BindPaths, Fakeroot, BaseImage
ExecOptions - InstanceName, Command, ApptainerBin
StopOptions - InstanceName, DeleteAll, Pattern
State - Persisted config: Name, BaseImage, Overlays, StartTime, PID
Usage
// Start instance
opts := instance.Options{
Name: "myinstance",
Overlays: []string{"python/3.11", "env.img"},
WritableImg: true,
}
instance.Start(ctx, opts)
// Execute in instance
instance.Exec(ctx, instance.ExecOptions{
InstanceName: "myinstance",
Command: []string{"python", "script.py"},
})
// Stop instance
instance.Stop(ctx, instance.StopOptions{InstanceName: "myinstance"})
State Persistence
State files: $XDG_STATE_HOME/condatainer/instances/<name>.json
Stores instance configuration (State struct) for recovery and tracking. Auto-cleaned on normal stop.
Lifecycle
Start: Container setup → apptainer.InstanceStart() → save state
Exec: Load state → apptainer.InstanceExec()
Stop: apptainer.InstanceStop() → delete state
Instance List/Stats
For listing and stats operations, commands call internal/apptainer directly:
apptainer.InstanceList(ctx)- List all running instancesapptainer.InstanceStats(ctx, name)- Show instance statistics
These operations don't require state file access.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Exec ¶
func Exec(ctx context.Context, opts ExecOptions) error
Exec executes a command in a running instance
Types ¶
type ExecOptions ¶
type ExecOptions struct {
Name string // Instance name
Command []string // Command to execute
EnvSettings []string // Additional environment variables to set (format: "KEY=VALUE")
ApptainerFlags []string // Additional apptainer flags to pass through
ApptainerBin string // Path to apptainer binary
PrintEnv bool // Whether to print environment variables (when command length <= 1)
}
ExecOptions holds configuration for executing commands in an instance
type Options ¶
type Options struct {
Name string // Instance name
Overlays []string // Overlay paths
WritableImg bool // Whether .img overlays should be writable
EnvSettings []string // Environment variables
BindPaths []string // Bind mount paths
ApptainerFlags []string // Additional apptainer flags
Fakeroot bool // Run with fakeroot
BaseImage string // Base image path
ApptainerBin string // Path to apptainer binary
}
Options holds configuration for starting an instance
type State ¶
type State struct {
Name string `json:"name"`
Env []string `json:"env"` // Environment variables
Overlays []string `json:"overlays"` // Overlay paths
BindPaths []string `json:"bind_paths"` // Bind paths
BaseImage string `json:"base_image"` // Base image path
Notes map[string]string `json:"notes"` // Environment variable notes for display
}
State holds the runtime state of an instance apptainer exec instance://NAME cannot use the ENV used with instance start, so we have to save them here to be loaded by exec
type StopOptions ¶
type StopOptions struct {
ApptainerBin string // Path to apptainer binary
ApptainerFlags []string // All arguments to pass to apptainer instance stop
All bool // Whether --all flag is set
InstanceNames []string // Instance names/patterns to stop
}
StopOptions holds configuration for stopping an instance
Source Files