gornir

Documentation

Overview

Package gornir implements the core functionality and define the needed interfaces to integrate with the framework

Index

• func TaskWrapper(ctx context.Context, logger Logger, processors Processors, wg *sync.WaitGroup, ...) error
• type Connection
• type FilterFunc
• type Gornir
  • func New() *Gornir
  • func (gr *Gornir) Clone() *Gornir
  • func (gr *Gornir) Filter(f FilterFunc) *Gornir
  • func (gr *Gornir) RunAsync(ctx context.Context, task Task, results chan *JobResult) error
  • func (gr *Gornir) RunSync(ctx context.Context, task Task) (chan *JobResult, error)
  • func (gr *Gornir) UUID() string
  • func (gr *Gornir) WithInventory(inv Inventory) *Gornir
  • func (gr *Gornir) WithLogger(l Logger) *Gornir
  • func (gr *Gornir) WithProcessor(p Processor) *Gornir
  • func (gr *Gornir) WithProcessors(p Processors) *Gornir
  • func (gr *Gornir) WithRunner(rnr Runner) *Gornir
  • func (gr *Gornir) WithUUID(u string) *Gornir
• type Host
  • func (h *Host) Err() error
  • func (h *Host) GetConnection(name string) (Connection, error)
  • func (h *Host) SetConnection(name string, conn Connection)
  • func (h *Host) SetErr(err error)
• type Inventory
  • func (i *Inventory) Filter(f FilterFunc) *Inventory
• type JobResult
  • func NewJobResult(ctx context.Context, host *Host, data interface{}, err error) *JobResult
  • func (r *JobResult) Context() context.Context
  • func (r *JobResult) Data() interface{}
  • func (r *JobResult) Err() error
  • func (r *JobResult) Host() *Host
  • func (r *JobResult) SetData(data interface{})
  • func (r *JobResult) SetErr(err error)
• type Logger
• type Processor
• type Processors
  • func (p Processors) TaskCompleted(ctx context.Context, logger Logger, task Task) error
  • func (p Processors) TaskInstanceCompleted(ctx context.Context, logger Logger, jobResult *JobResult, host *Host, ...) error
  • func (p Processors) TaskInstanceStarted(ctx context.Context, logger Logger, host *Host, task Task) error
  • func (p Processors) TaskStarted(ctx context.Context, logger Logger, task Task) error
• type Runner
• type Task
• type TaskInstanceResult
• type TaskMetadata

Functions

func TaskWrapper

func TaskWrapper(ctx context.Context, logger Logger, processors Processors, wg *sync.WaitGroup, task Task, host *Host, results chan *JobResult) error

TaskWrapper is a helper function that runs an instance of a task on a given host

Types

type Connection

type Connection interface {
	Close(context.Context) error // Close closes the connection
}

Connection defines an interface to write connection tasks

type FilterFunc

type FilterFunc func(*Host) bool

FilterFunc is a function that can be used to filter the inventory

type Gornir

type Gornir struct {
	Inventory  *Inventory // Inventory for the object
	Logger     Logger     // Logger for the object
	Runner     Runner     // Runner that will be used to run the task
	Processors Processors // Processors to be used during the execution
	// contains filtered or unexported fields
}

Gornir is the main object that glues everything together

func New

func New() *Gornir

New is a Gornir constructor. It is currently no different that new, however is a placeholder for any future defaults.

func (*Gornir) Clone

func (gr *Gornir) Clone() *Gornir

Clone returns a new instance of Gornir with the same attributes as the receiver

func (*Gornir) Filter

func (gr *Gornir) Filter(f FilterFunc) *Gornir

Filter creates a new Gornir with a filtered Inventory. It filters the hosts in the inventory returning a copy of the current Gornir instance but with only the hosts that passed the filter.

func (*Gornir) RunAsync

func (gr *Gornir) RunAsync(ctx context.Context, task Task, results chan *JobResult) error

RunAsync will execute the task over the hosts in the inventory using the given runner. This function doesn't block, the user can use the method Runnner.Wait instead. It's also up to the user to ensure the channel is closed and that Processors.TaskCompleted is called Note: It is up to the underlying task to check if the context is done

func (*Gornir) RunSync

func (gr *Gornir) RunSync(ctx context.Context, task Task) (chan *JobResult, error)

RunSync will execute the task over the hosts in the inventory using the given runner. This function will block until all the tasks are completed. Note: It is up to the underlying task to check if the context is done

func (*Gornir) UUID

func (gr *Gornir) UUID() string

UUID returns either the user defined uuid (if set) or a randomized one

func (*Gornir) WithInventory

func (gr *Gornir) WithInventory(inv Inventory) *Gornir

WithInventory returns a clone of the current Gornir but with the given inventory

func (*Gornir) WithLogger

func (gr *Gornir) WithLogger(l Logger) *Gornir

WithLogger returns a clone of the current Gornir but with the given logger

func (*Gornir) WithProcessor

func (gr *Gornir) WithProcessor(p Processor) *Gornir

WithProcessor returns a clone of the current Gornir but with the given Processor appended to the existing ones

func (*Gornir) WithProcessors

func (gr *Gornir) WithProcessors(p Processors) *Gornir

WithProcessors returns a clone of the current Gornir but with the given Processors

func (*Gornir) WithRunner

func (gr *Gornir) WithRunner(rnr Runner) *Gornir

WithRunner returns a clone of the current Gornir but with the given runner

func (*Gornir) WithUUID

func (gr *Gornir) WithUUID(u string) *Gornir

WithUUID returns a clone of the current Gornir but with the given UUID set. If not specifically set gornir will generate one dynamically on each Run

type Host

