local

Documentation

Index

• Constants
• func DefaultIntermediateStatePersistRule(info *IntermediateStatePersistInfo) bool
• func TestLocalProvider(t *testing.T, b *Local, name string, schema *terraform.ProviderSchema) *terraform.MockProvider
• func TestNewLocalNoDefault() backend.Backend
• func TestNewLocalSingle() backend.Backend
• type IntermediateStateConditionalPersister
• type IntermediateStatePersistInfo
• type Local
  • func New() *Local
  • func NewWithBackend(backend backend.Backend) *Local
  • func TestLocal(t *testing.T) *Local
  • func (b *Local) CLIInit(opts *backend.CLIOpts) error
  • func (b *Local) ConfigSchema() *configschema.Block
  • func (b *Local) Configure(obj cty.Value) tfdiags.Diagnostics
  • func (b *Local) DeleteWorkspace(name string, force bool) error
  • func (b *Local) LocalRun(op *backend.Operation) (*backend.LocalRun, statemgr.Full, tfdiags.Diagnostics)
  • func (b *Local) Operation(ctx context.Context, op *backend.Operation) (*backend.RunningOperation, error)
  • func (b *Local) PathsConflictWith(other *Local) bool
  • func (b *Local) PrepareConfig(obj cty.Value) (cty.Value, tfdiags.Diagnostics)
  • func (b *Local) StateMgr(name string) (statemgr.Full, error)
  • func (b *Local) StatePaths(name string) (stateIn, stateOut, backupOut string)
  • func (b *Local) Workspaces() ([]string, error)
• type StateHook
  • func (h *StateHook) PostStateUpdate(new *states.State) (terraform.HookAction, error)
  • func (h *StateHook) Stopping()
• type TestLocalNoDefaultState
  • func (b *TestLocalNoDefaultState) DeleteWorkspace(name string, force bool) error
  • func (b *TestLocalNoDefaultState) StateMgr(name string) (statemgr.Full, error)
  • func (b *TestLocalNoDefaultState) Workspaces() ([]string, error)
• type TestLocalSingleState
  • func (b *TestLocalSingleState) DeleteWorkspace(string, bool) error
  • func (b *TestLocalSingleState) StateMgr(name string) (statemgr.Full, error)
  • func (b *TestLocalSingleState) Workspaces() ([]string, error)

Constants

const (
	DefaultWorkspaceDir    = "terraform.tfstate.d"
	DefaultWorkspaceFile   = "environment"
	DefaultStateFilename   = "terraform.tfstate"
	DefaultBackupExtension = ".backup"
)

Functions

func DefaultIntermediateStatePersistRule

func DefaultIntermediateStatePersistRule(info *IntermediateStatePersistInfo) bool

DefaultIntermediateStatePersistRule is the default implementation of [IntermediateStateConditionalPersister.ShouldPersistIntermediateState] used when the selected state manager doesn't implement that interface.

Implementers of that interface can optionally wrap a call to this function if they want to combine the default behavior with some logic of their own.

func TestLocalProvider

func TestLocalProvider(t *testing.T, b *Local, name string, schema *terraform.ProviderSchema) *terraform.MockProvider

TestLocalProvider modifies the ContextOpts of the *Local parameter to have a provider with the given name.

func TestNewLocalNoDefault

func TestNewLocalNoDefault() backend.Backend

TestNewLocalNoDefault is a factory for creating a TestLocalNoDefaultState. This function matches the signature required for backend/init.

func TestNewLocalSingle

func TestNewLocalSingle() backend.Backend

TestNewLocalSingle is a factory for creating a TestLocalSingleState. This function matches the signature required for backend/init.

Types

type IntermediateStateConditionalPersister

