backend

Documentation

Overview

Package backend provides interfaces that the CLI uses to interact with Terraform. A backend provides the abstraction that allows the same CLI to simultaneously support both local and remote operations for seamlessly using Terraform in a team environment.

Index

• Constants
• Variables
• func TestBackendStateForceUnlock(t *testing.T, b1, b2 Backend)
• func TestBackendStateLocks(t *testing.T, b1, b2 Backend)
• func TestBackendStates(t *testing.T, b Backend)
• type Backend
  • func TestBackendConfig(t *testing.T, b Backend, c map[string]interface{}) Backend
• type CLI
• type CLIOpts
• type Enhanced
• type InitFn
• type Local
• type Nil
  • func (Nil) Configure(*terraform.ResourceConfig) error
  • func (Nil) DeleteState(string) error
  • func (Nil) Input(ui terraform.UIInput, c *terraform.ResourceConfig) (*terraform.ResourceConfig, error)
  • func (Nil) State(string) (state.State, error)
  • func (Nil) States() ([]string, error)
  • func (Nil) Validate(*terraform.ResourceConfig) ([]string, []error)
• type Operation
• type OperationType
  • func (i OperationType) String() string
• type RunningOperation

Constants

const DefaultStateName = "default"

DefaultStateName is the name of the default, initial state that every backend must have. This state cannot be deleted.

Variables

var (
	// ErrDefaultStateNotSupported is returned when an operation does not support
	// using the default state, but requires a named state to be selected.
	ErrDefaultStateNotSupported = errors.New("default state not supported\n" +
		"You can create a new workspace with the \"workspace new\" command.")

	// ErrNamedStatesNotSupported is returned when a named state operation
	// isn't supported.
	ErrNamedStatesNotSupported = errors.New("named states not supported")

	// ErrOperationNotSupported is returned when an unsupported operation
	// is detected by the configured backend.
	ErrOperationNotSupported = errors.New("operation not supported")
)

This must be returned rather than a custom error so that the Terraform CLI can detect it and handle it appropriately.

Functions

func TestBackendStateForceUnlock

func TestBackendStateForceUnlock(t *testing.T, b1, b2 Backend)

TestBackendStateForceUnlock verifies that the lock error is the expected type, and the lock can be unlocked using the ID reported in the error. Remote state backends that support -force-unlock should call this in at least one of the acceptance tests.

func TestBackendStateLocks

func TestBackendStateLocks(t *testing.T, b1, b2 Backend)

TestBackendStateLocks will test the locking functionality of the remote state backend.

func TestBackendStates

func TestBackendStates(t *testing.T, b Backend)

TestBackend will test the functionality of a Backend. The backend is assumed to already be configured. This will test state functionality. If the backend reports it doesn't support multi-state by returning the error ErrNamedStatesNotSupported, then it will not test that.

Types

type Backend

type Backend interface {
	// Ask for input and configure the backend. Similar to
	// terraform.ResourceProvider.
	Input(terraform.UIInput, *terraform.ResourceConfig) (*terraform.ResourceConfig, error)
	Validate(*terraform.ResourceConfig) ([]string, []error)
	Configure(*terraform.ResourceConfig) error

	// State returns the current state for this environment. This state may
	// not be loaded locally: the proper APIs should be called on state.State
	// to load the state. If the state.State is a state.Locker, it's up to the
	// caller to call Lock and Unlock as needed.
	//
	// If the named state doesn't exist it will be created. The "default" state
	// is always assumed to exist.
	State(name string) (state.State, error)

	// DeleteState removes the named state if it exists. It is an error
	// to delete the default state.
	//
	// DeleteState does not prevent deleting a state that is in use. It is the
	// responsibility of the caller to hold a Lock on the state when calling
	// this method.
	DeleteState(name string) error

	// States returns a list of configured named states.
	States() ([]string, error)
}

Backend is the minimal interface that must be implemented to enable Terraform.

func TestBackendConfig

func TestBackendConfig(t *testing.T, b Backend, c map[string]interface{}) Backend

TestBackendConfig validates and configures the backend with the given configuration.

type CLI

