client

package
v0.0.0-...-ccd25d4 Latest Latest
Warning

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

 Go to latest Published: Jan 7, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package client provides a high-level wrapper around the Incus client library.

This package abstracts the complexities of interacting with Incus servers and provides a compose-spec friendly interface for managing instances, networks, volumes, and projects.

For detailed documentation, see: https://gitlab.com/r3j0/incus-compose/-/blob/main/docs/architecture/client/README.md

Index

Constants

View Source 
const (
	PriorityProject  = 1 << 8  // Infrastructure (created first, deleted last)
	PriorityProfile  = 1 << 9  // Base config
	PriorityImage    = 1 << 10 // Images (own batch for parallel downloads)
	PriorityNetwork  = 1 << 11 // Networks
	PriorityVolume   = 1 << 12 // Storage
	PriorityInstance = 1 << 13 // Instance depends on everything above
)

Resource creation priorities using powers of 2 for clear separation. Lower priority values are created first and deleted last.

View Source 
const (
	InstanceDeviceTypeProxy = "proxy"
	InstanceDeviceTypeDisk  = "disk"
	InstanceDeviceTypeNic   = "nic"
	InstanceDeviceTypeTmpfs = "tmpfs"
)

Device type constants.

Variables

View Source 
var (
	// ErrUnsupportedAction indicates the resource does not support the action.
	ErrUnsupportedAction = NewError("resource does not support action")

	// ErrUnknown indicates an unknown error occurred.
	ErrUnknown = NewError("unknown")

	// ErrUnknownConfig indicates an unknown config for a resource.
	ErrUnknownConfig = NewError("unknown config for resource")

	// ErrNilPointer indicates something is a nil pointer.
	ErrNilPointer = NewError("found a nil pointer")

	// ErrOperation is returned within an operation.
	ErrOperation = NewError("in an operation")

	// ErrBadDeviceConfig indicates a bad device config.
	ErrBadDeviceConfig = NewError("bad config for device")

	// ErrDependencyNotEnsured indicates a dependency is not ensured.
	ErrDependencyNotEnsured = NewError("dependency not ensured")

	// ErrDisconnected indicates an operation was attempted on a disconnected client.
	ErrDisconnected = NewError("client is not connected")

	// ErrConnectionFailed indicates a connection attempt failed.
	ErrConnectionFailed = NewError("connection failed")

	// ErrAborted indicates an operation was aborted (e.g., by BeforeAny hook).
	ErrAborted = NewError("operation aborted")

	// ErrNotFound indicates a resource was not found.
	ErrNotFound = NewError("resource not found")

	// ErrNotEnsured indicates an operation requires the resource to be ensured first.
	ErrNotEnsured = NewError("resource not ensured")

	// ErrImageRequired indicates an instance requires an image.
	ErrImageRequired = NewError("instances without an image are not yet supported")

	// ErrBindMountRemote indicates bind mounts are not supported over network connections.
	ErrBindMountRemote = NewError("bind mounts not supported over network connection")

	// ErrUnknownResource indicates an unknown resource kind.
	ErrUnknownResource = NewError("unknown resource kind")

	// ErrInvalidFormat indicates invalid format or syntax.
	ErrInvalidFormat = NewError("invalid format")

	// ErrImageSource indicates an image source error.
	ErrImageSource = NewError("image source error")

	// ErrDeviceConflict indicates a device name conflict.
	ErrDeviceConflict = NewError("device conflict")

	// ErrVolumeMismatch indicates volume configuration mismatch.
	ErrVolumeMismatch = NewError("volume configuration mismatch")

	// ErrCreate indicates a resource creation error.
	ErrCreate = NewError("create failed")
)

Functions

func ByKind 

func ByKind[T Resource](resources []Resource, kind Kind) ([]T, error)

ByKind filters resources by kind and returns them as the specified type.

func RunAction 

func RunAction(r Resource, action Action, opts ...Option) error

RunAction runs a action on a resource.

func SupportsAction 

