states

package
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 18, 2019 License: MPL-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package states contains the types that are used to represent Terraform states.

Index

Constants

View Source 
const NotDeposed = DeposedKey("")

NotDeposed is a special invalid value of DeposedKey that is used to represent the absense of a deposed key. It must not be used as an actual deposed key.

Variables

This section is empty.

Functions

func LegacyInstanceObjectID 

func LegacyInstanceObjectID(obj *ResourceInstanceObjectSrc) string

LegacyInstanceObjectID is a helper for extracting an object id value from an instance object in a way that approximates how we used to do this for the old state types. ID is no longer first-class, so this is preserved only for compatibility with old tests that include the id as part of their expected value.

Types

type DeposedKey 

type DeposedKey string

DeposedKey is a 8-character hex string used to uniquely identify deposed instance objects in the state.

func NewDeposedKey 

func NewDeposedKey() DeposedKey

NewDeposedKey generates a pseudo-random deposed key. Because of the short length of these keys, uniqueness is not a natural consequence and so the caller should test to see if the generated key is already in use and generate another if so, until a unique key is found.

func (DeposedKey) Generation 

func (k DeposedKey) Generation() Generation

Generation is a helper method to convert a DeposedKey into a Generation. If the reciever is anything other than NotDeposed then the result is just the same value as a Generation. If the receiver is NotDeposed then the result is CurrentGen.

func (DeposedKey) GoString 

func (k DeposedKey) GoString() string

func (DeposedKey) String 

func (k DeposedKey) String() string

type EachMode 

type EachMode rune

EachMode specifies the multi-instance mode for a resource. 

const (
	NoEach   EachMode = 0
	EachList EachMode = 'L'
	EachMap  EachMode = 'M'
)

func (EachMode) String 

func (i EachMode) String() string

type Generation 

type Generation interface {
	// contains filtered or unexported methods
}