type IntermediateStateConditionalPersister interface {
	// ShouldPersistIntermediateState will be called each time Terraform Core
	// emits an intermediate state event that is potentially eligible to be
	// persisted.
	//
	// The implemention should return true to signal that the state snapshot
	// most recently provided to the object's WriteState should be persisted,
	// or false if it should not be persisted. If this function returns true
	// then the receiver will see a subsequent call to
	// [statemgr.Persister.PersistState] to request persistence.
	//
	// The implementation must not modify anything reachable through the
	// arguments, and must not retain pointers to anything reachable through
	// them after the function returns. However, implementers can assume that
	// nothing will write to anything reachable through the arguments while
	// this function is active.
	ShouldPersistIntermediateState(info *IntermediateStatePersistInfo) bool
}

IntermediateStateConditionalPersister is an optional extension of statemgr.Persister that allows an implementation to tailor the rules for whether to create intermediate state snapshots when Terraform Core emits events reporting that the state might have changed.

For state managers that don't implement this interface, StateHook uses a default set of rules that aim to be a good compromise between how long a state change can be active before it gets committed as a snapshot vs. how many intermediate snapshots will get created. That compromise is subject to change over time, but a state manager can implement this interface to exert full control over those rules.

type IntermediateStatePersistInfo

type IntermediateStatePersistInfo struct {
	// RequestedPersistInterval is the persist interval requested by whatever
	// instantiated the StateHook.
	//
	// Implementations of [IntermediateStateConditionalPersister] should ideally
	// respect this, but may ignore it if they use something other than the
	// passage of time to make their decision.
	RequestedPersistInterval time.Duration

	// LastPersist is the time when the last intermediate state snapshot was
	// persisted, or the time of the first report for Terraform Core if there
	// hasn't yet been a persisted snapshot.
	LastPersist time.Time

	// ForcePersist is true when Terraform CLI has receieved an interrupt
	// signal and is therefore trying to create snapshots more aggressively
	// in anticipation of possibly being terminated ungracefully.
	// [IntermediateStateConditionalPersister] implementations should ideally
	// persist every snapshot they get when this flag is set, unless they have
	// some external information that implies this shouldn't be necessary.
	ForcePersist bool
}

type Local

type Local struct {
	// The State* paths are set from the backend config, and may be left blank
	// to use the defaults. If the actual paths for the local backend state are
	// needed, use the StatePaths method.
	//
	// 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.
	// Set this to "-" to disable state backup.
	//
	// StateWorkspaceDir is the path to the folder containing data for
	// non-default workspaces. This defaults to DefaultWorkspaceDir if not set.
	StatePath         string
	StateOutPath      string
	StateBackupPath   string
	StateWorkspaceDir string

	// The OverrideState* paths are set based on per-operation CLI arguments
	// and will override what'd be built from the State* fields if non-empty.
	// While the interpretation of the State* fields depends on the active
	// workspace, the OverrideState* fields are always used literally.
	OverrideStatePath       string
	OverrideStateOutPath    string
	OverrideStateBackupPath string

	// Terraform context. Many of these will be overridden or merged by
	// Operation. See Operation for more details.
	ContextOpts *terraform.ContextOpts

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

	// Backend, if non-nil, will use this backend for non-enhanced behavior.
	// This allows local behavior with remote state storage. It is a way to
	// "upgrade" a non-enhanced backend to an enhanced backend with typical
	// behavior.
	//
	// If this is nil, local performs normal state loading and storage.
	Backend backend.Backend
	// contains filtered or unexported fields
}

Local is an implementation of EnhancedBackend that performs all operations locally. This is the "default" backend and implements normal Terraform behavior as it is well known.

func New

func New() *Local

New returns a new initialized local backend.

func NewWithBackend

func NewWithBackend(backend backend.Backend) *Local

NewWithBackend returns a new local backend initialized with a dedicated backend for non-enhanced behavior.

func TestLocal

func TestLocal(t *testing.T) *Local

TestLocal returns a configured Local struct with temporary paths and in-memory ContextOpts.

No operations will be called on the returned value, so you can still set public fields without any locks.

func (*Local) CLIInit

func (b *Local) CLIInit(opts *backend.CLIOpts) error

backend.CLI impl.

func (*Local) ConfigSchema

func (b *Local) ConfigSchema() *configschema.Block

func (*Local) Configure

func (b *Local) Configure(obj cty.Value) tfdiags.Diagnostics