func SupportsAction(r Resource, action Action) bool

SupportsAction returns if the Resource supports the action.

Types

type Action 

type Action string

Action identifies a resource action. 

const (
	ActionEnsure Action = "ensure"
	ActionDelete Action = "delete"
	ActionStart  Action = "start"
	ActionStop   Action = "stop"
	ActionLog    Action = "log"
)

Action constants for resource actions.

type BaseResource 

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

BaseResource provides common fields for all Incus resources.

func NewBaseResource 

func NewBaseResource(kind Kind, name string, priority int) *BaseResource

NewBaseResource creates a new BaseResource.

func (*BaseResource) Kind 

func (r *BaseResource) Kind() Kind

Kind returns the resource kind.

func (*BaseResource) Name 

func (r *BaseResource) Name() string

Name returns the resource name.

func (*BaseResource) Priority 

func (r *BaseResource) Priority() int

Priority returns the resource priority.

type Client 

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

Client wraps a project-scoped Incus client with resource management.

func (*Client) AddHookAfter 

func (c *Client) AddHookAfter(hook func(action Action, r Resource, args Options, err error) error)

AddHookAfter adds a hook that will be executed after any action (LIFO order).

func (*Client) AddHookBefore 

func (c *Client) AddHookBefore(hook func(action Action, r Resource, args Options, err error) error)

AddHookBefore adds a hook that will be executed before any action. You may use it for abort control.

func (*Client) Config 

func (c *Client) Config() ClientConfig

Config returns the client config.

func (*Client) Connection 

func (c *Client) Connection() *incusClient.ProtocolIncus

Connection returns the project-scoped Connection client.

func (*Client) GlobalConnection 

func (c *Client) GlobalConnection() *incusClient.ProtocolIncus

GlobalConnection returns the global (non-project-scoped) Incus client.

func (*Client) IncusProject 

func (c *Client) IncusProject() string

IncusProject returns the sanitized Incus project name.

func (*Client) Instance 

func (c *Client) Instance(name string, config InstanceConfig) (*Instance, error)

Instance returns an existing Instance resource or creates a new one.

func (*Client) IsRemote 

func (c *Client) IsRemote() bool

IsRemote returns true if connected via network (not unix socket).

func (*Client) LogDebug 

func (c *Client) LogDebug(msg string, args ...any)

LogDebug logs an debug message. The `any` here is ok.

func (*Client) LogError 

func (c *Client) LogError(msg string, args ...any)

LogError logs an error. The `any` here is ok.

func (*Client) LogWarn 

func (c *Client) LogWarn(msg string, args ...any)

LogWarn logs an warning message. The `any` here is ok.

func (*Client) Project 

func (c *Client) Project() string

Project returns the user-facing project name.

func (*Client) Resource 

func (c *Client) Resource(kind Kind, name string, config Config) (Resource, error)

Resource returns an existing resource or creates a new one.

type ClientConfig 

type ClientConfig struct {
	// URL is the Incus server URL to connect to.
	URL string

	// Logger to use within this client.
	Logger *slog.Logger

	// InsecureSkipVerify accepts any certificate (insecure, for testing only).
	InsecureSkipVerify bool

	// TLSClientCert is the path to TLS client certificate for authentication.
	TLSClientCert string

	// TLSClientKey is the path to TLS client key for authentication.
	TLSClientKey string

	// NetworkPrefix is the prefix for new networks (default: "ic-").
	NetworkPrefix string

	// DefaultStoragePool is the storage pool to use for volumes (default: "default").
	DefaultStoragePool string

	// DescriptionFormat is the format string for resource descriptions (default: "incus-compose: %s").
	DescriptionFormat string

	// ProvidedInstanceServer allows injecting an existing connection (for testing).
	ProvidedInstanceServer incusClient.InstanceServer

	// ProvidedImageCache allows injecting an existing image cache (for testing).
	ProvidedImageCache incusClient.InstanceServer

	// CacheProject is the project name to use as image cache.
	// If set, the project will be created if it doesn't exist.
	CacheProject string
}

