playbook

Documentation

Overview

Package playbook provides the base types and interfaces for creating automation playbooks using SSH-based remote execution.

Index

• Constants
• func CheckExists(client *ssh.Client, checkCmd string) bool
• func EnsureState(client *ssh.Client, checkCmd, applyCmd string) (bool, error)
• type BasePlaybook
  • func NewBasePlaybook() *BasePlaybook
  • func (b *BasePlaybook) Check() (bool, error)
  • func (b *BasePlaybook) GetArg(key string) string
  • func (b *BasePlaybook) GetArgs() map[string]string
  • func (b *BasePlaybook) GetConfig() config.NodeConfig
  • func (b *BasePlaybook) GetDescription() string
  • func (b *BasePlaybook) GetID() string
  • func (b *BasePlaybook) GetTimeout() time.Duration
  • func (b *BasePlaybook) IsDryRun() bool
  • func (b *BasePlaybook) Run() Result
  • func (b *BasePlaybook) SetArg(key, value string) PlaybookInterface
  • func (b *BasePlaybook) SetArgs(args map[string]string) PlaybookInterface
  • func (b *BasePlaybook) SetConfig(cfg config.NodeConfig) PlaybookInterface
  • func (b *BasePlaybook) SetDescription(description string) PlaybookInterface
  • func (b *BasePlaybook) SetDryRun(dryRun bool) PlaybookInterface
  • func (b *BasePlaybook) SetID(id string) PlaybookInterface
  • func (b *BasePlaybook) SetTimeout(timeout time.Duration) PlaybookInterface
• type PlaybookInterface
• type PlaybookOptions
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) GetPlaybookIDs() []string
  • func (r *Registry) PlaybookFindByID(id string) (PlaybookInterface, bool)
  • func (r *Registry) PlaybookList() []PlaybookInterface
  • func (r *Registry) PlaybookRegister(p PlaybookInterface)
• type Result

Constants

const (
	// IDPing checks SSH connectivity
	IDPing = "ping"

	// IDAptUpdate refreshes the package database
	IDAptUpdate = "apt-update"

	// IDAptUpgrade installs available updates
	IDAptUpgrade = "apt-upgrade"

	// IDAptStatus shows available updates
	IDAptStatus = "apt-status"

	// IDReboot reboots the server
	IDReboot = "reboot"

	// IDSwapCreate creates a swap file (requires "size" arg in GB)
	IDSwapCreate = "swap-create"

	// IDSwapDelete removes the swap file
	IDSwapDelete = "swap-delete"

	// IDSwapStatus shows swap status
	IDSwapStatus = "swap-status"

	// IDUserCreate creates a user with sudo (requires "username" arg)
	IDUserCreate = "user-create"

	// IDUserDelete deletes a user (requires "username" arg)
	IDUserDelete = "user-delete"

	// IDUserStatus shows user info (accepts optional "username" arg)
	IDUserStatus = "user-status"
)

Playbook ID constants for use with RunPlaybook. These constants provide compile-time safety and IDE autocomplete for playbook IDs.

Example:

node := ork.NewNodeForHost("server.example.com")
err := node.RunPlaybook(playbook.IDPing)

Functions

func CheckExists

func CheckExists(client *ssh.Client, checkCmd string) bool

CheckExists runs a check command and returns true if the command succeeds. This is useful for checking if a file exists, a service is running, etc. Returns false if the command fails or produces no output.

func EnsureState

func EnsureState(client *ssh.Client, checkCmd, applyCmd string) (bool, error)

EnsureState ensures a desired state by running a check command first. If the check fails, it runs the apply command to achieve the desired state. Returns true if changes were made (apply was run), false if no changes needed. Returns an error if either command fails.

Types

type BasePlaybook

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

BasePlaybook provides default implementations of the PlaybookInterface. Embed this in your playbook struct to get boilerplate getter/setter methods. Only implement Check() and Run() for the specific playbook logic.

Example usage:

type MyPlaybook struct {
    *BasePlaybook
}

