tfexec

Documentation

Index

• func GetTestAccBackendS3Config(dir string) string
• func MatchTerraformVersion(ctx context.Context, tf TerraformCLI, constraints string) (bool, error)
• func SkipUnlessAcceptanceTestEnabled(t *testing.T)
• func UpdateTestAccSource(t *testing.T, tf TerraformCLI, source string)
• type Command
• type Executor
  • func NewExecutor(dir string, env []string) Executor
  • func NewMockExecutor(mockCommands []*mockCommand) Executor
  • func SetupTestAcc(t *testing.T, source string) Executor
• type ExitError
• type Plan
  • func NewPlan(b []byte) *Plan
  • func (p *Plan) Bytes() []byte
• type State
  • func NewState(b []byte) *State
  • func (s *State) Bytes() []byte
• type TerraformCLI
  • func NewTerraformCLI(e Executor) TerraformCLI
  • func SetupTestAccWithApply(t *testing.T, workspace string, source string) TerraformCLI

Functions

func GetTestAccBackendS3Config

func GetTestAccBackendS3Config(dir string) string

GetTestAccBackendS3Config returns mocked backend s3 config for testing. Its endpoint can be set via LOCALSTACK_ENDPOINT environment variable. default to "http://localhost:4566"

func MatchTerraformVersion

func MatchTerraformVersion(ctx context.Context, tf TerraformCLI, constraints string) (bool, error)

MatchTerraformVersion returns true if terraform version matches a given constraints.

func SkipUnlessAcceptanceTestEnabled

func SkipUnlessAcceptanceTestEnabled(t *testing.T)

SkipUnlessAcceptanceTestEnabled skips acceptance tests unless TEST_ACC is set to 1.

func UpdateTestAccSource

func UpdateTestAccSource(t *testing.T, tf TerraformCLI, source string)

UpdateTestAccSource updates a terraform configuration file with a given contents.

Types

type Command

type Command interface {
	// Run executes an arbitrary command.
	Run() error
	// Stdout returns outputs of stdout.
	Stdout() string
	// Stderr returns outputs of stderr.
	Stderr() string
	// Args returns args of the command.
	Args() []string
}

Command is an interface for wrapping os/exec.Cmd. Since the os/exec.Cmd is a struct, not an interface, we cannot mock it for testing, so we wrap it here. We implement only functions we need.

type Executor

type Executor interface {
	// NewCommandContext builds and returns an instance of Command.
	NewCommandContext(ctx context.Context, name string, args ...string) (Command, error)
	// Run executes a command.
	Run(cmd Command) error
	// Dir returns the current working directory.
	Dir() string
	// AppendEnv appends an environment variable.
	AppendEnv(key string, value string)
}

Executor abstracts the os command execution layer.

func NewExecutor

func NewExecutor(dir string, env []string) Executor

NewExecutor returns a default executor for real environments.

func NewMockExecutor

func NewMockExecutor(mockCommands []*mockCommand) Executor

NewMockExecutor returns a mock executor for testing.

func SetupTestAcc

func SetupTestAcc(t *testing.T, source string) Executor

SetupTestAcc is a common setup helper for acceptance tests.

type ExitError

type ExitError interface {
	// String returns a string represention of the error.
	String() string
	// Error returns a string useful for displaying error messages.
	Error() string
	// ExitCode returns a exit status code of the command.
	ExitCode() int
}

ExitError is an interface for wrapping os/exec.ExitError. We want to add helper methods we need.

type Plan

type Plan []byte

Plan is a named type for tfplan. We don't parse contents of tfplan to avoid depending on internal details, but we define it as a named type to clarify interface.

func NewPlan

func NewPlan(b []byte) *Plan

NewPlan returns a new Plan instance with a given content of tfplan.

func (*Plan) Bytes

func (p *Plan) Bytes() []byte

Bytes returns raw contents of tfstate as []byte.

type State

type State []byte

State is a named type for tfstate. We don't parse contents of tfstate to avoid depending on internal details, but we define it as a named type to clarify interface.

func NewState

func NewState(b []byte) *State

NewState returns a new State instance with a given content of tfstate.

func (*State) Bytes

