state

Documentation

Index

• func LockWithContext(ctx context.Context, s State, info *LockInfo) (string, error)
• func TestState(t *testing.T, s State)
• func TestStateInitial() *terraform.State
• type BackupState
  • func (s *BackupState) Lock(info *LockInfo) (string, error)
  • func (s *BackupState) PersistState() error
  • func (s *BackupState) RefreshState() error
  • func (s *BackupState) State() *terraform.State
  • func (s *BackupState) Unlock(id string) error
  • func (s *BackupState) WriteState(state *terraform.State) error
• type InmemState
  • func (s *InmemState) Lock(*LockInfo) (string, error)
  • func (s *InmemState) PersistState() error
  • func (s *InmemState) RefreshState() error
  • func (s *InmemState) State() *terraform.State
  • func (s *InmemState) Unlock(string) error
  • func (s *InmemState) WriteState(state *terraform.State) error
• type LocalState
  • func (s *LocalState) Lock(info *LockInfo) (string, error)
  • func (s *LocalState) PersistState() error
  • func (s *LocalState) RefreshState() error
  • func (s *LocalState) SetState(state *terraform.State)
  • func (s *LocalState) State() *terraform.State
  • func (s *LocalState) Unlock(id string) error
  • func (s *LocalState) WriteState(state *terraform.State) error
• type LockDisabled
  • func (s *LockDisabled) Lock(info *LockInfo) (string, error)
  • func (s *LockDisabled) PersistState() error
  • func (s *LockDisabled) RefreshState() error
  • func (s *LockDisabled) State() *terraform.State
  • func (s *LockDisabled) Unlock(id string) error
  • func (s *LockDisabled) WriteState(v *terraform.State) error
• type LockError
  • func (e *LockError) Error() string
• type LockInfo
  • func NewLockInfo() *LockInfo
  • func (l *LockInfo) Err() error
  • func (l *LockInfo) Marshal() []byte
  • func (l *LockInfo) String() string
• type Locker
• type State
• type StatePersister
• type StateReader
• type StateRefresher
• type StateWriter

Functions

func LockWithContext

func LockWithContext(ctx context.Context, s State, info *LockInfo) (string, error)

Lock the state, using the provided context for timeout and cancellation. This backs off slightly to an upper limit.

func TestState

func TestState(t *testing.T, s State)

TestState is a helper for testing state implementations. It is expected that the given implementation is pre-loaded with the TestStateInitial state.

func TestStateInitial

func TestStateInitial() *terraform.State

TestStateInitial is the initial state that a State should have for TestState.

Types

type BackupState

type BackupState struct {
	Real State
	Path string
	// contains filtered or unexported fields
}

BackupState wraps a State that backs up the state on the first time that a WriteState or PersistState is called.

If Path exists, it will be overwritten.

func (*BackupState) Lock

func (s *BackupState) Lock(info *LockInfo) (string, error)

func (*BackupState) PersistState

func (s *BackupState) PersistState() error

func (*BackupState) RefreshState

func (s *BackupState) RefreshState() error

func (*BackupState) State

func (s *BackupState) State() *terraform.State

func (*BackupState) Unlock

func (s *BackupState) Unlock(id string) error

func (*BackupState) WriteState

func (s *BackupState) WriteState(state *terraform.State) error

type InmemState

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

InmemState is an in-memory state storage.

func (*InmemState) Lock

func (s *InmemState) Lock(*LockInfo) (string, error)

func (*InmemState) PersistState

func (s *InmemState) PersistState() error

func (*InmemState) RefreshState

func (s *InmemState) RefreshState() error

func (*InmemState) State

func (s *InmemState) State() *terraform.State

func (*InmemState) Unlock

func (s *InmemState) Unlock(string) error

func (*InmemState) WriteState

func (s *InmemState) WriteState(state *terraform.State) error

type LocalState

type LocalState struct {

	// Path is the path to read the state from. PathOut is the path to
	// write the state to. If PathOut is not specified, Path will be used.
	// If PathOut already exists, it will be overwritten.
	Path    string
	PathOut string
	// contains filtered or unexported fields
}

LocalState manages a state storage that is local to the filesystem.

func (*LocalState) Lock

func (s *LocalState) Lock(info *LockInfo) (string, error)

Lock implements a local filesystem state.Locker.

func (*LocalState) PersistState

func (s *LocalState) PersistState() error

PersistState for LocalState is a no-op since WriteState always persists.

StatePersister impl.

func (*LocalState) RefreshState

func (s *LocalState) RefreshState() error

StateRefresher impl.

func (*LocalState) SetState

func (s *LocalState) SetState(state *terraform.State)

SetState will force a specific state in-memory for this local state.

func (*LocalState) State