func NewMyPlaybook() *MyPlaybook {
    return &MyPlaybook{
        BasePlaybook: playbook.NewBasePlaybook().
            SetID("my-playbook").
            SetDescription("What this playbook does"),
    }
}

func (m *MyPlaybook) Check() (bool, error) {
    // Check if changes are needed
}

func (m *MyPlaybook) Run() Result {
    // Execute the playbook
}

func NewBasePlaybook

func NewBasePlaybook() *BasePlaybook

NewBasePlaybook creates a new BasePlaybook with default values. Use the setter methods to configure it before returning from your constructor.

func (*BasePlaybook) Check

func (b *BasePlaybook) Check() (bool, error)

Check is a stub that embedding types must override.

func (*BasePlaybook) GetArg

func (b *BasePlaybook) GetArg(key string) string

GetArg retrieves a single argument value by key.

func (*BasePlaybook) GetArgs

func (b *BasePlaybook) GetArgs() map[string]string

GetArgs returns the entire arguments map.

func (*BasePlaybook) GetConfig

func (b *BasePlaybook) GetConfig() config.NodeConfig

GetConfig returns the current node configuration for this playbook.

func (*BasePlaybook) GetDescription

func (b *BasePlaybook) GetDescription() string

GetDescription returns a short description of what the playbook does.

func (*BasePlaybook) GetID

func (b *BasePlaybook) GetID() string

GetID returns the unique identifier for this playbook.

func (*BasePlaybook) GetTimeout

func (b *BasePlaybook) GetTimeout() time.Duration

GetTimeout returns the maximum duration for playbook execution.

func (*BasePlaybook) IsDryRun

func (b *BasePlaybook) IsDryRun() bool

IsDryRun returns true if this is a dry-run execution.

func (*BasePlaybook) Run

func (b *BasePlaybook) Run() Result

Run is a stub that embedding types must override.

func (*BasePlaybook) SetArg

func (b *BasePlaybook) SetArg(key, value string) PlaybookInterface

SetArg sets a single argument value. Returns PlaybookInterface for fluent method chaining.

func (*BasePlaybook) SetArgs

func (b *BasePlaybook) SetArgs(args map[string]string) PlaybookInterface

SetArgs replaces the entire arguments map. Returns PlaybookInterface for fluent method chaining.

func (*BasePlaybook) SetConfig

func (b *BasePlaybook) SetConfig(cfg config.NodeConfig) PlaybookInterface

SetConfig sets the node configuration for this playbook execution. Returns PlaybookInterface for fluent method chaining with embedding types.

func (*BasePlaybook) SetDescription

func (b *BasePlaybook) SetDescription(description string) PlaybookInterface

SetDescription sets a short description of what the playbook does. Returns PlaybookInterface for fluent method chaining with embedding types.

func (*BasePlaybook) SetDryRun

func (b *BasePlaybook) SetDryRun(dryRun bool) PlaybookInterface

SetDryRun sets whether to simulate execution without making changes. Returns PlaybookInterface for fluent method chaining.

func (*BasePlaybook) SetID

func (b *BasePlaybook) SetID(id string) PlaybookInterface

SetID sets the unique identifier for this playbook. Returns PlaybookInterface for fluent method chaining with embedding types.

func (*BasePlaybook) SetTimeout

func (b *BasePlaybook) SetTimeout(timeout time.Duration) PlaybookInterface

SetTimeout sets the maximum duration for playbook execution. Returns PlaybookInterface for fluent method chaining.

type PlaybookInterface