ClientConfig holds configuration options for the Client.

type ClientOption 

type ClientOption func(*ClientConfig)

ClientOption is a functional option for configuring the Client.

func ClientCacheProject 

func ClientCacheProject(n string) ClientOption

ClientCacheProject sets the project name to use as image cache.

func ClientDefaultStoragePool 

func ClientDefaultStoragePool(n string) ClientOption

ClientDefaultStoragePool sets the default storage pool name.

func ClientDescriptionFormat 

func ClientDescriptionFormat(n string) ClientOption

ClientDescriptionFormat sets the format string for resource descriptions.

func ClientInsecureSkipVerify 

func ClientInsecureSkipVerify() ClientOption

ClientInsecureSkipVerify disables TLS certificate verification.

func ClientLogger 

func ClientLogger(l *slog.Logger) ClientOption

ClientLogger sets the client to use within the created client.

func ClientNetworkPrefix 

func ClientNetworkPrefix(n string) ClientOption

ClientNetworkPrefix sets the prefix for network names.

func ClientProvideConnection 

func ClientProvideConnection(instances incusClient.InstanceServer) ClientOption

ClientProvideConnection injects existing connections (for testing).

func ClientProvideInstanceServer 

func ClientProvideInstanceServer(server incusClient.InstanceServer) ClientOption

ClientProvideInstanceServer injects an existing instance server connection.

func ClientTLSClientCert 

func ClientTLSClientCert(f string) ClientOption

ClientTLSClientCert sets the path to the TLS client certificate.

func ClientTLSClientKey 

func ClientTLSClientKey(f string) ClientOption

ClientTLSClientKey sets the path to the TLS client key.

func ClientURL 

func ClientURL(u string) ClientOption

ClientURL sets the Incus server ClientURL.

type Config 

type Config interface {
	GetConfig() any
}

Config is implemented by resource configuration types.

type DeleteAble 

type DeleteAble interface {
	Delete(opts ...Option) error
}

DeleteAble is implemented by resources that can be deleted.

type EnsureAble 

type EnsureAble interface {
	// Ensure fetches an existing Resource or creates a new one.
	// If a Resource with the same name exists, it is returned.
	Ensure(opts ...Option) error
}

EnsureAble is implemented by resources that can be ensured.

type Error 

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

Error is a sentinel-based error type that supports context enrichment.

func NewError 

func NewError(text string) *Error

NewError creates a new sentinel error.

func (*Error) As 

func (e *Error) As(target any) bool

As implements errors.As() support by copying to target if it's *Error.

func (*Error) Error 

func (e *Error) Error() string

Error implements the error interface.

func (*Error) Is 

func (e *Error) Is(target error) bool

Is implements errors.Is() support by comparing sentinel pointers.

func (*Error) Unwrap 

func (e *Error) Unwrap() error

Unwrap returns the wrapped error for errors.Unwrap() support.

func (*Error) WithAction 

func (e *Error) WithAction(action Action) *Error

WithAction adds action context to the error.

func (*Error) WithKindName 

func (e *Error) WithKindName(kind Kind, name string) *Error

WithKindName adds resource kind and name context to the error.

func (*Error) WithResource 

func (e *Error) WithResource(resource Resource) *Error

WithResource adds resource context to the error.

func (*Error) WithText 

func (e *Error) WithText(text string) *Error

WithText adds text context to the error.

func (*Error) Wrap 

func (e *Error) Wrap(wrapped error) *Error

Wrap wraps another error, preserving the sentinel identity.

type GlobalClient 

type GlobalClient struct {
	Ctx    context.Context
	Config ClientConfig
	// contains filtered or unexported fields
}

GlobalClient provides a high-level interface to Incus operations.

func New 

func New(ctx context.Context, opts ...ClientOption) *GlobalClient

New creates a new Client with the provided context and logger.

func (*GlobalClient) AddHookAfter 

func (c *GlobalClient) AddHookAfter(hook func(action Action, r Resource, args Options, err error) error)