type CLI interface {
	Backend

	// CLIInit is called once with options. The options passed to this
	// function may not be modified after calling this since they can be
	// read/written at any time by the Backend implementation.
	//
	// This may be called before or after Configure is called, so if settings
	// here affect configurable settings, care should be taken to handle
	// whether they should be overwritten or not.
	CLIInit(*CLIOpts) error
}

CLI is an optional interface that can be implemented to be initialized with information from the Terraform CLI. If this is implemented, this initialization function will be called with data to help interact better with a CLI.

This interface was created to improve backend interaction with the official Terraform CLI while making it optional for API users to have to provide full CLI interaction to every backend.

If you're implementing a Backend, it is acceptable to require CLI initialization. In this case, your backend should be coded to error on other methods (such as State, Operation) if CLI initialization was not done with all required fields.

type CLIOpts

type CLIOpts struct {
	// CLI and Colorize control the CLI output. If CLI is nil then no CLI
	// output will be done. If CLIColor is nil then no coloring will be done.
	CLI      cli.Ui
	CLIColor *colorstring.Colorize

	// StatePath is the local path where state is read from.
	//
	// StateOutPath is the local path where the state will be written.
	// If this is empty, it will default to StatePath.
	//
	// StateBackupPath is the local path where a backup file will be written.
	// If this is empty, no backup will be taken.
	StatePath       string
	StateOutPath    string
	StateBackupPath string

	// ContextOpts are the base context options to set when initializing a
	// Terraform context. Many of these will be overridden or merged by
	// Operation. See Operation for more details.
	ContextOpts *terraform.ContextOpts

	// Input will ask for necessary input prior to performing any operations.
	//
	// Validation will perform validation prior to running an operation. The
	// variable naming doesn't match the style of others since we have a func
	// Validate.
	Input      bool
	Validation bool

	// RunningInAutomation indicates that commands are being run by an
	// automated system rather than directly at a command prompt.
	//
	// This is a hint not to produce messages that expect that a user can
	// run a follow-up command, perhaps because Terraform is running in
	// some sort of workflow automation tool that abstracts away the
	// exact commands that are being run.
	RunningInAutomation bool
}

CLIOpts are the options passed into CLIInit for the CLI interface.

These options represent the functionality the CLI exposes and often maps to meta-flags available on every CLI (such as -input).

When implementing a backend, it isn't expected that every option applies. Your backend should be documented clearly to explain to end users what options have an affect and what won't. In some cases, it may even make sense to error in your backend when an option is set so that users don't make a critically incorrect assumption about behavior.

type Enhanced

type Enhanced interface {
	Backend

	// Operation performs a Terraform operation such as refresh, plan, apply.
	// It is up to the implementation to determine what "performing" means.
	// This DOES NOT BLOCK. The context returned as part of RunningOperation
	// should be used to block for completion.
	// If the state used in the operation can be locked, it is the
	// responsibility of the Backend to lock the state for the duration of the
	// running operation.
	Operation(context.Context, *Operation) (*RunningOperation, error)
}

Enhanced implements additional behavior on top of a normal backend.

Enhanced backends allow customizing the behavior of Terraform operations. This allows Terraform to potentially run operations remotely, load configurations from external sources, etc.

type InitFn

type InitFn func() Backend

InitFn is used to initialize a new backend.

type Local

type Local interface {
	// Context returns a runnable terraform Context. The operation parameter
	// doesn't need a Type set but it needs other options set such as Module.
	Context(*Operation) (*terraform.Context, state.State, error)
}

Local implements additional behavior on a Backend that allows local operations in addition to remote operations.

This enables more behaviors of Terraform that require more data such as `console`, `import`, `graph`. These require direct access to configurations, variables, and more. Not all backends may support this so we separate it out into its own optional interface.

type Nil

type Nil struct{}

Nil is a no-op implementation of Backend.

This is useful to embed within another struct to implement all of the backend interface for testing.

func (Nil) Configure

func (Nil) Configure(*terraform.ResourceConfig) error

func (Nil) DeleteState

func (Nil) DeleteState(string) error

func (Nil) Input