func (*Local) DeleteWorkspace

func (b *Local) DeleteWorkspace(name string, force bool) error

DeleteWorkspace removes a workspace.

The "default" workspace cannot be removed.

func (*Local) LocalRun

func (b *Local) LocalRun(op *backend.Operation) (*backend.LocalRun, statemgr.Full, tfdiags.Diagnostics)

backend.Local implementation.

func (*Local) Operation

func (b *Local) Operation(ctx context.Context, op *backend.Operation) (*backend.RunningOperation, error)

Operation implements backend.Enhanced

This will initialize an in-memory terraform.Context to perform the operation within this process.

The given operation parameter will be merged with the ContextOpts on the structure with the following rules. If a rule isn't specified and the name conflicts, assume that the field is overwritten if set.

func (*Local) PathsConflictWith

func (b *Local) PathsConflictWith(other *Local) bool

PathsConflictWith returns true if any state path used by a workspace in the receiver is the same as any state path used by the other given local backend instance.

This should be used when "migrating" from one local backend configuration to another in order to avoid deleting the "old" state snapshots if they are in the same files as the "new" state snapshots.

func (*Local) PrepareConfig

func (b *Local) PrepareConfig(obj cty.Value) (cty.Value, tfdiags.Diagnostics)

func (*Local) StateMgr

func (b *Local) StateMgr(name string) (statemgr.Full, error)

func (*Local) StatePaths

func (b *Local) StatePaths(name string) (stateIn, stateOut, backupOut string)

StatePaths returns the StatePath, StateOutPath, and StateBackupPath as configured from the CLI.

func (*Local) Workspaces

func (b *Local) Workspaces() ([]string, error)

type StateHook

type StateHook struct {
	terraform.NilHook
	sync.Mutex

	StateMgr statemgr.Writer

	// If PersistInterval is nonzero then for any new state update after
	// the duration has elapsed we'll try to persist a state snapshot
	// to the persistent backend too.
	// That's only possible if field Schemas is valid, because the
	// StateMgr.PersistState function for some backends needs schemas.
	PersistInterval time.Duration

	// Schemas are the schemas to use when persisting state due to
	// PersistInterval. This is ignored if PersistInterval is zero,
	// and PersistInterval is ignored if this is nil.
	Schemas *terraform.Schemas
	// contains filtered or unexported fields
}

StateHook is a hook that continuously updates the state by calling WriteState on a statemgr.Full.

func (*StateHook) PostStateUpdate

func (h *StateHook) PostStateUpdate(new *states.State) (terraform.HookAction, error)

func (*StateHook) Stopping

func (h *StateHook) Stopping()

type TestLocalNoDefaultState

type TestLocalNoDefaultState struct {
	*Local
}

TestLocalNoDefaultState is a backend implementation that wraps Local and modifies it to support named states, but not the default state. It returns ErrDefaultWorkspaceNotSupported when the DefaultStateName is used.

func (*TestLocalNoDefaultState) DeleteWorkspace

func (b *TestLocalNoDefaultState) DeleteWorkspace(name string, force bool) error

func (*TestLocalNoDefaultState) StateMgr

func (b *TestLocalNoDefaultState) StateMgr(name string) (statemgr.Full, error)

func (*TestLocalNoDefaultState) Workspaces

func (b *TestLocalNoDefaultState) Workspaces() ([]string, error)

type TestLocalSingleState

type TestLocalSingleState struct {
	*Local
}

TestLocalSingleState is a backend implementation that wraps Local and modifies it to only support single states (returns ErrWorkspacesNotSupported for multi-state operations).

This isn't an actual use case, this is exported just to provide a easy way to test that behavior.

func (*TestLocalSingleState) DeleteWorkspace

func (b *TestLocalSingleState) DeleteWorkspace(string, bool) error

func (*TestLocalSingleState) StateMgr

func (b *TestLocalSingleState) StateMgr(name string) (statemgr.Full, error)

func (*TestLocalSingleState) Workspaces

func (b *TestLocalSingleState) Workspaces() ([]string, error)