AddHookAfter adds a hook that will be executed after any action (LIFO order).

func (*GlobalClient) AddHookBefore 

func (c *GlobalClient) AddHookBefore(hook func(action Action, r Resource, args Options, err error) error)

AddHookBefore adds a hook that will be executed before any action (FIFO order). You may use it for abort control.

func (*GlobalClient) Connect 

func (c *GlobalClient) Connect() error

Connect establishes a connection to the Incus server.

func (*GlobalClient) DeleteProject 

func (c *GlobalClient) DeleteProject(name string, force bool) error

DeleteProject deletes a project and removes it from the cache.

func (*GlobalClient) EnsureProject 

func (c *GlobalClient) EnsureProject(name string, create bool) (*Client, error)

EnsureProject ensures a project exists and returns a ClientProject. Creates the project if create is true and it does not exist.

func (*GlobalClient) IsConnected 

func (c *GlobalClient) IsConnected() bool

IsConnected returns true if the client is connected.

func (*GlobalClient) IsDebugging 

func (c *GlobalClient) IsDebugging() bool

IsDebugging returns true if debug logging is enabled.

func (*GlobalClient) IsRemote 

func (c *GlobalClient) IsRemote() bool

IsRemote returns true if connected via network (not unix socket).

func (*GlobalClient) LogError 

func (c *GlobalClient) LogError(msg string, args ...any)

LogError logs an error. The `any` here is ok.

func (*GlobalClient) SetOutputHandler 

func (c *GlobalClient) SetOutputHandler(handler func(action Action, r Resource, data []byte))

SetOutputHandler sets the handler for resource output (e.g., logs). The handler receives raw bytes - formatting is the caller's responsibility.

type Image 

type Image struct {
	*BaseResource

	Config ImageConfig

	// State - nil means not ensured.
	IncusAlias *incusApi.ImageAliasesEntry
	ETag       string
	// contains filtered or unexported fields
}

Image represents an OCI image copied to the Incus image cache.

func (*Image) CopyTo 

func (r *Image) CopyTo(target incusClient.InstanceServer) error

CopyTo copies image from cache to target instance server (project). The target is remembered for Delete operations.

func (*Image) Created 

func (r *Image) Created() bool

Created returns true if the image was created during the last Ensure call.

func (*Image) Delete 

func (r *Image) Delete(opts ...Option) error

Delete removes the image from the project (target), not from cache.

func (*Image) Ensure 

func (r *Image) Ensure(opts ...Option) error

Ensure retrieves an existing image from cache or copies it if Create option is set.

func (*Image) IncusName 

func (r *Image) IncusName() string

IncusName returns the image alias name used in Incus.

func (*Image) IsEnsured 

func (r *Image) IsEnsured() bool

IsEnsured returns true if the image has been fetched/copied to cache.

func (*Image) Remote 

func (r *Image) Remote() string

Remote returns the image remote.

func (*Image) SetSource 

func (r *Image) SetSource(imageServer incusClient.ImageServer)

SetSource sets the source image server.

func (*Image) Status 

func (r *Image) Status() string

Status returns the image status: "Unknown", "Cached", or "Exists".

func (*Image) String 

func (r *Image) String() string

String is for debugging.

type ImageConfig 

type ImageConfig struct {
	// Source is the image server to copy the image from.
	// For NativeIncus images, this can be nil and will be resolved from Remote.
	Source incusClient.ImageServer

	// CacheServer is an image server to use as cache (for library users).
	// Takes precedence over CacheProject.
	CacheServer incusClient.InstanceServer

	// CacheProject is the project name to use as cache (for CLI users).
	// The project will be created if it doesn't exist.
	// Ignored if CacheServer is set.
	CacheProject string

	// Remote is the domain part of the image reference.
	Remote string

	// Image is the image reference without the remote prefix.
	Image string

	// NativeIncus indicates this is an Incus native image (e.g., "images:alpine/edge")
	// rather than an OCI image (e.g., "docker.io/library/alpine:latest").
	NativeIncus bool
	// contains filtered or unexported fields
}

