workflow

Documentation

Overview

Package workflow orchestrates multi-step VM provisioning (plan/apply/verify/rollback).

Index

• type Change
• type MultiNodeWorkflow
  • func NewMultiNodeWorkflow(cfg *config.Env, client *proxmox.Client, rnd *kickstart.Renderer, ...) *MultiNodeWorkflow
  • func (m *MultiNodeWorkflow) Apply(ctx context.Context) error
  • func (m *MultiNodeWorkflow) Down(ctx context.Context, force bool) error
  • func (m *MultiNodeWorkflow) Plan(ctx context.Context) (map[string][]Change, error)
  • func (m *MultiNodeWorkflow) Rollback(ctx context.Context) error
  • func (m *MultiNodeWorkflow) Up(ctx context.Context) error
  • func (m *MultiNodeWorkflow) Verify(ctx context.Context) error
• type NodeResult
• type SingleVMWorkflow
  • func (w *SingleVMWorkflow) Apply(ctx context.Context, changes []Change) error
  • func (w *SingleVMWorkflow) Down(ctx context.Context, force bool) error
  • func (w *SingleVMWorkflow) Plan(ctx context.Context) ([]Change, error)
  • func (w *SingleVMWorkflow) Rollback(ctx context.Context, _ []Change) error
  • func (w *SingleVMWorkflow) Up(ctx context.Context) error
  • func (w *SingleVMWorkflow) Verify(ctx context.Context) error

Types

type Change

type Change struct {
	Kind        string
	Target      string
	Description string
	Details     map[string]any
}

Change is a single unit of work in the plan.

type MultiNodeWorkflow

type MultiNodeWorkflow struct {
	Config   *config.Env
	Client   *proxmox.Client
	Renderer *kickstart.Renderer
	Builder  *kickstart.ISOBuilder
	DryRun   bool

	// MaxConcurrency caps concurrent per-node Apply goroutines. <=0 → 4.
	MaxConcurrency int
	// ContinueOnError keeps running other nodes when one fails.
	ContinueOnError bool
	// ISOUploadMu serializes ISO uploads across nodes. If nil, one is allocated
	// internally.
	ISOUploadMu *sync.Mutex
}

MultiNodeWorkflow fans one env manifest out to many nodes, each driven by an internal SingleVMWorkflow. VM creation and boot run in parallel; the shared install-ISO / kickstart-ISO upload path is serialized by ISOUploadMu to avoid racing the Proxmox storage upload endpoint.

func NewMultiNodeWorkflow

func NewMultiNodeWorkflow(cfg *config.Env, client *proxmox.Client, rnd *kickstart.Renderer, builder *kickstart.ISOBuilder) *MultiNodeWorkflow

NewMultiNodeWorkflow is a small factory that fills sensible defaults.

func (*MultiNodeWorkflow) Apply

func (m *MultiNodeWorkflow) Apply(ctx context.Context) error

Apply runs per-node Apply concurrently using errgroup + a semaphore. In fail-fast mode, the first error cancels the context. ContinueOnError keeps remaining nodes running and aggregates errors.

func (*MultiNodeWorkflow) Down

func (m *MultiNodeWorkflow) Down(ctx context.Context, force bool) error

Down tears down every node. Reverse-alphabetical order so network-ish names (e.g. "net-*") come down after VM nodes in typical conventions.

func (*MultiNodeWorkflow) Plan

func (m *MultiNodeWorkflow) Plan(ctx context.Context) (map[string][]Change, error)

Plan computes per-node change sets sequentially (plan is cheap, read-only). The result is keyed by node name.

func (*MultiNodeWorkflow) Rollback

func (m *MultiNodeWorkflow) Rollback(ctx context.Context) error

Rollback reverses in-flight Apply best-effort across all nodes. Errors are aggregated so the caller sees everything that failed.

func (*MultiNodeWorkflow) Up

func (m *MultiNodeWorkflow) Up(ctx context.Context) error

Up runs Plan → Apply → Verify honouring DryRun. Verify failures are reported as warnings (matching SingleVMWorkflow.Up).

func (*MultiNodeWorkflow) Verify

func (m *MultiNodeWorkflow) Verify(ctx context.Context) error

Verify runs per-node Verify concurrently, aggregating errors.

type NodeResult

type NodeResult struct {
	Node    string
	Success bool
	Err     error
	Changes []Change
}

NodeResult captures per-node execution outcome.

type SingleVMWorkflow

type SingleVMWorkflow struct {
	Config   *config.Env
	NodeName string
	Client   *proxmox.Client
	Renderer *kickstart.Renderer
	Builder  *kickstart.ISOBuilder
	DryRun   bool
	// UploadMu serializes the upload-iso step across callers that share a
	// Proxmox storage endpoint (multi-node Apply). Optional.
	UploadMu *sync.Mutex
}

SingleVMWorkflow provisions exactly one node from an env manifest.

func (*SingleVMWorkflow) Apply

func (w *SingleVMWorkflow) Apply(ctx context.Context, changes []Change) error

Apply executes the given change set.

func (*SingleVMWorkflow) Down

func (w *SingleVMWorkflow) Down(ctx context.Context, force bool) error

Down tears the VM down.

func (*SingleVMWorkflow) Plan

func (w *SingleVMWorkflow) Plan(ctx context.Context) ([]Change, error)

Plan computes the change set without side effects.

func (*SingleVMWorkflow) Rollback

func (w *SingleVMWorkflow) Rollback(ctx context.Context, _ []Change) error

Rollback reverses an in-flight Apply. Best-effort destroy.

func (*SingleVMWorkflow) Up

func (w *SingleVMWorkflow) Up(ctx context.Context) error

Up is Plan → Apply → Verify (best-effort).

func (*SingleVMWorkflow) Verify

func (w *SingleVMWorkflow) Verify(ctx context.Context) error

Verify checks post-apply state.