Generation is used to represent multiple objects in a succession of objects represented by a single resource instance address. A resource instance can have multiple generations over its lifetime due to object replacement (when a change can't be applied without destroying and re-creating), and multiple generations can exist at the same time when create_before_destroy is used.

A Generation value can either be the value of the variable "CurrentGen" or a value of type DeposedKey. Generation values can be compared for equality using "==" and used as map keys. The zero value of Generation (nil) is not a valid generation and must not be used. 

var CurrentGen Generation

CurrentGen is the Generation representing the currently-active object for a resource instance.

type Module 

type Module struct {
	Addr addrs.ModuleInstance

	// Resources contains the state for each resource. The keys in this map are
	// an implementation detail and must not be used by outside callers.
	Resources map[string]*Resource

	// OutputValues contains the state for each output value. The keys in this
	// map are output value names.
	OutputValues map[string]*OutputValue

	// LocalValues contains the value for each named output value. The keys
	// in this map are local value names.
	LocalValues map[string]cty.Value
}

Module is a container for the states of objects within a particular module.

func NewModule 

func NewModule(addr addrs.ModuleInstance) *Module

NewModule constructs an empty module state for the given module address.

func (*Module) DeepCopy 

func (ms *Module) DeepCopy() *Module

DeepCopy returns a new module state that contains equivalent data to the receiver but shares no backing memory in common.

As with all methods on Module, this method is not safe to use concurrently with writing to any portion of the recieving data structure. It is the caller's responsibility to ensure mutual exclusion for the duration of the operation, but may then freely modify the receiver and the returned copy independently once this method returns.

func (*Module) ForgetResourceInstanceAll 

func (ms *Module) ForgetResourceInstanceAll(addr addrs.ResourceInstance)

ForgetResourceInstanceAll removes the record of all objects associated with the specified resource instance, if present. If not present, this is a no-op.

func (*Module) ForgetResourceInstanceDeposed 

func (ms *Module) ForgetResourceInstanceDeposed(addr addrs.ResourceInstance, key DeposedKey)

ForgetResourceInstanceDeposed removes the record of the deposed object with the given address and key, if present. If not present, this is a no-op.

func (*Module) PruneResourceHusks 

func (ms *Module) PruneResourceHusks()

PruneResourceHusks is a specialized method that will remove any Resource objects that do not contain any instances, even if they have an EachMode.

You probably shouldn't call this! See the method of the same name on type State for more information on what this is for and the rare situations where it is safe to use.

func (*Module) RemoveLocalValue 

func (ms *Module) RemoveLocalValue(name string)

RemoveLocalValue removes the local value of the given name from the state, if it exists. This method is a no-op if there is no value of the given name.

func (*Module) RemoveOutputValue 

func (ms *Module) RemoveOutputValue(name string)

RemoveOutputValue removes the output value of the given name from the state, if it exists. This method is a no-op if there is no value of the given name.

func (*Module) RemoveResource 

func (ms *Module) RemoveResource(addr addrs.Resource)

RemoveResource removes the entire state for the given resource, taking with it any instances associated with the resource. This should generally be called only for resource objects whose instances have all been destroyed.

func (*Module) Resource 

func (ms *Module) Resource(addr addrs.Resource) *Resource

Resource returns the state for the resource with the given address within the receiving module state, or nil if the requested resource is not tracked in the state.

func (*Module) ResourceInstance 

func (ms *Module) ResourceInstance(addr addrs.ResourceInstance) *ResourceInstance

ResourceInstance returns the state for the resource instance with the given address within the receiving module state, or nil if the requested instance is not tracked in the state.

func (*Module) SetLocalValue 

func (ms *Module) SetLocalValue(name string, value cty.Value)

SetLocalValue writes a local value into the state, overwriting any existing value of the same name.

func (*Module) SetOutputValue 

func (ms *Module) SetOutputValue(name string, value cty.Value, sensitive bool) *OutputValue

SetOutputValue writes an output value into the state, overwriting any existing value of the same name.

func (*Module) SetResourceInstanceCurrent 

func (ms *Module) SetResourceInstanceCurrent(addr addrs.ResourceInstance, obj *ResourceInstanceObjectSrc, provider addrs.AbsProviderConfig)

SetResourceInstanceCurrent saves the given instance object as the current generation of the resource instance with the given address, simulataneously updating the recorded provider configuration address, dependencies, and resource EachMode.

Any existing current instance object for the given resource is overwritten. Set obj to nil to remove the primary generation object altogether. If there are no deposed objects then the instance will be removed altogether.

The provider address and "each mode" are resource-wide settings and so they are updated for all other instances of the same resource as a side-effect of this call.

func (*Module) SetResourceInstanceDeposed 

func (ms *Module) SetResourceInstanceDeposed(addr addrs.ResourceInstance, key DeposedKey, obj *ResourceInstanceObjectSrc, provider addrs.AbsProviderConfig)

SetResourceInstanceDeposed saves the given instance object as a deposed generation of the resource instance with the given address and deposed key.

Call this method only for pre-existing deposed objects that already have a known DeposedKey. For example, this method is useful if reloading objects that were persisted to a state file. To mark the current object as deposed, use DeposeResourceInstanceObject instead.

The resource that contains the given instance must already exist in the state, or this method will panic. Use Resource to check first if its presence is not already guaranteed.

Any existing current instance object for the given resource and deposed key is overwritten. Set obj to nil to remove the deposed object altogether. If the instance is left with no objects after this operation then it will be removed from its containing resource altogether.

func (*Module) SetResourceMeta 

func (ms *Module) SetResourceMeta(addr addrs.Resource, eachMode EachMode, provider addrs.AbsProviderConfig)

SetResourceMeta updates the resource-level metadata for the resource with the given address, creating the resource state for it if it doesn't already exist.

type ObjectStatus 

type ObjectStatus rune

ObjectStatus represents the status of a RemoteObject. 

const (
	// ObjectReady is an object status for an object that is ready to use.
	ObjectReady ObjectStatus = 'R'

	// ObjectTainted is an object status representing an object that is in
	// an unrecoverable bad state due to a partial failure during a create,
	// update, or delete operation. Since it cannot be moved into the
	// ObjectRead state, a tainted object must be replaced.
	ObjectTainted ObjectStatus = 'T'

	// ObjectPlanned is a special object status used only for the transient
	// placeholder objects we place into state during the refresh and plan
	// walks to stand in for objects that will be created during apply.
	//
	// Any object of this status must have a corresponding change recorded
	// in the current plan, whose value must then be used in preference to
	// the value stored in state when evaluating expressions. A planned
	// object stored in state will be incomplete if any of its attributes are
	// not yet known, and the plan must be consulted in order to "see" those
	// unknown values, because the state is not able to represent them.
	ObjectPlanned ObjectStatus = 'P'
)

func (ObjectStatus) String 

func (i ObjectStatus) String() string

type OutputValue 

type OutputValue struct {
	Value     cty.Value
	Sensitive bool
}

OutputValue represents the state of a particular output value.

It is not valid to mutate an OutputValue object once it has been created. Instead, create an entirely new OutputValue to replace the previous one.

func (*OutputValue) DeepCopy 

func (os *OutputValue) DeepCopy() *OutputValue

DeepCopy returns a new output value state that contains equivalent data to the receiver but shares no backing memory in common.

As with all methods on OutputValue, this method is not safe to use concurrently with writing to any portion of the recieving data structure. It is the caller's responsibility to ensure mutual exclusion for the duration of the operation, but may then freely modify the receiver and the returned copy independently once this method returns.

type Resource 

type Resource struct {
	// Addr is the module-relative address for the resource this state object
	// belongs to.
	Addr addrs.Resource

	// EachMode is the multi-instance mode currently in use for this resource,
	// or NoEach if this is a single-instance resource. This dictates what
	// type of value is returned when accessing this resource via expressions
	// in the Terraform language.
	EachMode EachMode

	// Instances contains the potentially-multiple instances associated with
	// this resource. This map can contain a mixture of different key types,
	// but only the ones of InstanceKeyType are considered current.
	Instances map[addrs.InstanceKey]*ResourceInstance

	// ProviderConfig is the absolute address for the provider configuration that
	// most recently managed this resource. This is used to connect a resource
	// with a provider configuration when the resource configuration block is
	// not available, such as if it has been removed from configuration
	// altogether.
	ProviderConfig addrs.AbsProviderConfig
}

Resource represents the state of a resource.

func (*Resource) DeepCopy 

func (rs *Resource) DeepCopy() *Resource

DeepCopy returns a new resource state that contains equivalent data to the receiver but shares no backing memory in common.

As with all methods on Resource, this method is not safe to use concurrently with writing to any portion of the recieving data structure. It is the caller's responsibility to ensure mutual exclusion for the duration of the operation, but may then freely modify the receiver and the returned copy independently once this method returns.

func (*Resource) EnsureInstance 

func (rs *Resource) EnsureInstance(key addrs.InstanceKey) *ResourceInstance

EnsureInstance returns the state for the instance with the given key, creating a new empty state for it if one doesn't already exist.

Because this may create and save a new state, it is considered to be a write operation.

func (*Resource) Instance 

func (rs *Resource) Instance(key addrs.InstanceKey) *ResourceInstance

Instance returns the state for the instance with the given key, or nil if no such instance is tracked within the state.

type ResourceInstance 

type ResourceInstance struct {
	// Current, if non-nil, is the remote object that is currently represented
	// by the corresponding resource instance.
	Current *ResourceInstanceObjectSrc

	// Deposed, if len > 0, contains any remote objects that were previously
	// represented by the corresponding resource instance but have been
	// replaced and are pending destruction due to the create_before_destroy
	// lifecycle mode.
	Deposed map[DeposedKey]*ResourceInstanceObjectSrc
}

ResourceInstance represents the state of a particular instance of a resource.

func NewResourceInstance 

func NewResourceInstance() *ResourceInstance

NewResourceInstance constructs and returns a new ResourceInstance, ready to use.

func (*ResourceInstance) DeepCopy 

func (is *ResourceInstance) DeepCopy() *ResourceInstance

DeepCopy returns a new resource instance state that contains equivalent data to the receiver but shares no backing memory in common.

As with all methods on ResourceInstance, this method is not safe to use concurrently with writing to any portion of the recieving data structure. It is the caller's responsibility to ensure mutual exclusion for the duration of the operation, but may then freely modify the receiver and the returned copy independently once this method returns.

func (*ResourceInstance) FindUnusedDeposedKey 

func (i *ResourceInstance) FindUnusedDeposedKey() DeposedKey

FindUnusedDeposedKey generates a unique DeposedKey that is guaranteed not to already be in use for this instance at the time of the call.

Note that the validity of this result may change if new deposed keys are allocated before it is used. To avoid this risk, instead use the DeposeResourceInstanceObject method on the SyncState wrapper type, which allocates a key and uses it atomically.

func (*ResourceInstance) GetGeneration 

func (i *ResourceInstance) GetGeneration(gen Generation) *ResourceInstanceObjectSrc

GetGeneration retrieves the object of the given generation from the ResourceInstance, or returns nil if there is no such object.

If the given generation is nil or invalid, this method will panic.

func (*ResourceInstance) HasAnyDeposed 

func (i *ResourceInstance) HasAnyDeposed() bool

HasAnyDeposed returns true if this resource instance has one or more deposed objects.

func (*ResourceInstance) HasCurrent 

func (i *ResourceInstance) HasCurrent() bool

HasCurrent returns true if this resource instance has a "current"-generation object. Most instances do, but this can briefly be false during a create-before-destroy replace operation when the current has been deposed but its replacement has not yet been created.

func (*ResourceInstance) HasDeposed 

func (i *ResourceInstance) HasDeposed(key DeposedKey) bool

HasDeposed returns true if this resource instance has a deposed object with the given key.

func (*ResourceInstance) HasObjects 

func (i *ResourceInstance) HasObjects() bool

HasObjects returns true if this resource has any objects at all, whether current or deposed.

type ResourceInstanceObject 

type ResourceInstanceObject struct {
	// Value is the object-typed value representing the remote object within
	// Terraform.
	Value cty.Value

	// Private is an opaque value set by the provider when this object was
	// last created or updated. Terraform Core does not use this value in
	// any way and it is not exposed anywhere in the user interface, so
	// a provider can use it for retaining any necessary private state.
	Private []byte

	// Status represents the "readiness" of the object as of the last time
	// it was updated.
	Status ObjectStatus

	// Dependencies is a set of other addresses in the same module which
	// this instance depended on when the given attributes were evaluated.
	// This is used to construct the dependency relationships for an object
	// whose configuration is no longer available, such as if it has been
	// removed from configuration altogether, or is now deposed.
	Dependencies []addrs.Referenceable
}

ResourceInstanceObject is the local representation of a specific remote object associated with a resource instance. In practice not all remote objects are actually remote in the sense of being accessed over the network, but this is the most common case.

It is not valid to mutate a ResourceInstanceObject once it has been created. Instead, create a new object and replace the existing one.

func (*ResourceInstanceObject) AsTainted 

func (o *ResourceInstanceObject) AsTainted() *ResourceInstanceObject

AsTainted returns a deep copy of the receiver with the status updated to ObjectTainted.

func (*ResourceInstanceObject) DeepCopy 

func (obj *ResourceInstanceObject) DeepCopy() *ResourceInstanceObject

DeepCopy returns a new resource instance object that contains equivalent data to the receiver but shares no backing memory in common.

As with all methods on ResourceInstanceObject, this method is not safe to use concurrently with writing to any portion of the recieving data structure. It is the caller's responsibility to ensure mutual exclusion for the duration of the operation, but may then freely modify the receiver and the returned copy independently once this method returns.

func (*ResourceInstanceObject) Encode 

func (o *ResourceInstanceObject) Encode(ty cty.Type, schemaVersion uint64) (*ResourceInstanceObjectSrc, error)

Encode marshals the value within the receiver to produce a ResourceInstanceObjectSrc ready to be written to a state file.

The given type must be the implied type of the resource type schema, and the given value must conform to it. It is important to pass the schema type and not the object's own type so that dynamically-typed attributes will be stored correctly. The caller must also provide the version number of the schema that the given type was derived from, which will be recorded in the source object so it can be used to detect when schema migration is required on read.

The returned object may share internal references with the receiver and so the caller must not mutate the receiver any further once once this method is called.

type ResourceInstanceObjectSrc 

type ResourceInstanceObjectSrc struct {
	// SchemaVersion is the resource-type-specific schema version number that
	// was current when either AttrsJSON or AttrsFlat was encoded. Migration
	// steps are required if this is less than the current version number
	// reported by the corresponding provider.
	SchemaVersion uint64

	// AttrsJSON is a JSON-encoded representation of the object attributes,
	// encoding the value (of the object type implied by the associated resource
	// type schema) that represents this remote object in Terraform Language
	// expressions, and is compared with configuration when producing a diff.
	//
	// This is retained in JSON format here because it may require preprocessing
	// before decoding if, for example, the stored attributes are for an older
	// schema version which the provider must upgrade before use. If the
	// version is current, it is valid to simply decode this using the
	// type implied by the current schema, without the need for the provider
	// to perform an upgrade first.
	//
	// When writing a ResourceInstanceObject into the state, AttrsJSON should
	// always be conformant to the current schema version and the current
	// schema version should be recorded in the SchemaVersion field.
	AttrsJSON []byte

	// AttrsFlat is a legacy form of attributes used in older state file
	// formats, and in the new state format for objects that haven't yet been
	// upgraded. This attribute is mutually exclusive with Attrs: for any
	// ResourceInstanceObject, only one of these attributes may be populated
	// and the other must be nil.
	//
	// An instance object with this field populated should be upgraded to use
	// Attrs at the earliest opportunity, since this legacy flatmap-based
	// format will be phased out over time. AttrsFlat should not be used when
	// writing new or updated objects to state; instead, callers must follow
	// the recommendations in the AttrsJSON documentation above.
	AttrsFlat map[string]string

	// These fields all correspond to the fields of the same name on
	// ResourceInstanceObject.
	Private      []byte
	Status       ObjectStatus
	Dependencies []addrs.Referenceable
}

ResourceInstanceObjectSrc is a not-fully-decoded version of ResourceInstanceObject. Decoding of it can be completed by first handling any schema migration steps to get to the latest schema version and then calling method Decode with the implied type of the latest schema.

func (*ResourceInstanceObjectSrc) CompleteUpgrade 

func (os *ResourceInstanceObjectSrc) CompleteUpgrade(newAttrs cty.Value, newType cty.Type, newSchemaVersion uint64) (*ResourceInstanceObjectSrc, error)

CompleteUpgrade creates a new ResourceInstanceObjectSrc by copying the metadata from the receiver and writing in the given new schema version and attribute value that are presumed to have resulted from upgrading from an older schema version.

func (*ResourceInstanceObjectSrc) Decode 

func (os *ResourceInstanceObjectSrc) Decode(ty cty.Type) (*ResourceInstanceObject, error)

Decode unmarshals the raw representation of the object attributes. Pass the implied type of the corresponding resource type schema for correct operation.

Before calling Decode, the caller must check that the SchemaVersion field exactly equals the version number of the schema whose implied type is being passed, or else the result is undefined.

The returned object may share internal references with the receiver and so the caller must not mutate the receiver any further once once this method is called.

func (*ResourceInstanceObjectSrc) DeepCopy 

func (obj *ResourceInstanceObjectSrc) DeepCopy() *ResourceInstanceObjectSrc

DeepCopy returns a new resource instance object that contains equivalent data to the receiver but shares no backing memory in common.

As with all methods on ResourceInstanceObjectSrc, this method is not safe to use concurrently with writing to any portion of the recieving data structure. It is the caller's responsibility to ensure mutual exclusion for the duration of the operation, but may then freely modify the receiver and the returned copy independently once this method returns.

type State 

type State struct {
	// Modules contains the state for each module. The keys in this map are
	// an implementation detail and must not be used by outside callers.
	Modules map[string]*Module
}

State is the top-level type of a Terraform state.

A state should be mutated only via its accessor methods, to ensure that invariants are preserved.

Access to State and the nested values within it is not concurrency-safe, so when accessing a State object concurrently it is the caller's responsibility to ensure that only one write is in progress at a time and that reads only occur when no write is in progress. The most common way to acheive this is to wrap the State in a SyncState and use the higher-level atomic operations supported by that type.

func BuildState 

func BuildState(cb func(*SyncState)) *State

BuildState is a helper -- primarily intended for tests -- to build a state using imperative code against the StateSync type while still acting as an expression of type *State to assign into a containing struct.

func NewState 

func NewState() *State

NewState constructs a minimal empty state, containing an empty root module.

func (*State) DeepCopy 

func (s *State) DeepCopy() *State

DeepCopy returns a new state that contains equivalent data to the reciever but shares no backing memory in common.

As with all methods on State, this method is not safe to use concurrently with writing to any portion of the recieving data structure. It is the caller's responsibility to ensure mutual exclusion for the duration of the operation, but may then freely modify the receiver and the returned copy independently once this method returns.

func (*State) Empty 

func (s *State) Empty() bool

Empty returns true if there are no resources or populated output values in the receiver. In other words, if this state could be safely replaced with the return value of NewState and be functionally equivalent.

func (*State) EnsureModule 

func (s *State) EnsureModule(addr addrs.ModuleInstance) *Module

EnsureModule returns the state for the module with the given address, creating and adding a new one if necessary.

Since this might modify the state to add a new instance, it is considered to be a write operation.

func (*State) Equal 

func (s *State) Equal(other *State) bool

Equal returns true if the receiver is functionally equivalent to other, including any ephemeral portions of the state that would not be included if the state were saved to files.

To test only the persistent portions of two states for equality, instead use statefile.StatesMarshalEqual.

func (*State) HasResources 

func (s *State) HasResources() bool

HasResources returns true if there is at least one resource (of any mode) present in the receiving state.

func (*State) LocalValue 

func (s *State) LocalValue(addr addrs.AbsLocalValue) cty.Value

LocalValue returns the value of the named local value with the given address, or cty.NilVal if no such value is tracked in the state.

func (*State) Module 

func (s *State) Module(addr addrs.ModuleInstance) *Module

Module returns the state for the module with the given address, or nil if the requested module is not tracked in the state.

func (*State) OutputValue 

func (s *State) OutputValue(addr addrs.AbsOutputValue) *OutputValue

OutputValue returns the state for the output value with the given address, or nil if no such output value is tracked in the state.

func (*State) ProviderAddrs 

func (s *State) ProviderAddrs() []addrs.AbsProviderConfig

ProviderAddrs returns a list of all of the provider configuration addresses referenced throughout the receiving state.

The result is de-duplicated so that each distinct address appears only once.

func (*State) PruneResourceHusks 

func (s *State) PruneResourceHusks()

PruneResourceHusks is a specialized method that will remove any Resource objects that do not contain any instances, even if they have an EachMode.

This should generally be used only after a "terraform destroy" operation, to finalize the cleanup of the state. It is not correct to use this after other operations because if a resource has "count = 0" or "for_each" over an empty collection then we want to retain it in the state so that references to it, particularly in "strange" contexts like "terraform console", can be properly resolved.

This method MUST NOT be called concurrently with other readers and writers of the receiving state.

func (*State) RemoveModule 

func (s *State) RemoveModule(addr addrs.ModuleInstance)

RemoveModule removes the module with the given address from the state, unless it is the root module. The root module cannot be deleted, and so this method will panic if that is attempted.

Removing a module implicitly discards all of the resources, outputs and local values within it, and so this should usually be done only for empty modules. For callers accessing the state through a SyncState wrapper, modules are automatically pruned if they are empty after one of their contained elements is removed.

func (*State) Resource 

func (s *State) Resource(addr addrs.AbsResource) *Resource

Resource returns the state for the resource with the given address, or nil if no such resource is tracked in the state.

func (*State) ResourceInstance 

func (s *State) ResourceInstance(addr addrs.AbsResourceInstance) *ResourceInstance

ResourceInstance returns the state for the resource instance with the given address, or nil if no such resource is tracked in the state.

func (*State) RootModule 

func (s *State) RootModule() *Module

RootModule is a convenient alias for Module(addrs.RootModuleInstance).

func (*State) String 

func (s *State) String() string

String returns a rather-odd string representation of the entire state.

This is intended to match the behavior of the older terraform.State.String method that is used in lots of existing tests. It should not be used in new tests: instead, use "cmp" to directly compare the state data structures and print out a diff if they do not match.

This method should never be used in non-test code, whether directly by call or indirectly via a %s or %q verb in package fmt.

func (*State) SyncWrapper 

func (s *State) SyncWrapper() *SyncState

SyncWrapper returns a SyncState object wrapping the receiver.

type SyncState 

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

SyncState is a wrapper around State that provides concurrency-safe access to various common operations that occur during a Terraform graph walk, or other similar concurrent contexts.

When a SyncState wrapper is in use, no concurrent direct access to the underlying objects is permitted unless the caller first acquires an explicit lock, using the Lock and Unlock methods. Most callers should _not_ explicitly lock, and should instead use the other methods of this type that handle locking automatically.

Since SyncState is able to safely consolidate multiple updates into a single atomic operation, many of its methods are at a higher level than those of the underlying types, and operate on the state as a whole rather than on individual sub-structures of the state.

SyncState can only protect against races within its own methods. It cannot provide any guarantees about the order in which concurrent operations will be processed, so callers may still need to employ higher-level techniques for ensuring correct operation sequencing, such as building and walking a dependency graph.

func (*SyncState) DeposeResourceInstanceObject 

func (s *SyncState) DeposeResourceInstanceObject(addr addrs.AbsResourceInstance) DeposedKey

DeposeResourceInstanceObject moves the current instance object for the given resource instance address into the deposed set, leaving the instance without a current object.

The return value is the newly-allocated deposed key, or NotDeposed if the given instance is already lacking a current object.

If the containing module for this resource or the resource itself are not already tracked in state then there cannot be a current object for the given instance, and so NotDeposed will be returned without modifying the state at all.

func (*SyncState) DeposeResourceInstanceObjectForceKey 

func (s *SyncState) DeposeResourceInstanceObjectForceKey(addr addrs.AbsResourceInstance, forcedKey DeposedKey)

DeposeResourceInstanceObjectForceKey is like DeposeResourceInstanceObject but uses a pre-allocated key. It's the caller's responsibility to ensure that there aren't any races to use a particular key; this method will panic if the given key is already in use.

func (*SyncState) ForgetResourceInstanceAll 

func (s *SyncState) ForgetResourceInstanceAll(addr addrs.AbsResourceInstance)

ForgetResourceInstanceAll removes the record of all objects associated with the specified resource instance, if present. If not present, this is a no-op.

func (*SyncState) ForgetResourceInstanceDeposed 

func (s *SyncState) ForgetResourceInstanceDeposed(addr addrs.AbsResourceInstance, key DeposedKey)

ForgetResourceInstanceDeposed removes the record of the deposed object with the given address and key, if present. If not present, this is a no-op.

func (*SyncState) LocalValue 

func (s *SyncState) LocalValue(addr addrs.AbsLocalValue) cty.Value

LocalValue returns the current value associated with the given local value address.

func (*SyncState) Lock 

func (s *SyncState) Lock() *State

Lock acquires an explicit lock on the state, allowing direct read and write access to the returned state object. The caller must call Unlock once access is no longer needed, and then immediately discard the state pointer pointer.

Most callers should not use this. Instead, use the concurrency-safe accessors and mutators provided directly on SyncState.

func (*SyncState) MaybeFixUpResourceInstanceAddressForCount 

func (s *SyncState) MaybeFixUpResourceInstanceAddressForCount(addr addrs.AbsResource, countEnabled bool) bool

MaybeFixUpResourceInstanceAddressForCount deals with the situation where a resource has changed from having "count" set to not set, or vice-versa, and so we need to rename the zeroth instance key to no key at all, or vice-versa.

Set countEnabled to true if the resource has count set in its new configuration, or false if it does not.

The state is modified in-place if necessary, moving a resource instance between the two addresses. The return value is true if a change was made, and false otherwise.

func (*SyncState) MaybeRestoreResourceInstanceDeposed 

func (s *SyncState) MaybeRestoreResourceInstanceDeposed(addr addrs.AbsResourceInstance, key DeposedKey) bool

MaybeRestoreResourceInstanceDeposed will restore the deposed object with the given key on the specified resource as the current object for that instance if and only if that would not cause us to forget an existing current object for that instance.

Returns true if the object was restored to current, or false if no change was made at all.

func (*SyncState) Module 

func (s *SyncState) Module(addr addrs.ModuleInstance) *Module

Module returns a snapshot of the state of the module instance with the given address, or nil if no such module is tracked.

The return value is a pointer to a copy of the module state, which the caller may then freely access and mutate. However, since the module state tends to be a large data structure with many child objects, where possible callers should prefer to use a more granular accessor to access a child module directly, and thus reduce the amount of copying required.

func (*SyncState) OutputValue 

func (s *SyncState) OutputValue(addr addrs.AbsOutputValue) *OutputValue

OutputValue returns a snapshot of the state of the output value with the given address, or nil if no such output value is tracked.

The return value is a pointer to a copy of the output value state, which the caller may then freely access and mutate.

func (*SyncState) RemoveLocalValue 

func (s *SyncState) RemoveLocalValue(addr addrs.AbsLocalValue)

RemoveLocalValue removes the stored value for the local value with the given address.

If this results in its containing module being empty, the module will be pruned from the state as a side-effect.

func (*SyncState) RemoveModule 

func (s *SyncState) RemoveModule(addr addrs.ModuleInstance)

RemoveModule removes the entire state for the given module, taking with it any resources associated with the module. This should generally be called only for modules whose resources have all been destroyed, but that is not enforced by this method.

func (*SyncState) RemoveOutputValue 

func (s *SyncState) RemoveOutputValue(addr addrs.AbsOutputValue)

RemoveOutputValue removes the stored value for the output value with the given address.

If this results in its containing module being empty, the module will be pruned from the state as a side-effect.

func (*SyncState) RemovePlannedResourceInstanceObjects 

func (s *SyncState) RemovePlannedResourceInstanceObjects()

RemovePlannedResourceInstanceObjects removes from the state any resource instance objects that have the status ObjectPlanned, indiciating that they are just transient placeholders created during planning.

Note that this does not restore any "ready" or "tainted" object that might have been present before the planned object was written. The only real use for this method is in preparing the state created during a refresh walk, where we run the planning step for certain instances just to create enough information to allow correct expression evaluation within provider and data resource blocks. Discarding planned instances in that case is okay because the refresh phase only creates planned objects to stand in for objects that don't exist yet, and thus the planned object must have been absent before by definition.

func (*SyncState) RemoveResource 

func (s *SyncState) RemoveResource(addr addrs.AbsResource)

RemoveResource removes the entire state for the given resource, taking with it any instances associated with the resource. This should generally be called only for resource objects whose instances have all been destroyed, but that is not enforced by this method. (Use RemoveResourceIfEmpty instead to safely check first.)

func (*SyncState) RemoveResourceIfEmpty 

func (s *SyncState) RemoveResourceIfEmpty(addr addrs.AbsResource) bool

RemoveResourceIfEmpty is similar to RemoveResource but first checks to make sure there are no instances or objects left in the resource.

Returns true if the resource was removed, or false if remaining child objects prevented its removal. Returns true also if the resource was already absent, and thus no action needed to be taken.

func (*SyncState) Resource 

func (s *SyncState) Resource(addr addrs.AbsResource) *Resource

Resource returns a snapshot of the state of the resource with the given address, or nil if no such resource is tracked.

The return value is a pointer to a copy of the resource state, which the caller may then freely access and mutate.

func (*SyncState) ResourceInstance 

func (s *SyncState) ResourceInstance(addr addrs.AbsResourceInstance) *ResourceInstance

ResourceInstance returns a snapshot of the state the resource instance with the given address, or nil if no such instance is tracked.

The return value is a pointer to a copy of the instance state, which the caller may then freely access and mutate.

func (*SyncState) ResourceInstanceObject 

func (s *SyncState) ResourceInstanceObject(addr addrs.AbsResourceInstance, gen Generation) *ResourceInstanceObjectSrc

ResourceInstanceObject returns a snapshot of the current instance object of the given generation belonging to the instance with the given address, or nil if no such object is tracked..

The return value is a pointer to a copy of the object, which the caller may then freely access and mutate.

func (*SyncState) SetLocalValue 

func (s *SyncState) SetLocalValue(addr addrs.AbsLocalValue, value cty.Value)

SetLocalValue writes a given output value into the state, overwriting any existing value of the same name.

If the module containing the local value is not yet tracked in state then it will be added as a side-effect.

func (*SyncState) SetOutputValue 

func (s *SyncState) SetOutputValue(addr addrs.AbsOutputValue, value cty.Value, sensitive bool)

SetOutputValue writes a given output value into the state, overwriting any existing value of the same name.

If the module containing the output is not yet tracked in state then it be added as a side-effect.

func (*SyncState) SetResourceInstanceCurrent 

func (s *SyncState) SetResourceInstanceCurrent(addr addrs.AbsResourceInstance, obj *ResourceInstanceObjectSrc, provider addrs.AbsProviderConfig)

SetResourceInstanceCurrent saves the given instance object as the current generation of the resource instance with the given address, simultaneously updating the recorded provider configuration address, dependencies, and resource EachMode.

Any existing current instance object for the given resource is overwritten. Set obj to nil to remove the primary generation object altogether. If there are no deposed objects then the instance as a whole will be removed, which may in turn also remove the containing module if it becomes empty.

The caller must ensure that the given ResourceInstanceObject is not concurrently mutated during this call, but may be freely used again once this function returns.

The provider address and "each mode" are resource-wide settings and so they are updated for all other instances of the same resource as a side-effect of this call.

If the containing module for this resource or the resource itself are not already tracked in state then they will be added as a side-effect.

func (*SyncState) SetResourceInstanceDeposed 

func (s *SyncState) SetResourceInstanceDeposed(addr addrs.AbsResourceInstance, key DeposedKey, obj *ResourceInstanceObjectSrc, provider addrs.AbsProviderConfig)

SetResourceInstanceDeposed saves the given instance object as a deposed generation of the resource instance with the given address and deposed key.

Call this method only for pre-existing deposed objects that already have a known DeposedKey. For example, this method is useful if reloading objects that were persisted to a state file. To mark the current object as deposed, use DeposeResourceInstanceObject instead.

The caller must ensure that the given ResourceInstanceObject is not concurrently mutated during this call, but may be freely used again once this function returns.

The resource that contains the given instance must already exist in the state, or this method will panic. Use Resource to check first if its presence is not already guaranteed.

Any existing current instance object for the given resource and deposed key is overwritten. Set obj to nil to remove the deposed object altogether. If the instance is left with no objects after this operation then it will be removed from its containing resource altogether.

If the containing module for this resource or the resource itself are not already tracked in state then they will be added as a side-effect.

func (*SyncState) SetResourceMeta 

func (s *SyncState) SetResourceMeta(addr addrs.AbsResource, eachMode EachMode, provider addrs.AbsProviderConfig)

SetResourceMeta updates the resource-level metadata for the resource at the given address, creating the containing module state and resource state as a side-effect if not already present.

func (*SyncState) Unlock 

func (s *SyncState) Unlock()

Unlock releases a lock previously acquired by Lock, at which point the caller must cease all use of the state pointer that was returned.

Do not call this method except to end an explicit lock acquired by Lock. If a caller calls Unlock without first holding the lock, behavior is undefined.

Source Files

View all Source files

Directories

Path Synopsis
Package statefile deals with the file format used to serialize states for persistent storage and then deserialize them into memory again later.
 Package statefile deals with the file format used to serialize states for persistent storage and then deserialize them into memory again later.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.