type PlaybookInterface interface {
	// GetID returns the unique identifier for this playbook (e.g., "apt-update")
	GetID() string

	// SetID sets the unique identifier for this playbook.
	SetID(id string) PlaybookInterface

	// GetDescription returns a short description of what the playbook does
	GetDescription() string

	// SetDescription sets a short description of what the playbook does.
	SetDescription(description string) PlaybookInterface

	// GetConfig returns the current node configuration for this playbook.
	GetConfig() config.NodeConfig

	// SetConfig sets the node configuration for this playbook execution.
	// Returns the PlaybookInterface for fluent method chaining.
	SetConfig(cfg config.NodeConfig) PlaybookInterface

	// GetArg retrieves a single argument value by key.
	GetArg(key string) string

	// SetArg sets a single argument value.
	// Returns the PlaybookInterface for fluent method chaining.
	SetArg(key, value string) PlaybookInterface

	// GetArgs returns the entire arguments map.
	GetArgs() map[string]string

	// SetArgs replaces the entire arguments map.
	// Returns the PlaybookInterface for fluent method chaining.
	SetArgs(args map[string]string) PlaybookInterface

	// IsDryRun returns true if this is a dry-run execution.
	IsDryRun() bool

	// SetDryRun sets whether to simulate execution without making changes.
	// Returns the PlaybookInterface for fluent method chaining.
	SetDryRun(dryRun bool) PlaybookInterface

	// GetTimeout returns the maximum duration for playbook execution.
	GetTimeout() time.Duration

	// SetTimeout sets the maximum duration for playbook execution.
	// Returns the PlaybookInterface for fluent method chaining.
	SetTimeout(timeout time.Duration) PlaybookInterface

	// Check determines if the playbook needs to make any changes.
	// Uses the config and options set via SetConfig/SetOptions.
	// Returns true if changes are needed, false if the system is already in the desired state.
	// Returns an error if the check itself fails.
	Check() (bool, error)

	// Run executes the playbook and returns a detailed result.
	// Uses the config and options set via SetConfig/SetOptions.
	// The Result.Changed field indicates whether any changes were made.
	Run() Result
}

PlaybookInterface is the interface that all playbooks must implement. A playbook is a self-contained automation task that runs on a remote server. All playbooks support idempotency through the Check() method and Result return value.

Usage:

pb := playbooks.NewUserCreate().
    SetConfig(cfg).
    SetOptions(&playbook.PlaybookOptions{Args: map[string]string{"username": "alice"}})

needsRun, _ := pb.Check()
result := pb.Run()

type PlaybookOptions

type PlaybookOptions struct {
	// Args contains playbook-specific variables that override node-level arguments.
	// These are merged with node-level args (playbook args take precedence).
	Args map[string]string

	// DryRun indicates whether to simulate execution without making changes.
	// When true, the playbook should preview what would be done.
	DryRun bool

	// Timeout specifies the maximum duration for playbook execution.
	// Zero means no timeout.
	Timeout time.Duration
}

PlaybookOptions provides configuration options for playbook execution. This allows per-playbook variable scoping and additional execution controls.

type Registry

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

Registry holds a collection of playbooks.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates a new playbook registry.

func (*Registry) GetPlaybookIDs

func (r *Registry) GetPlaybookIDs() []string

GetPlaybookIDs returns all registered playbook IDs.

func (*Registry) PlaybookFindByID

func (r *Registry) PlaybookFindByID(id string) (PlaybookInterface, bool)

PlaybookFindByID retrieves a playbook by ID.

func (*Registry) PlaybookList

func (r *Registry) PlaybookList() []PlaybookInterface

PlaybookList returns all registered playbooks.

func (*Registry) PlaybookRegister

func (r *Registry) PlaybookRegister(p PlaybookInterface)

PlaybookRegister adds a playbook to the registry.

type Result

type Result struct {
	// Changed indicates whether the playbook made any changes to the system.
	// false means the system was already in the desired state.
	// true means the playbook modified the system.
	Changed bool

	// Message is a human-readable description of what happened.
	Message string

	// Details contains additional information about the execution.
	// Keys are field names, values are string representations.
	Details map[string]string

	// Error is non-nil if the playbook failed to execute.
	// When Error is non-nil, Changed may be true if some changes occurred before the failure.
	Error error
}

Result represents the outcome of a playbook execution. It indicates whether any changes were made and provides details about the execution.