ImageConfig contains the source and cache configuration for an image.

func (*ImageConfig) GetConfig 

func (c *ImageConfig) GetConfig() any

GetConfig returns the configuration.

type Instance 

type Instance struct {
	*BaseResource

	Config InstanceConfig

	// State - nil means not ensured.
	IncusInstance *incusApi.Instance
	ETag          string

	// UID/GID extracted from container (for volume shifting).
	UID uint32
	GID uint32

	IncusInstanceFull *incusApi.InstanceFull
	IncusImageAlias   *incusApi.ImageAliasesEntry
	// contains filtered or unexported fields
}

Instance represents an Incus container or virtual machine.

func (*Instance) Created 

func (r *Instance) Created() bool

Created returns true if the instance was created during the last Ensure call.

func (*Instance) Delete 

func (r *Instance) Delete(opts ...Option) error

Delete removes the instance from Incus.

func (*Instance) Ensure 

func (r *Instance) Ensure(opts ...Option) error

Ensure retrieves an existing instance or creates a new one if args.Create is true.

func (*Instance) HasFull 

func (r *Instance) HasFull() bool

HasFull returns true if the instance has a full instance.

func (*Instance) IncusName 

func (r *Instance) IncusName() string

IncusName returns the sanitized instance name used in Incus.

func (*Instance) IsEnsured 

func (r *Instance) IsEnsured() bool

IsEnsured returns true if the instance has been fetched/created.

func (*Instance) Log 

func (r *Instance) Log(opts ...Option) error

Log streams the instance console log to the outputHandler.

func (*Instance) PushSecrets 

func (r *Instance) PushSecrets() error

PushSecrets pushes secrets into the running instance. Secrets are only pushed if they don't already exist with the same content.

func (*Instance) Start 

func (r *Instance) Start(opts ...Option) error

Start starts the instance.

func (*Instance) Stop 

func (r *Instance) Stop(opts ...Option) error

Stop stops the instance.

func (*Instance) String 

func (r *Instance) String() string

String is for debugging.

type InstanceConfig 

type InstanceConfig struct {
	// Type is the instance type (container or VM).
	Type incusApi.InstanceType

	// Full fetches the full instance.
	Full bool

	// Image is the OCI image to create the instance from.
	Image string

	// Ensured Resources that this instance depends on.
	Resources []Resource

	// Devices are devices attached before instance creation (networks, proxies).
	Devices []InstanceDevice

	// PostDevices are devices attached after instance creation (volumes needing UID/GID).
	PostDevices []InstanceDevice

	// Secrets are files pushed into the instance after start.
	Secrets []InstanceSecret

	// Config contains Incus instance configuration options.
	Config map[string]string

	// ExtraDevices contains additional raw device configurations.
	ExtraDevices map[string]map[string]string
}

InstanceConfig configures instance creation.

func (*InstanceConfig) GetConfig 

func (c *InstanceConfig) GetConfig() any

GetConfig returns the configuration.

type InstanceDevice 

type InstanceDevice struct {
	// Name is the device name.
	Name string

	// Config holds the device configuration.
	Config InstanceDeviceConfig
}

InstanceDevice represents an instance device configuration.

func (*InstanceDevice) ToIncusDevice 

func (d *InstanceDevice) ToIncusDevice() (string, map[string]string, *Error)

ToIncusDevice converts the device to Incus API format. Returns the device name and configuration map.

type InstanceDeviceConfig 

type InstanceDeviceConfig struct {
	// DeviceType identifies the device type (nic, disk, proxy, tmpfs).
	DeviceType string

	// Network is the network resource for nic devices.
	Network Resource

	// Proxy contains proxy device configuration.
	Proxy InstanceDeviceProxyConfig

	// Disk contains disk device configuration.
	Disk InstanceDeviceDiskConfig

	// Tmpfs contains tmpfs device configuration.
	Tmpfs InstanceDeviceTmpfsConfig

	ExtraConfig map[string]string
}