func (Nil) Input(
	ui terraform.UIInput,
	c *terraform.ResourceConfig) (*terraform.ResourceConfig, error)

func (Nil) State

func (Nil) State(string) (state.State, error)

func (Nil) States

func (Nil) States() ([]string, error)

func (Nil) Validate

func (Nil) Validate(*terraform.ResourceConfig) ([]string, []error)

type Operation

type Operation struct {
	// Type is the operation to perform.
	Type OperationType

	// PlanId is an opaque value that backends can use to execute a specific
	// plan for an apply operation.
	//
	// PlanOutBackend is the backend to store with the plan. This is the
	// backend that will be used when applying the plan.
	PlanId         string
	PlanRefresh    bool   // PlanRefresh will do a refresh before a plan
	PlanOutPath    string // PlanOutPath is the path to save the plan
	PlanOutBackend *terraform.BackendState

	// Module settings specify the root module to use for operations.
	Module *module.Tree

	// Plan is a plan that was passed as an argument. This is valid for
	// plan and apply arguments but may not work for all backends.
	Plan *terraform.Plan

	// The options below are more self-explanatory and affect the runtime
	// behavior of the operation.
	AutoApprove  bool
	Destroy      bool
	DestroyForce bool
	ModuleDepth  int
	Parallelism  int
	Targets      []string
	Variables    map[string]interface{}

	// Input/output/control options.
	UIIn  terraform.UIInput
	UIOut terraform.UIOutput

	// If LockState is true, the Operation must Lock any
	// state.Lockers for its duration, and Unlock when complete.
	LockState bool

	// StateLocker is used to lock the state while providing UI feedback to the
	// user. This will be supplied by the Backend itself.
	StateLocker clistate.Locker

	// The duration to retry obtaining a State lock.
	StateLockTimeout time.Duration

	// Workspace is the name of the workspace that this operation should run
	// in, which controls which named state is used.
	Workspace string
}

An operation represents an operation for Terraform to execute.

Note that not all fields are supported by all backends and can result in an error if set. All backend implementations should show user-friendly errors explaining any incorrectly set values. For example, the local backend doesn't support a PlanId being set.

The operation options are purposely designed to have maximal compatibility between Terraform and Terraform Servers (a commercial product offered by HashiCorp). Therefore, it isn't expected that other implementation support every possible option. The struct here is generalized in order to allow even partial implementations to exist in the open, without walling off remote functionality 100% behind a commercial wall. Anyone can implement against this interface and have Terraform interact with it just as it would with HashiCorp-provided Terraform Servers.

type OperationType

type OperationType uint

OperationType is an enum used with Operation to specify the operation type to perform for Terraform.

const (
	OperationTypeInvalid OperationType = iota
	OperationTypeRefresh
	OperationTypePlan
	OperationTypeApply
)

func (OperationType) String

func (i OperationType) String() string

type RunningOperation

type RunningOperation struct {
	// For implementers of a backend, this context should not wrap the
	// passed in context. Otherwise, cancelling the parent context will
	// immediately mark this context as "done" but those aren't the semantics
	// we want: we want this context to be done only when the operation itself
	// is fully done.
	context.Context

	// Stop requests the operation to complete early, by calling Stop on all
	// the plugins. If the process needs to terminate immediately, call Cancel.
	Stop context.CancelFunc

	// Cancel is the context.CancelFunc associated with the embedded context,
	// and can be called to terminate the operation early.
	// Once Cancel is called, the operation should return as soon as possible
	// to avoid running operations during process exit.
	Cancel context.CancelFunc

	// Err is the error of the operation. This is populated after
	// the operation has completed.
	Err error

	// ExitCode can be used to set a custom exit code. This enables enhanced
	// backends to set specific exit codes that miror any remote exit codes.
	ExitCode int

	// PlanEmpty is populated after a Plan operation completes without error
	// to note whether a plan is empty or has changes.
	PlanEmpty bool

	// State is the final state after the operation completed. Persisting
	// this state is managed by the backend. This should only be read
	// after the operation completes to avoid read/write races.
	State *terraform.State
}

RunningOperation is the result of starting an operation.