func (s *LocalState) State() *terraform.State

StateReader impl.

func (*LocalState) Unlock

func (s *LocalState) Unlock(id string) error

func (*LocalState) WriteState

func (s *LocalState) WriteState(state *terraform.State) error

WriteState for LocalState always persists the state as well. TODO: this should use a more robust method of writing state, by first writing to a temp file on the same filesystem, and renaming the file over the original.

StateWriter impl.

type LockDisabled

type LockDisabled struct {
	// We can't embed State directly since Go dislikes that a field is
	// State and State interface has a method State
	Inner State
}

LockDisabled implements State and Locker but disables state locking. If State doesn't support locking, this is a no-op. This is useful for easily disabling locking of an existing state or for tests.

func (*LockDisabled) Lock

func (s *LockDisabled) Lock(info *LockInfo) (string, error)

func (*LockDisabled) PersistState

func (s *LockDisabled) PersistState() error

func (*LockDisabled) RefreshState

func (s *LockDisabled) RefreshState() error

func (*LockDisabled) State

func (s *LockDisabled) State() *terraform.State

func (*LockDisabled) Unlock

func (s *LockDisabled) Unlock(id string) error

func (*LockDisabled) WriteState

func (s *LockDisabled) WriteState(v *terraform.State) error

type LockError

type LockError struct {
	Info *LockInfo
	Err  error
}

func (*LockError) Error

func (e *LockError) Error() string

type LockInfo

type LockInfo struct {
	// Unique ID for the lock. NewLockInfo provides a random ID, but this may
	// be overridden by the lock implementation. The final value if ID will be
	// returned by the call to Lock.
	ID string

	// Terraform operation, provided by the caller.
	Operation string
	// Extra information to store with the lock, provided by the caller.
	Info string

	// user@hostname when available
	Who string
	// Terraform version
	Version string
	// Time that the lock was taken.
	Created time.Time

	// Path to the state file when applicable. Set by the Lock implementation.
	Path string
}

LockInfo stores lock metadata.

Only Operation and Info are required to be set by the caller of Lock.

func NewLockInfo

func NewLockInfo() *LockInfo

Generate a LockInfo structure, populating the required fields.

func (*LockInfo) Err

func (l *LockInfo) Err() error

Err returns the lock info formatted in an error

func (*LockInfo) Marshal

func (l *LockInfo) Marshal() []byte

Marshal returns a string json representation of the LockInfo

func (*LockInfo) String

func (l *LockInfo) String() string

String return a multi-line string representation of LockInfo

type Locker

type Locker interface {
	Lock(info *LockInfo) (string, error)
	Unlock(id string) error
}

Locker is implemented to lock state during command execution. The info parameter can be recorded with the lock, but the implementation should not depend in its value. The string returned by Lock is an ID corresponding to the lock acquired, and must be passed to Unlock to ensure that the correct lock is being released.

Lock and Unlock may return an error value of type LockError which in turn can contain the LockInfo of a conflicting lock.

type State

type State interface {
	StateReader
	StateWriter
	StateRefresher
	StatePersister
	Locker
}

State is the collection of all state interfaces.

type StatePersister

type StatePersister interface {
	PersistState() error
}

StatePersister is implemented to truly persist a state. Whereas StateWriter is allowed to perhaps be caching in memory, PersistState must write the state to some durable storage.

If an object implements StatePersister in conjunction with StateReader and/or StateRefresher then these methods must coordinate such that subsequent reads after a persist return an updated value.

type StateReader

type StateReader interface {
	State() *terraform.State
}

StateReader is the interface for things that can return a state. Retrieving the state here must not error. Loading the state fresh (an operation that can likely error) should be implemented by RefreshState. If a state hasn't been loaded yet, it is okay for State to return nil.

Each caller of this function must get a distinct copy of the state, and it must also be distinct from any instance cached inside the reader, to ensure that mutations of the returned state will not affect the values returned to other callers.

type StateRefresher

type StateRefresher interface {
	RefreshState() error
}

StateRefresher is the interface that is implemented by something that can load a state. This might be refreshing it from a remote location or it might simply be reloading it from disk.

type StateWriter

type StateWriter interface {
	WriteState(*terraform.State) error
}

StateWriter is the interface that must be implemented by something that can write a state. Writing the state can be cached or in-memory, as full persistence should be implemented by StatePersister.

Implementors that cache the state in memory _must_ take a copy of it before returning, since the caller may continue to modify it once control returns. The caller must ensure that the state instance is not concurrently modified _during_ the call, or behavior is undefined.

If an object implements StatePersister in conjunction with StateReader then these methods must coordinate such that a subsequent read returns a copy of the most recent write, even if it has not yet been persisted.