config

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Jun 15, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package config handles parsing and validation of incus-apply configuration files.

Index

Constants

View Source 
const DefaultFetchTimeout = 30 * time.Second

Variables

This section is empty.

Functions

func Interpolate 

func Interpolate(data []byte, env map[string]string) ([]byte, error)

Interpolate replaces variable references in data with values from env.

Supported syntax: 

$$               literal '$'
$VAR             value of VAR (empty string if not set)
${VAR}           value of VAR (empty string if not set)
${VAR:-default}  value of VAR if set and non-empty, otherwise default

func InterpolateDeclared 

func InterpolateDeclared(data []byte, env map[string]string) ([]byte, error)

InterpolateDeclared replaces only declared variable references in data. Undeclared variables are preserved as-is.

func InterpolateStrict 

func InterpolateStrict(data []byte, env map[string]string) ([]byte, error)

InterpolateStrict is like Interpolate but returns an error for undeclared variables.

func ResolveVars 

func ResolveVars(v Vars) (map[string]string, error)

ResolveVars builds a variable map from a VarsConfig document.

Resolution order (later sources win):

  1. Each path in Files, loaded in order via godotenv
  2. Each entry in Vars, applied in declaration order

Within this function, shell environment variables may be referenced via $VAR / ${VAR} syntax in files paths and in vars values.

Types

type Base 

type Base struct {
	Kind        string                    `yaml:"kind,omitempty" json:"kind,omitempty"`               // Resource kind: instance, profile, network, etc.
	Type        string                    `yaml:"-" json:"-"`                                         // Resolved kind (set by parser); not read from YAML
	Name        string                    `yaml:"name" json:"name"`                                   // Resource name (unique within type)
	Remote      string                    `yaml:"-" json:"-"`                                         // Incus remote name (set by executor; not read from YAML directly)
	Project     string                    `yaml:"-" json:"-"`                                         // Incus project (set by --project flag only; not read from YAML)
	Config      map[string]string         `yaml:"config,omitempty" json:"config,omitempty"`           // Key-value config options
	Devices     map[string]map[string]any `yaml:"devices,omitempty" json:"devices,omitempty"`         // Device configurations. Kept here for simplicity, only instances and profiles support devices.
	Description string                    `yaml:"description,omitempty" json:"description,omitempty"` // Resource description
	SourceFile  string                    `yaml:"-" json:"-"`                                         // Path to source file (set during parsing)
}

Base contains fields common to all Incus resource types.

type BoolVal added in v0.1.1 

type BoolVal string

BoolVal is a string type that can be unmarshaled from bool or template variable strings. It accepts any string value during parsing to support template variables like "${VAR}". Validation happens after interpolation via ValidateBoolVal().

func (BoolVal) Bool added in v0.1.1 

func (b BoolVal) Bool() bool

Bool returns the boolean value.

func (BoolVal) MarshalYAML added in v0.1.1 

func (b BoolVal) MarshalYAML() (any, error)

MarshalYAML converts BoolVal back to YAML as a boolean if it's a valid bool string.

func (BoolVal) String added in v0.1.1 

func (b BoolVal) String() string

String returns the string representation.

func (*BoolVal) UnmarshalYAML added in v0.1.1 

func (b *BoolVal) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML allows BoolVal to accept bool values or any string. String validation (for template variables) is deferred to after interpolation.

func (BoolVal) Validate added in v0.1.1 

func (b BoolVal) Validate() error