InstanceDeviceConfig configures an instance device.

type InstanceDeviceDiskConfig 

type InstanceDeviceDiskConfig struct {
	StorageVolumeConfig *StorageVolumeConfig

	// Source is the volume name or host path.
	Source string

	// Path is the mount point inside the instance.
	Path string

	// Shift enables UID/GID shifting for the mount.
	Shift bool

	// ReadOnly makes the mount read-only.
	ReadOnly bool
}

InstanceDeviceDiskConfig configures a disk device (volume or bind mount).

type InstanceDeviceProxyConfig 

type InstanceDeviceProxyConfig struct {
	// ListenType is the protocol type for the listen side (e.g., "tcp").
	ListenType string

	// ListenAddr is the address to listen on.
	ListenAddr string

	// ListenPort is the port to listen on.
	ListenPort uint32

	// ConnectType is the protocol type for the connect side (e.g., "tcp").
	ConnectType string

	// ConnectAddr is the address to connect to.
	ConnectAddr string

	// ConnectPort is the port to connect to.
	ConnectPort uint32

	// Nat enables NAT mode for the proxy.
	Nat bool
}

InstanceDeviceProxyConfig configures a proxy device for port forwarding.

type InstanceDeviceTmpfsConfig 

type InstanceDeviceTmpfsConfig struct {
	// Path is the mount point inside the instance.
	Path string

	// Size is the optional size limit in bytes.
	Size string
}

InstanceDeviceTmpfsConfig configures a tmpfs device.

type InstanceSecret 

type InstanceSecret struct {
	Source  string // secret name
	Target  string // path in container (default: /run/secrets/{source})
	Content []byte // file content
	UID     int64
	GID     int64
	Mode    int // default: 0400
}

InstanceSecret represents a secret to be pushed into the instance.

type Kind 

type Kind string

Kind identifies a resource type. 

const (
	KindProject       Kind = "project"
	KindProfile       Kind = "profile"
	KindImage         Kind = "image"
	KindStorageVolume Kind = "storage-volume"
	KindNetwork       Kind = "network"
	KindInstance      Kind = "instance"
)

Resource kind identifiers.

type LogAble 

type LogAble interface {
	Log(opts ...Option) error
}

LogAble is implemented by resources that can stream logs.

type Network 

type Network struct {
	*BaseResource

	Config NetworkConfig

	// State - nil means not ensured.
	IncusNetwork *incusApi.Network
	ETag         string
	// contains filtered or unexported fields
}

Network represents an Incus bridge network.

func (*Network) Created 

func (r *Network) Created() bool

Created returns true if the network was created during the last Ensure call.

func (*Network) Delete 

func (r *Network) Delete(opts ...Option) error

Delete removes the network from Incus. External networks are never deleted.

func (*Network) Ensure 

func (r *Network) Ensure(opts ...Option) error

Ensure retrieves an existing network or creates a new one if args.Create is true.

func (*Network) IncusName 

func (r *Network) IncusName() string

IncusName returns the sanitized network name used in Incus.

func (*Network) IsEnsured 

func (r *Network) IsEnsured() bool

IsEnsured returns true if the network state has been fetched from Incus.

func (*Network) String 

func (r *Network) String() string

String is for debugging.

type NetworkConfig 

type NetworkConfig struct {
	// Type is the network type (default: "bridge").
	Type string

	// External marks the network as externally managed.
	// External networks must already exist and won't be created or deleted.
	External bool
}

NetworkConfig configures network creation.

func (*NetworkConfig) GetConfig 

func (c *NetworkConfig) GetConfig() any

GetConfig returns the configuration.

type Option 

type Option func(o *Options)

Option configures action arguments.

func OptionCreate 

func OptionCreate() Option

OptionCreate creates resources if they don't exist (for ActionEnsure).

func OptionFollow 

func OptionFollow() Option

OptionFollow enables continuous streaming (for ActionLog).

func OptionForce 