type Host struct {
	Port     uint16                 `yaml:"port"`     // Port to connect to
	Hostname string                 `yaml:"hostname"` // Hostname/FQDN/IP to connect to
	Username string                 `yaml:"username"` // Username to use for authentication purposes
	Password string                 `yaml:"password"` // Password to use for authentication purposes
	Platform string                 `yaml:"platform"` // Platform of the device
	Data     map[string]interface{} `yaml:"data"`     // Data belonging to the host
	// contains filtered or unexported fields
}

Host represent a host

func (*Host) Err

func (h *Host) Err() error

Err returns the stored error

func (*Host) GetConnection

func (h *Host) GetConnection(name string) (Connection, error)

GetConnection retrieves a connection that was previously set

func (*Host) SetConnection

func (h *Host) SetConnection(name string, conn Connection)

SetConnections stores a connection

func (*Host) SetErr

func (h *Host) SetErr(err error)

SetErr stores the error in the host

type Inventory

type Inventory struct {
	Hosts map[string]*Host // Hosts represents a collection of Hosts
}

Inventory represents a collection of Hosts

func (*Inventory) Filter

func (i *Inventory) Filter(f FilterFunc) *Inventory

Filter filters the hosts in the inventory returning a copy of the current Inventory instance but with only the hosts that passed the filter

type JobResult

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

JobResult is the result of running a task over a host.

func NewJobResult

func NewJobResult(ctx context.Context, host *Host, data interface{}, err error) *JobResult

NewJobResult instantiates a new JobResult

func (*JobResult) Context

func (r *JobResult) Context() context.Context

Context returns the context associated with the task

func (*JobResult) Data

func (r *JobResult) Data() interface{}

Data retrieves arbitrary data stored in the object

func (*JobResult) Err

func (r *JobResult) Err() error

Err returns the error the task set, otherwise nil

func (*JobResult) Host

func (r *JobResult) Host() *Host

Host returns the host associated to the result

func (*JobResult) SetData

func (r *JobResult) SetData(data interface{})

SetData let's you store arbitrary data in the object

func (*JobResult) SetErr

func (r *JobResult) SetErr(err error)

SetErr stores the error and also propagates it to the associated Host

type Logger

type Logger interface {
	Info(...interface{})                  // Info logs an informational message
	Debug(...interface{})                 // Debug logs a debug message
	Error(...interface{})                 // Error logs an error
	Warn(...interface{})                  // Warn logs a warning
	Fatal(...interface{})                 // Fatal logs a fatal event
	WithField(string, interface{}) Logger // WithField adds data to the logger
}

Logger defines the interface that a logger plugin can implement to provide logging capabilities

type Processor

type Processor interface {
	// TaskStarted is called before a task starts
	TaskStarted(context.Context, Logger, Task) error
	// TaskCompleted is called after all the TaskInstances have completed
	TaskCompleted(context.Context, Logger, Task) error
	// TaskInstanceStarted is called when a TaskInstance starts
	TaskInstanceStarted(context.Context, Logger, *Host, Task) error
	// TaskInstanceStarted is called after a TaskInstance completed
	TaskInstanceCompleted(context.Context, Logger, *JobResult, *Host, Task) error
}

Processor interface implements a set of methods that are called when certain events occur. This lets you tap into those events and process them easily as they occur.

To avoid confusions let's clarify the difference between a Task and a TaskInstance: - A Task refers to the idea of running a Task over your inventory - A TaskInstance refers to a single run of such task over an element of the Inventory.

For instance, if you call `gr.RunSync(MyTask)` and gr has 10 elements you will run a single Task and 10 TaskInstances

type Processors

type Processors []Processor

Processors stores a list of Processor that can be called during gornir's lifetime When Procerssors calls the methods of the same name of each Proccesor you have to take into account that: - It is done sequentially in the order they were defined - They are called in a blocking manner - If any returns an error the execution is interrupted so the rest won't be called

func (Processors) TaskCompleted

func (p Processors) TaskCompleted(ctx context.Context, logger Logger, task Task) error

TaskCompleted calls Processor's methods of the same name

func (Processors) TaskInstanceCompleted

func (p Processors) TaskInstanceCompleted(ctx context.Context, logger Logger, jobResult *JobResult, host *Host, task Task) error

TaskInstanceCompleted calls Processor's methods of the same name

func (Processors) TaskInstanceStarted

func (p Processors) TaskInstanceStarted(ctx context.Context, logger Logger, host *Host, task Task) error

TaskInstanceStarted calls Processor's methods of the same name

func (Processors) TaskStarted

func (p Processors) TaskStarted(ctx context.Context, logger Logger, task Task) error

TaskStarted calls Processor's methods of the same name

type Runner

type Runner interface {
	Run(context.Context, Logger, Processors, Task, map[string]*Host, chan *JobResult) error // Run executes the task over the hosts
	Close() error                                                                           // Close closes and cleans all objects associated with the runner
	Wait() error                                                                            // Wait blocks until all the hosts are done executing the task
}

Runner is the interface of a struct that can implement a strategy to run tasks over hosts

type Task

type Task interface {
	// Run method implements the business logic of the task
	Run(context.Context, Logger, *Host) (TaskInstanceResult, error)
	// Metadata returns some metadata information attached to the task
	Metadata() *TaskMetadata
}

Task is the interface that task plugins need to implement. the task is responsible to indicate its completion by calling sync.WaitGroup.Done()

type TaskInstanceResult

type TaskInstanceResult interface{}

TaskInstanceResult is the resut of running a task on a given host

type TaskMetadata

type TaskMetadata struct {
	Identifier string // Identifier of the task
}

TaskMetada includes some metadata about a given task