func (s *State) Bytes() []byte

Bytes returns raw contents of tfstate as []byte.

type TerraformCLI

type TerraformCLI interface {
	// Verison returns a version number of Terraform.
	Version(ctx context.Context) (string, error)

	// Init initializes the current work directory.
	Init(ctx context.Context, opts ...string) error

	// Plan computes expected changes.
	// If a state is given, use it for the input state.
	Plan(ctx context.Context, state *State, opts ...string) (*Plan, error)

	// Apply applies changes.
	// If a plan is given, use it for the input plan.
	Apply(ctx context.Context, plan *Plan, opts ...string) error

	// Destroy destroys resources.
	Destroy(ctx context.Context, opts ...string) error

	// Import imports an existing resource to state.
	// If a state is given, use it for the input state.
	Import(ctx context.Context, state *State, address string, id string, opts ...string) (*State, error)

	// StateList shows a list of resources.
	// If a state is given, use it for the input state.
	StateList(ctx context.Context, state *State, addresses []string, opts ...string) ([]string, error)

	// StatePull returns the current tfstate from remote.
	StatePull(ctx context.Context, opts ...string) (*State, error)

	// StateMv moves resources from source to destination address.
	// If a state argument is given, use it for the input state.
	// If a stateOut argument is given, move resources from state to stateOut.
	// It returns updated the given state and the stateOut.
	StateMv(ctx context.Context, state *State, stateOut *State, source string, destination string, opts ...string) (*State, *State, error)

	// StateRm removes resources from state.
	// If a state is given, use it for the input state and return a new state.
	// Note that if the input state is not given, always return nil state,
	// becasuse the terraform state rm command doesn't have -state-out option.
	StateRm(ctx context.Context, state *State, addresses []string, opts ...string) (*State, error)

	// StatePush pushs a given State to remote.
	StatePush(ctx context.Context, state *State, opts ...string) error

	// Create a new workspace with name "workspace".
	WorkspaceNew(ctx context.Context, workspace string, opts ...string) error

	// Returns the current selected workspace.
	WorkspaceShow(ctx context.Context) (string, error)

	// Switch to the workspace with name "workspace". This workspace should already exist
	WorkspaceSelect(ctx context.Context, workspace string) error

	// Run is a low-level generic method for running an arbitrary terraform command.
	Run(ctx context.Context, args ...string) (string, string, error)

	// dir returns a working directory where terraform command is executed.
	Dir() string

	// SetExecPath customizes how the terraform command is executed. Default to terraform.
	// It's intended to inject a wrapper command such as direnv.
	SetExecPath(execPath string)

	// OverrideBackendToLocal switches the backend to local and returns a function
	// for swtich back it to remote with defer.
	// The -state flag for terraform command is not valid for remote state,
	// so we need to switch the backend to local for temporary state operations.
	// The filename argument must meet constraints for override file.
	// (e.g.) _tfexec_override.tf
	OverrideBackendToLocal(ctx context.Context, filename string, workspace string) (func(), error)

	// PlanHasChange is a helper method which runs plan and return true if the plan has change.
	PlanHasChange(ctx context.Context, state *State, opts ...string) (bool, error)
}

TerraformCLI is an interface for executing the terraform command. The main features of the terraform command are many of side effects, and the most of stdout may not be useful. In addition, the interfaces of state subcommands are inconsistent, and if a state file is required for the argument, we need a temporary file. However, It's hard to clean up the temporary file when an error occurs in the middle of a series of commands. This means implementing the exactly same interface for the terraform command doesn't make sense for us. So we wrap the terraform command and provider a high-level and easy-to-use interface which can be used in memory as much as possible. The interface is an opinionated, if it doesn't match you need, you can use Run(), which is a low-level generic method for running an arbitrary terraform command.

func NewTerraformCLI

func NewTerraformCLI(e Executor) TerraformCLI

NewTerraformCLI returns an implementation of the TerraformCLI interface.

func SetupTestAccWithApply

func SetupTestAccWithApply(t *testing.T, workspace string, source string) TerraformCLI

SetupTestAccWithApply is an acceptance test helper for initializing a temporary work directory and applying a given source.