func OptionForce() Option

OptionForce forces deletion/stop even if resource is in use.

func OptionTimeout 

func OptionTimeout(t int) Option

OptionTimeout in seconds for actions (0 = default).

type Options 

type Options struct {
	// Create resources if they don't exist (for ActionEnsure).
	Create bool

	// Force deletion/stop even if resource is in use.
	Force bool

	// Timeout in seconds for actions (0 = default).
	Timeout int

	// Follow enables continuous streaming (for ActionLog).
	Follow bool
}

Options holds arguments for resource actions.

func NewOptions 

func NewOptions(opts ...Option) Options

NewOptions makes a ActionArgs struct from ActionO* options.

type PoolRunArgs 

type PoolRunArgs struct {
	// FailFast stops processing on first error (default: true).
	FailFast bool
}

PoolRunArgs contains options for WorkerPool.Run.

type Profile 

type Profile struct {
	*BaseResource

	Config ProfileConfig

	// State - nil means not ensured.
	IncusProfile *incusApi.Profile
	ETag         string
	// contains filtered or unexported fields
}

Profile represents an Incus profile resource.

func (*Profile) Created 

func (r *Profile) Created() bool

Created returns true if the profile was created during the last Ensure call.

func (*Profile) Delete 

func (r *Profile) Delete(opts ...Option) error

Delete removes the profile from Incus.

func (*Profile) Ensure 

func (r *Profile) Ensure(opts ...Option) error

Ensure retrieves an existing resource or creates a new one if args.Create is true.

func (*Profile) HasDevice 

func (r *Profile) HasDevice(name string) bool

HasDevice returns true if the profile has a device with the given name.

func (*Profile) IncusName 

func (r *Profile) IncusName() string

IncusName returns the sanitized profile name used in Incus.

func (*Profile) IsEnsured 

func (r *Profile) IsEnsured() bool

IsEnsured returns true if the profile state has been fetched from Incus.

func (*Profile) String 

func (r *Profile) String() string

String is for debugging.

type ProfileConfig 

type ProfileConfig struct {
	// SourceServer is the Incus server to copy the profile from.
	// If nil, uses the global Incus client.
	SourceServer *incusClient.ProtocolIncus

	// SourceProject is the project containing the source profile.
	SourceProject string

	// SourceProfile is the name of the profile to copy from.
	SourceProfile string
}

ProfileConfig configures profile creation from a source profile.

func (*ProfileConfig) GetConfig 

func (c *ProfileConfig) GetConfig() any

GetConfig returns the configuration.

type Resource 

type Resource interface {
	// Kind returns the resource type identifier (e.g., "instance", "network").
	Kind() Kind

	// Name returns the user-facing resource name.
	Name() string

	// IncusName returns the sanitized name for incus.
	IncusName() string

	// Priority returns the creation/deletion priority for dependency ordering.
	// Lower values are created first and deleted last.
	Priority() int

	// IsEnsured returns wherever the resource has been ensured.
	IsEnsured() bool

	// Created returns true if the resource was created during the last Ensure call.
	// Returns false if the resource already existed or hasn't been ensured yet.
	Created() bool
}

Resource defines the common interface for all Incus resources.

func FilterDuplicates 

func FilterDuplicates(resources []Resource) []Resource

FilterDuplicates filters duplicates out of Resources.

type ResourceStore 

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

ResourceStore provides storage for any BasicResource type.

func (*ResourceStore) Add 

func (s *ResourceStore) Add(r Resource)

Add appends a resource to the store.

func (*ResourceStore) All 

func (s *ResourceStore) All() []Resource

All returns all resources.

func (*ResourceStore) Get 

func (s *ResourceStore) Get(kind Kind, name string) Resource

Get retrieves a resource by kind and name. Returns nil if not found.

type Stack 

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

Stack manages a collection of resource operations. Resources are executed in priority order with proper dependency handling.

func NewStack 

func NewStack(p *Client, opts ...StackOption) *Stack

NewStack creates a new Stack for the given project.

