terraform

Documentation

Overview

Package terraform handles the execution of terraform processes to bring up the infrastructure for the Lokomotive cluster.

Index

• Constants
• Variables
• func Configure(assetDir, renderedBackend string) error
• func GetTerraformRootDir(assetDir string) string
• type Config
• type ExecutionHook
• type ExecutionStatus
• type ExecutionStep
• type Executor
  • func NewExecutor(conf Config) (*Executor, error)
  • func (ex *Executor) Apply(extraArgs []string) error
  • func (ex *Executor) Destroy() error
  • func (ex *Executor) Execute(steps ...ExecutionStep) error
  • func (ex *Executor) Init() error
  • func (ex *Executor) LoadVars() (map[string]interface{}, error)
  • func (ex *Executor) Output(key string, s interface{}) error
  • func (ex *Executor) Plan() error
  • func (ex *Executor) Status(id int) (ExecutionStatus, error)
  • func (ex *Executor) WorkingDirectory() string

Constants

const (

	// WithoutParallelism sets the parallelism value to 1.
	WithoutParallelism = "-parallelism=1"
	// WithParallelism sets the parallelism value to 100.
	WithParallelism = "-parallelism=100"
)

Variables

var ErrBinaryNotFound = errors.New(
	"Terraform not in executable's folder, cwd nor PATH",
)

ErrBinaryNotFound denotes the fact that the Terraform binary could not be found on disk.

Functions

func Configure

func Configure(assetDir, renderedBackend string) error

Configure creates Terraform directories and modules as well as a Terraform backend file if provided by the user.

func GetTerraformRootDir

func GetTerraformRootDir(assetDir string) string

GetTerraformRootDir gets the Terraform directory path.

Types

type Config

type Config struct {
	WorkingDir string
	Verbose    bool
}

A configuration struct for program information such as the current working directory and command-line arguments.

type ExecutionHook

type ExecutionHook func(*Executor) error

ExecutionHook represents a callback function which should be run prior to executing a Terraform operation.

type ExecutionStatus

type ExecutionStatus string

ExecutionStatus describes whether an execution succeeded, failed or is still in progress.

const (
	// ExecutionStatusUnknown indicates that the status of execution is unknown.
	ExecutionStatusUnknown ExecutionStatus = "Unknown"
	// ExecutionStatusRunning indicates that the the execution is still in
	// process.
	ExecutionStatusRunning ExecutionStatus = "Running"
	// ExecutionStatusSuccess indicates that the execution succeeded.
	ExecutionStatusSuccess ExecutionStatus = "Success"
	// ExecutionStatusFailure indicates that the execution failed.
	ExecutionStatusFailure ExecutionStatus = "Failure"
)

type ExecutionStep

type ExecutionStep struct {
	// A short string describing the step in a way that is meaningful to the user. The string
	// should begin with a lowercase letter, be in the imperative tense and have no period at the
	// end.
	//
	// Examples:
	// - "create DNS resources"
	// - "deploy virtual machines"
	Description string
	// A list of arguments to be passed to the `terraform` command. Note that for "apply"
	// operations the "-auto-approve" argument should always be included to avoid halting the
	// Terraform execution with interactive prompts.
	//
	// Examples:
	// - []string{"apply", "-target=module.foo", "-auto-approve"}
	// - []string{"refresh"}
	// - []string{"apply", "-auto-approve"}
	Args []string
	// A function which should be run prior to executing the Terraform operation. If specified and
	// the function returns an error, execution is halted.
	PreExecutionHook ExecutionHook
}

ExecutionStep represents a single Terraform operation.

type Executor

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

Executor enables calling Terraform from Go, across platforms, with any additional providers/provisioners that the currently executing binary exposes.

The Terraform binary is expected to be in the executing binary's folder, in the current working directory or in the PATH. Each Executor runs in a temporary folder, so each Executor should only be used for one TF project.

TODO: Ideally, we would use Terraform as a Go library, so we can monitor a hook and report the current state in real-time when Apply/Refresh/Destroy are used. While technically possible today, because Terraform currently hides the providers/provisioners list construction in their main package, it would require to reproduce a bunch of their logic, which is out of the scope of the first-version of the Executor. With a bit of efforts, we could actually even stop requiring having a Terraform binary altogether, by linking the builtin providers/provisioners to this particular binary and re-implemeting the routing here. Alternatively, we could contribute upstream to add a 'debug' flag that would enable a hook that would expose the live state to a file (or else).

func NewExecutor

func NewExecutor(conf Config) (*Executor, error)

NewExecutor initializes a new Executor.

func (*Executor) Apply

func (ex *Executor) Apply(extraArgs []string) error

Apply is a wrapper function that runs `terraform apply -auto-approve`.

func (*Executor) Destroy

func (ex *Executor) Destroy() error

Destroy is a wrapper function that runs `terraform destroy -auto-approve`.

func (*Executor) Execute

func (ex *Executor) Execute(steps ...ExecutionStep) error

Execute accepts one or more ExecutionSteps and executes them sequentially in the order they were provided. If a step has a PreExecutionHook defined, the hook is run prior to executing the step. If any error is encountered, the error is returned and the execution is halted.

func (*Executor) Init

func (ex *Executor) Init() error

Init is a wrapper function that runs `terraform init`.

func (*Executor) LoadVars

func (ex *Executor) LoadVars() (map[string]interface{}, error)

LoadVars is a convenience function to load the tfvars file into memory as a JSON object.

func (*Executor) Output

func (ex *Executor) Output(key string, s interface{}) error

Output gets output value from Terraform in JSON format and tries to unmarshal it to a given struct.

func (*Executor) Plan

func (ex *Executor) Plan() error

Plan runs 'terraform plan'.

func (*Executor) Status

func (ex *Executor) Status(id int) (ExecutionStatus, error)

Status returns the status of a given execution process.

An error can be returned if the running processes could not be listed, or if the process failed, in which case the exit message is returned in an error of type ExecutionError.

Note that if the identifier is invalid, the current implementation will return ExecutionStatusSuccess rather than ExecutionStatusUnknown.

func (*Executor) WorkingDirectory

func (ex *Executor) WorkingDirectory() string

WorkingDirectory returns the directory in which Terraform runs, which can be useful for inspection or to retrieve any generated files.