ValidateBoolVal validates a BoolVal after interpolation. Returns an error if the value is not a valid boolean string. Skips validation if the value is a template variable (starts with $ or ${).

type Discovery 

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

Discovery finds YAML and JSON configuration files containing incus resources.

func NewDiscovery 

func NewDiscovery(recursive bool) *Discovery

NewDiscovery creates a new file discovery instance. If recursive is true, directories are searched recursively.

func (Discovery) FindFiles 

func (d Discovery) FindFiles(paths []string) ([]string, error)

FindFiles finds all incus config files in the given paths. Paths can be individual files or directories. Returns a sorted, deduplicated list of absolute file paths.

type DynamicEntry added in v0.0.14 

type DynamicEntry struct {
	File   string `yaml:"file,omitempty"`   // read the file at this path as the value
	Incus  string `yaml:"incus,omitempty"`  // run: incus <args> and use stdout as the value
	Format string `yaml:"format,omitempty"` // output format: "" (raw) or "base64"
}

DynamicEntry defines how to resolve a single dynamic variable. Exactly one source processor (File, Incus) must be set. Format is applied to the raw output after resolution.

type EnvFileError 

type EnvFileError struct {
	Path string
	Err  error
}

EnvFileError is returned when an files entry cannot be read.

func (*EnvFileError) Error 

func (e *EnvFileError) Error() string

func (*EnvFileError) Unwrap 

func (e *EnvFileError) Unwrap() error

type FileResult 

type FileResult struct {
	SourceFile string
	Vars       []*Vars
	Resources  []*Resource
}

FileResult holds everything parsed from a single source (file, stdin, URL).

type InstanceFields added in v0.0.2 

type InstanceFields struct {
	Image     string   `yaml:"image,omitempty" json:"image,omitempty"`
	VM        BoolVal  `yaml:"vm,omitempty" json:"vm,omitempty"`
	Empty     bool     `yaml:"empty,omitempty" json:"empty,omitempty"`
	Ephemeral bool     `yaml:"ephemeral,omitempty" json:"ephemeral,omitempty"`
	Profiles  []string `yaml:"profiles,omitempty" json:"profiles,omitempty"`
	Storage   string   `yaml:"storage,omitempty" json:"storage,omitempty"`
	Network   string   `yaml:"network,omitempty" json:"network,omitempty"`
	Target    string   `yaml:"target,omitempty" json:"target,omitempty"`
	After     []string `yaml:"apply.after,omitempty" json:"apply.after,omitempty"`
}

InstanceFields captures the fields specific to Incus instances.

type NetworkACLFields added in v0.0.2 

type NetworkACLFields struct {
	Ingress []map[string]any `yaml:"ingress,omitempty" json:"ingress,omitempty"`
	Egress  []map[string]any `yaml:"egress,omitempty" json:"egress,omitempty"`
}

NetworkACLFields captures the fields specific to network ACLs.

type NetworkFields added in v0.0.2 

type NetworkFields struct {
	NetworkType string `yaml:"networkType,omitempty" json:"networkType,omitempty"`
}

NetworkFields captures the fields specific to networks.

type NetworkForwardFields added in v0.0.3 

type NetworkForwardFields struct {
	ListenAddress string           `yaml:"listen_address,omitempty" json:"listen_address,omitempty"`
	Ports         []map[string]any `yaml:"ports,omitempty" json:"ports,omitempty"`
}

NetworkForwardFields captures the fields specific to network forwards.

type Parser 

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

Parser handles parsing of YAML and JSON configuration files.

func NewParser 

func NewParser(timeout time.Duration) *Parser

NewParser creates a new config parser instance.

func (Parser) ParseFile 

func (p Parser) ParseFile(path string) (*FileResult, error)

ParseFile parses a single configuration file (YAML or JSON).

func (Parser) ParseStdin 

func (p Parser) ParseStdin(r io.Reader) (*FileResult, error)

ParseStdin parses configuration from stdin.

func (Parser) ParseURL 

func (p Parser) ParseURL(rawURL string) (*FileResult, error)

ParseURL fetches and parses configuration from a URL.

type Resource 

type Resource struct {
	Base                   `yaml:",inline"`
	InstanceFields         `yaml:",inline"`
	StoragePoolFields      `yaml:",inline"`
	StorageResourceFields  `yaml:",inline"`
	StorageBucketKeyFields `yaml:",inline"`
	NetworkFields          `yaml:",inline"`
	NetworkACLFields       `yaml:",inline"`
	NetworkForwardFields   `yaml:",inline"`

	PreviewRedactPrefixes []string `yaml:"-" json:"-"`
}

Resource represents a single resource configuration from a .yaml file. It embeds common fields plus the resource-specific field groups used based on the resource Type.

func (*Resource) QualifiedName added in v0.0.18 

func (r *Resource) QualifiedName() string

QualifiedName returns the remote-qualified resource name ("remote:name" or just "name" when no remote is set). Use this wherever the incus CLI accepts "[remote:]name" as the primary resource identifier.

func (*Resource) QualifiedNetwork added in v0.0.18 

func (r *Resource) QualifiedNetwork() string

QualifiedNetwork returns the remote-qualified network name ("remote:network" or just "network"). Use this for network-forward commands where the remote travels on the network argument rather than the listen address.

func (*Resource) QualifiedPool added in v0.0.18 

func (r *Resource) QualifiedPool() string

QualifiedPool returns the remote-qualified storage pool name ("remote:pool" or just "pool"). Use this for storage volume and bucket commands where the remote travels on the pool argument rather than the resource name.

func (Resource) Validate 

func (r Resource) Validate() error

Validate checks if required fields are present in the resource configuration.

type Stdin 

type Stdin struct {
	Config      map[string]string         `yaml:"config,omitempty"`
	Devices     map[string]map[string]any `yaml:"devices,omitempty"`
	Description string                    `yaml:"description,omitempty"`
	Profiles    []string                  `yaml:"profiles,omitempty"`
	Ingress     []map[string]any          `yaml:"ingress,omitempty"` // Network ACL ingress rules
	Egress      []map[string]any          `yaml:"egress,omitempty"`  // Network ACL egress rules
	Ports       []map[string]any          `yaml:"ports,omitempty"`   // Network forward port rules
}

Stdin represents configuration data passed to incus commands via stdin. Incus edit commands accept YAML on stdin to modify resource configuration.

type StorageBucketKeyFields added in v0.0.23 

type StorageBucketKeyFields struct {
	Bucket string `yaml:"bucket,omitempty" json:"bucket,omitempty"` // Parent bucket name
	Role   string `yaml:"role,omitempty" json:"role,omitempty"`     // Key role: "admin" or "read-only"
}

StorageBucketKeyFields captures the fields specific to storage bucket keys.

type StoragePoolFields added in v0.0.2 

type StoragePoolFields struct {
	Driver string `yaml:"driver,omitempty" json:"driver,omitempty"`
	Source string `yaml:"source,omitempty" json:"source,omitempty"`
}

StoragePoolFields captures the fields specific to storage pools.

type StorageResourceFields added in v0.0.2 

type StorageResourceFields struct {
	Pool        string `yaml:"pool,omitempty" json:"pool,omitempty"`
	ContentType string `yaml:"type,omitempty" json:"type,omitempty"` // --type flag for storage volume create (block or filesystem)
}

StorageResourceFields captures the fields specific to storage volumes and buckets.

type ValidationError 

type ValidationError struct {
	Field   string // The field that failed validation
	Message string // Description of the validation failure
}

ValidationError represents a field-level configuration validation error.

func (ValidationError) Error 

func (e ValidationError) Error() string

type Vars 

type Vars struct {
	Vars     map[string]string       `yaml:"vars,omitempty"`
	Computed map[string]DynamicEntry `yaml:"computed,omitempty"` // computed (dynamically resolved) variables
	Files    []string                `yaml:"files,omitempty"`    // .env files to load
	Global   bool                    `yaml:"global,omitempty"`

	SourceFile string `yaml:"-"`
}

Vars represents a `type: vars` document that declares variables for interpolation in resource configs within the same file (or globally).

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.