func (*Stack) Add 

func (s *Stack) Add(resources ...Resource) *Stack

Add appends a resource operation to the stack.

func (*Stack) All 

func (s *Stack) All() []Resource

All returns all tasks in the stack.

func (*Stack) ForAction 

func (s *Stack) ForAction(action Action) *Stack

ForAction returns a new stack with resources filtered for the given action.

func (*Stack) Run 

func (s *Stack) Run(action Action, opts ...Option) error

Run executes all tasks in priority order. Returns aggregated errors from all failed operations.

Image tasks are executed in parallel using a worker pool. All other tasks are executed sequentially to respect potential dependencies.

type StackOption 

type StackOption func(*StackOptions)

StackOption configures stack options.

func StackSortDescending 

func StackSortDescending() StackOption

StackSortDescending sorts resources in descending priority order.

func StackWorkers 

func StackWorkers(w int) StackOption

StackWorkers sets the number of parallel workers.

type StackOptions 

type StackOptions struct {
	Workers        int
	SortDescending bool
}

StackOptions configures stack execution.

type StackRunArgs 

type StackRunArgs struct {
	Options

	// Workers is the number of parallel workers per batch (default: 4).
	Workers int
}

StackRunArgs holds arguments for Stack.Run().

type StartAble 

type StartAble interface {
	Start(opts ...Option) error
}

StartAble is implemented by resources that can be started.

type StopAble 

type StopAble interface {
	Stop(opts ...Option) error
}

StopAble is implemented by resources that can be stopped.

type StorageVolume 

type StorageVolume struct {
	*BaseResource

	Config StorageVolumeConfig

	// State - nil means not ensured.
	IncusVolume *incusApi.StorageVolume
	ETag        string
	// contains filtered or unexported fields
}

StorageVolume represents a custom storage volume with optional UID/GID shifting. Storage volumes provide persistent storage that can be attached to instances.

func (*StorageVolume) Created 

func (r *StorageVolume) Created() bool

Created returns true if the volume was created during the last Ensure call.

func (*StorageVolume) Delete 

func (r *StorageVolume) Delete(opts ...Option) error

Delete removes the storage volume from Incus.

func (*StorageVolume) Ensure 

func (r *StorageVolume) Ensure(opts ...Option) error

Ensure retrieves an existing storage volume or creates a new one if Create option is set.

func (*StorageVolume) IncusName 

func (r *StorageVolume) IncusName() string

IncusName returns the prefixed volume name used in Incus.

func (*StorageVolume) IsEnsured 

func (r *StorageVolume) IsEnsured() bool

IsEnsured returns true if the volume has been fetched/created.

func (*StorageVolume) String 

func (r *StorageVolume) String() string

String is for debugging.

type StorageVolumeConfig 

type StorageVolumeConfig struct {
	// Pool is the storage pool to create the volume in.
	// Defaults to ClientProject.Config.DefaultStoragePool.
	Pool string

	// Shifted enables UID/GID shifting for the volume.
	Shifted bool

	// UID is the initial UID for shifted volumes.
	UID uint32

	// GID is the initial GID for shifted volumes.
	GID uint32

	// ExtraConfig contains additional volume configuration options.
	ExtraConfig map[string]string
}

StorageVolumeConfig configures storage volume creation.

func (*StorageVolumeConfig) GetConfig 

func (c *StorageVolumeConfig) GetConfig() any

GetConfig returns the configuration.

type WorkerPool 

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

WorkerPool executes tasks concurrently with a limited number of workers.

func NewWorkerPool 

func NewWorkerPool(workers int) *WorkerPool

NewWorkerPool creates a new WorkerPool with the specified number of workers.

func (*WorkerPool) Run 

func (p *WorkerPool) Run(args PoolRunArgs) error

Run executes all submitted tasks using the worker pool. Returns aggregated errors from all failed tasks.

func (*WorkerPool) Submit 

func (p *WorkerPool) Submit(fn func() error)

Submit adds a task to the pool.

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.