terraform

package
Version: v2.7.1 Latest Latest
Warning

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

Go to latest
Published: Aug 31, 2021 License: MPL-2.0 Imports: 20 Imported by: 41

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BackendState

type BackendState struct {
	Type      string          `json:"type"`   // Backend type
	ConfigRaw json.RawMessage `json:"config"` // Backend raw config
	Hash      uint64          `json:"hash"`   // Hash of portion of configuration from config files
}

BackendState stores the configuration to connect to a remote backend.

type DataSource

type DataSource struct {
	Name string

	// SchemaAvailable is set if the provider supports the ProviderSchema,
	// ResourceTypeSchema and DataSourceSchema methods. Although it is
	// included on each resource type, it's actually a provider-wide setting
	// that's smuggled here only because that avoids a breaking change to
	// the plugin protocol.
	SchemaAvailable bool
}

DataSource is a data source that a resource provider implements.

type EphemeralState

type EphemeralState struct {
	// ConnInfo is used for the providers to export information which is
	// used to connect to the resource for provisioning. For example,
	// this could contain SSH or WinRM credentials.
	ConnInfo map[string]string `json:"-"`

	// Type is used to specify the resource type for this instance. This is only
	// required for import operations (as documented). If the documentation
	// doesn't state that you need to set this, then don't worry about
	// setting it.
	Type string `json:"-"`
}

EphemeralState is used for transient state that is only kept in-memory

type InstanceDiff

type InstanceDiff struct {
	Attributes     map[string]*ResourceAttrDiff
	Destroy        bool
	DestroyDeposed bool
	DestroyTainted bool

	// Meta is a simple K/V map that is stored in a diff and persisted to
	// plans but otherwise is completely ignored by Terraform core. It is
	// meant to be used for additional data a resource may want to pass through.
	// The value here must only contain Go primitives and collections.
	Meta map[string]interface{}
	// contains filtered or unexported fields
}

InstanceDiff is the diff of a resource from some state to another.

func NewInstanceDiff

func NewInstanceDiff() *InstanceDiff

func (*InstanceDiff) Apply

func (d *InstanceDiff) Apply(attrs map[string]string, schema *configschema.Block) (map[string]string, error)

Apply applies the diff to the provided flatmapped attributes, returning the new instance attributes.

This method is intended for shimming old subsystems that still use this legacy diff type to work with the new-style types.

func (*InstanceDiff) ApplyToValue

func (d *InstanceDiff) ApplyToValue(base cty.Value, schema *configschema.Block) (cty.Value, error)

ApplyToValue merges the receiver into the given base value, returning a new value that incorporates the planned changes. The given value must conform to the given schema, or this method will panic.

This method is intended for shimming old subsystems that still use this legacy diff type to work with the new-style types.

func (*InstanceDiff) ChangeType

func (d *InstanceDiff) ChangeType() diffChangeType

ChangeType returns the diffChangeType represented by the diff for this single instance.

func (*InstanceDiff) CopyAttributes

func (d *InstanceDiff) CopyAttributes() map[string]*ResourceAttrDiff

Safely copies the Attributes map

func (*InstanceDiff) Empty

func (d *InstanceDiff) Empty() bool

Empty returns true if this diff encapsulates no changes.

func (*InstanceDiff) Equal

func (d *InstanceDiff) Equal(d2 *InstanceDiff) bool

Equal compares two diffs for exact equality.

This is different from the Same comparison that is supported which checks for operation equality taking into account computed values. Equal instead checks for exact equality. TODO: investigate why removing this unused method causes panic in tests

func (*InstanceDiff) GetAttribute

func (d *InstanceDiff) GetAttribute(key string) (*ResourceAttrDiff, bool)

func (*InstanceDiff) GetDestroy

func (d *InstanceDiff) GetDestroy() bool

func (*InstanceDiff) GetDestroyDeposed

func (d *InstanceDiff) GetDestroyDeposed() bool

func (*InstanceDiff) GetDestroyTainted

func (d *InstanceDiff) GetDestroyTainted() bool

func (*InstanceDiff) GoString

func (d *InstanceDiff) GoString() string

func (*InstanceDiff) Lock

func (d *InstanceDiff) Lock()

func (*InstanceDiff) RequiresNew

func (d *InstanceDiff) RequiresNew() bool

RequiresNew returns true if the diff requires the creation of a new resource (implying the destruction of the old).

func (*InstanceDiff) Same

func (d *InstanceDiff) Same(d2 *InstanceDiff) (bool, string)

Same checks whether or not two InstanceDiff's are the "same". When we say "same", it is not necessarily exactly equal. Instead, it is just checking that the same attributes are changing, a destroy isn't suddenly happening, etc.

func (*InstanceDiff) Unlock

func (d *InstanceDiff) Unlock()

type InstanceInfo

type InstanceInfo struct {
	// Id is a unique name to represent this instance. This is not related
	// to InstanceState.ID in any way.
	Id string

	// ModulePath is the complete path of the module containing this
	// instance.
	ModulePath []string

	// Type is the resource type of this instance
	Type string
}

InstanceInfo is used to hold information about the instance and/or resource being modified.

type InstanceState

type InstanceState struct {
	// A unique ID for this resource. This is opaque to Terraform
	// and is only meant as a lookup mechanism for the providers.
	ID string `json:"id"`

	// Attributes are basic information about the resource. Any keys here
	// are accessible in variable format within Terraform configurations:
	// ${resourcetype.name.attribute}.
	Attributes map[string]string `json:"attributes"`

	// Ephemeral is used to store any state associated with this instance
	// that is necessary for the Terraform run to complete, but is not
	// persisted to a state file.
	Ephemeral EphemeralState `json:"-"`

	// Meta is a simple K/V map that is persisted to the State but otherwise
	// ignored by Terraform core. It's meant to be used for accounting by
	// external client code. The value here must only contain Go primitives
	// and collections.
	Meta map[string]interface{} `json:"meta"`

	ProviderMeta cty.Value

	// Tainted is used to mark a resource for recreation.
	Tainted bool `json:"tainted"`
	// contains filtered or unexported fields
}

InstanceState is used to track the unique state information belonging to a given instance.

func NewInstanceStateShimmedFromValue

func NewInstanceStateShimmedFromValue(state cty.Value, schemaVersion int) *InstanceState

NewInstanceStateShimmedFromValue is a shim method to lower a new-style object value representing the attributes of an instance object into the legacy InstanceState representation.

This is for shimming to old components only and should not be used in new code.

func (*InstanceState) AttrsAsObjectValue

func (s *InstanceState) AttrsAsObjectValue(ty cty.Type) (cty.Value, error)

AttrsAsObjectValue shims from the legacy InstanceState representation to a new-style cty object value representation of the state attributes, using the given type for guidance.

The given type must be the implied type of the schema of the resource type of the object whose state is being converted, or the result is undefined.

This is for shimming from old components only and should not be used in new code.

func (*InstanceState) DeepCopy

func (s *InstanceState) DeepCopy() *InstanceState

func (*InstanceState) Empty

func (s *InstanceState) Empty() bool

func (*InstanceState) Equal

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

func (*InstanceState) Lock

func (s *InstanceState) Lock()

func (*InstanceState) MergeDiff

func (s *InstanceState) MergeDiff(d *InstanceDiff) *InstanceState

MergeDiff takes a ResourceDiff and merges the attributes into this resource state in order to generate a new state. This new state can be used to provide updated attribute lookups for variable interpolation.

If the diff attribute requires computing the value, and hence won't be available until apply, the value is replaced with the computeID.

func (*InstanceState) Set

func (s *InstanceState) Set(from *InstanceState)

Copy all the Fields from another InstanceState

func (*InstanceState) String

func (s *InstanceState) String() string

func (*InstanceState) Unlock

func (s *InstanceState) Unlock()

type ModuleState

type ModuleState struct {
	// Path is the import path from the root module. Modules imports are
	// always disjoint, so the path represents amodule tree
	Path []string `json:"path"`

	// Locals are kept only transiently in-memory, because we can always
	// re-compute them.
	Locals map[string]interface{} `json:"-"`

	// Outputs declared by the module and maintained for each module
	// even though only the root module technically needs to be kept.
	// This allows operators to inspect values at the boundaries.
	Outputs map[string]*OutputState `json:"outputs"`

	// Resources is a mapping of the logically named resource to
	// the state of the resource. Each resource may actually have
	// N instances underneath, although a user only needs to think
	// about the 1:1 case.
	Resources map[string]*ResourceState `json:"resources"`

	// Dependencies are a list of things that this module relies on
	// existing to remain intact. For example: an module may depend
	// on a VPC ID given by an aws_vpc resource.
	//
	// Terraform uses this information to build valid destruction
	// orders and to warn the user if they're destroying a module that
	// another resource depends on.
	//
	// Things can be put into this list that may not be managed by
	// Terraform. If Terraform doesn't find a matching ID in the
	// overall state, then it assumes it isn't managed and doesn't
	// worry about it.
	Dependencies []string `json:"depends_on"`
	// contains filtered or unexported fields
}

ModuleState is used to track all the state relevant to a single module. Previous to Terraform 0.3, all state belonged to the "root" module.

func (*ModuleState) Equal

func (m *ModuleState) Equal(other *ModuleState) bool

Equal tests whether one module state is equal to another.

func (*ModuleState) Lock

func (s *ModuleState) Lock()

func (*ModuleState) String

func (m *ModuleState) String() string

func (*ModuleState) Unlock

func (s *ModuleState) Unlock()

type OutputState

type OutputState struct {
	// Sensitive describes whether the output is considered sensitive,
	// which may lead to masking the value on screen in some cases.
	Sensitive bool `json:"sensitive"`
	// Type describes the structure of Value. Valid values are "string",
	// "map" and "list"
	Type string `json:"type"`
	// Value contains the value of the output, in the structure described
	// by the Type field.
	Value interface{} `json:"value"`
	// contains filtered or unexported fields
}

OutputState is used to track the state relevant to a single output.

func (*OutputState) Equal

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

Equal compares two OutputState structures for equality. nil values are considered equal.

func (*OutputState) Lock

func (s *OutputState) Lock()

func (*OutputState) String

func (s *OutputState) String() string

func (*OutputState) Unlock

func (s *OutputState) Unlock()

type ProviderSchema

type ProviderSchema struct {
	Provider      *configschema.Block
	ResourceTypes map[string]*configschema.Block
	DataSources   map[string]*configschema.Block

	ResourceTypeSchemaVersions map[string]uint64
}

ProviderSchema represents the schema for a provider's own configuration and the configuration for some or all of its resources and data sources.

The completeness of this structure depends on how it was constructed. When constructed for a configuration, it will generally include only resource types and data sources used by that configuration.

type ProviderSchemaRequest

type ProviderSchemaRequest struct {
	ResourceTypes []string
	DataSources   []string
}

ProviderSchemaRequest is used to describe to a ResourceProvider which aspects of schema are required, when calling the GetSchema method.

type RemoteState

type RemoteState struct {
	// Type controls the client we use for the remote state
	Type string `json:"type"`

	// Config is used to store arbitrary configuration that
	// is type specific
	Config map[string]string `json:"config"`
	// contains filtered or unexported fields
}

RemoteState is used to track the information about a remote state store that we push/pull state to.

func (*RemoteState) Empty

func (r *RemoteState) Empty() bool

func (*RemoteState) Lock

func (s *RemoteState) Lock()

func (*RemoteState) Unlock

func (s *RemoteState) Unlock()

type ResourceAttrDiff

type ResourceAttrDiff struct {
	Old         string      // Old Value
	New         string      // New Value
	NewComputed bool        // True if new value is computed (unknown currently)
	NewRemoved  bool        // True if this attribute is being removed
	NewExtra    interface{} // Extra information for the provider
	RequiresNew bool        // True if change requires new resource
	Sensitive   bool        // True if the data should not be displayed in UI output
	Type        diffAttrType
}

ResourceAttrDiff is the diff of a single attribute of a resource.

func (*ResourceAttrDiff) GoString

func (d *ResourceAttrDiff) GoString() string

type ResourceConfig

type ResourceConfig struct {
	ComputedKeys []string
	Raw          map[string]interface{}
	Config       map[string]interface{}
}

ResourceConfig is a legacy type that was formerly used to represent interpolatable configuration blocks. It is now only used to shim to old APIs that still use this type, via NewResourceConfigShimmed.

func NewResourceConfigRaw

func NewResourceConfigRaw(raw map[string]interface{}) *ResourceConfig

NewResourceConfigRaw constructs a ResourceConfig whose content is exactly the given value.

The given value may contain hcl2shim.UnknownVariableValue to signal that something is computed, but it must not contain unprocessed interpolation sequences as we might've seen in Terraform v0.11 and prior.

func NewResourceConfigShimmed

func NewResourceConfigShimmed(val cty.Value, schema *configschema.Block) *ResourceConfig

NewResourceConfigShimmed wraps a cty.Value of object type in a legacy ResourceConfig object, so that it can be passed to older APIs that expect this wrapping.

The returned ResourceConfig is already interpolated and cannot be re-interpolated. It is, therefore, useful only to functions that expect an already-populated ResourceConfig which they then treat as read-only.

If the given value is not of an object type that conforms to the given schema then this function will panic.

func (*ResourceConfig) DeepCopy

func (c *ResourceConfig) DeepCopy() *ResourceConfig

DeepCopy performs a deep copy of the configuration. This makes it safe to modify any of the structures that are part of the resource config without affecting the original configuration.

func (*ResourceConfig) Equal

func (c *ResourceConfig) Equal(c2 *ResourceConfig) bool

Equal checks the equality of two resource configs.

func (*ResourceConfig) Get

func (c *ResourceConfig) Get(k string) (interface{}, bool)

Get looks up a configuration value by key and returns the value.

The second return value is true if the get was successful. Get will return the raw value if the key is computed, so you should pair this with IsComputed.

func (*ResourceConfig) GetRaw

func (c *ResourceConfig) GetRaw(k string) (interface{}, bool)

GetRaw looks up a configuration value by key and returns the value, from the raw, uninterpolated config.

The second return value is true if the get was successful. Get will not succeed if the value is being computed.

func (*ResourceConfig) IsComputed

func (c *ResourceConfig) IsComputed(k string) bool

IsComputed returns whether the given key is computed or not.

type ResourceMode

type ResourceMode int

ResourceMode is deprecated, use addrs.ResourceMode instead. It has been preserved for backwards compatibility.

const (
	ManagedResourceMode ResourceMode = iota
	DataResourceMode
)

func (ResourceMode) String

func (i ResourceMode) String() string

type ResourceState

type ResourceState struct {
	// This is filled in and managed by Terraform, and is the resource
	// type itself such as "mycloud_instance". If a resource provider sets
	// this value, it won't be persisted.
	Type string `json:"type"`

	// Dependencies are a list of things that this resource relies on
	// existing to remain intact. For example: an AWS instance might
	// depend on a subnet (which itself might depend on a VPC, and so
	// on).
	//
	// Terraform uses this information to build valid destruction
	// orders and to warn the user if they're destroying a resource that
	// another resource depends on.
	//
	// Things can be put into this list that may not be managed by
	// Terraform. If Terraform doesn't find a matching ID in the
	// overall state, then it assumes it isn't managed and doesn't
	// worry about it.
	Dependencies []string `json:"depends_on"`

	// Primary is the current active instance for this resource.
	// It can be replaced but only after a successful creation.
	// This is the instances on which providers will act.
	Primary *InstanceState `json:"primary"`

	// Deposed is used in the mechanics of CreateBeforeDestroy: the existing
	// Primary is Deposed to get it out of the way for the replacement Primary to
	// be created by Apply. If the replacement Primary creates successfully, the
	// Deposed instance is cleaned up.
	//
	// If there were problems creating the replacement Primary, the Deposed
	// instance and the (now tainted) replacement Primary will be swapped so the
	// tainted replacement will be cleaned up instead.
	//
	// An instance will remain in the Deposed list until it is successfully
	// destroyed and purged.
	Deposed []*InstanceState `json:"deposed"`

	// Provider is used when a resource is connected to a provider with an alias.
	// If this string is empty, the resource is connected to the default provider,
	// e.g. "aws_instance" goes with the "aws" provider.
	// If the resource block contained a "provider" key, that value will be set here.
	Provider string `json:"provider"`
	// contains filtered or unexported fields
}

ResourceState holds the state of a resource that is used so that a provider can find and manage an existing resource as well as for storing attributes that are used to populate variables of child resources.

Attributes has attributes about the created resource that are queryable in interpolation: "${type.id.attr}"

Extra is just extra data that a provider can return that we store for later, but is not exposed in any way to the user.

func (*ResourceState) Equal

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

Equal tests whether two ResourceStates are equal.

func (*ResourceState) Lock

func (s *ResourceState) Lock()

func (*ResourceState) String

func (s *ResourceState) String() string

func (*ResourceState) Taint

func (s *ResourceState) Taint()

Taint marks a resource as tainted.

func (*ResourceState) Unlock

func (s *ResourceState) Unlock()

func (*ResourceState) Untaint

func (s *ResourceState) Untaint()

Untaint unmarks a resource as tainted.

type ResourceStateKey

type ResourceStateKey struct {
	Name  string
	Type  string
	Mode  ResourceMode
	Index int
}

ResourceStateKey is a structured representation of the key used for the ModuleState.Resources mapping

func (*ResourceStateKey) Equal

func (rsk *ResourceStateKey) Equal(other *ResourceStateKey) bool

Equal determines whether two ResourceStateKeys are the same

func (*ResourceStateKey) String

func (rsk *ResourceStateKey) String() string

type ResourceType

type ResourceType struct {
	Name       string // Name of the resource, example "instance" (no provider prefix)
	Importable bool   // Whether this resource supports importing

	// SchemaAvailable is set if the provider supports the ProviderSchema,
	// ResourceTypeSchema and DataSourceSchema methods. Although it is
	// included on each resource type, it's actually a provider-wide setting
	// that's smuggled here only because that avoids a breaking change to
	// the plugin protocol.
	SchemaAvailable bool
}

ResourceType is a type of resource that a resource provider can manage.

type State

type State struct {
	// Version is the state file protocol version.
	Version int `json:"version"`

	// TFVersion is the version of Terraform that wrote this state.
	TFVersion string `json:"terraform_version,omitempty"`

	// Serial is incremented on any operation that modifies
	// the State file. It is used to detect potentially conflicting
	// updates.
	Serial int64 `json:"serial"`

	// Lineage is set when a new, blank state is created and then
	// never updated. This allows us to determine whether the serials
	// of two states can be meaningfully compared.
	// Apart from the guarantee that collisions between two lineages
	// are very unlikely, this value is opaque and external callers
	// should only compare lineage strings byte-for-byte for equality.
	Lineage string `json:"lineage"`

	// Remote is used to track the metadata required to
	// pull and push state files from a remote storage endpoint.
	Remote *RemoteState `json:"remote,omitempty"`

	// Backend tracks the configuration for the backend in use with
	// this state. This is used to track any changes in the backend
	// configuration.
	Backend *BackendState `json:"backend,omitempty"`

	// Modules contains all the modules in a breadth-first order
	Modules []*ModuleState `json:"modules"`

	// IsBinaryDrivenTest is a special flag that assists with a binary driver
	// heuristic, it should not be set externally
	IsBinaryDrivenTest bool
	// contains filtered or unexported fields
}

State keeps track of a snapshot state-of-the-world that Terraform can use to keep track of what real world resources it is actually managing.

func NewState

func NewState() *State

NewState is used to initialize a blank state

func (*State) AddModule

func (s *State) AddModule(path addrs.ModuleInstance) *ModuleState

AddModule adds the module with the given path to the state.

This should be the preferred method to add module states since it allows us to optimize lookups later as well as control sorting.

func (*State) AddModuleState

func (s *State) AddModuleState(mod *ModuleState)

AddModuleState insert this module state and override any existing ModuleState

func (*State) Children

func (s *State) Children(path []string) []*ModuleState

Children returns the ModuleStates that are direct children of the given path. If the path is "root", for example, then children returned might be "root.child", but not "root.child.grandchild".

func (*State) CompareAges

func (s *State) CompareAges(other *State) (StateAgeComparison, error)

CompareAges compares one state with another for which is "older".

This is a simple check using the state's serial, and is thus only as reliable as the serial itself. In the normal case, only one state exists for a given combination of lineage/serial, but Terraform does not guarantee this and so the result of this method should be used with care.

Returns an integer that is negative if the receiver is older than the argument, positive if the converse, and zero if they are equal. An error is returned if the two states are not of the same lineage, in which case the integer returned has no meaning.

func (*State) DeepCopy

func (s *State) DeepCopy() *State

DeepCopy performs a deep copy of the state structure and returns a new structure.

func (*State) Empty

func (s *State) Empty() bool

Empty returns true if the state is empty.

func (*State) EnsureHasLineage

func (s *State) EnsureHasLineage()

func (*State) Equal

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

Equal tests if one state is equal to another.

func (*State) HasResources

func (s *State) HasResources() bool

HasResources returns true if the state contains any resources.

This is similar to !s.Empty, but returns true also in the case where the state has modules but all of them are devoid of resources.

func (*State) Init

func (s *State) Init()

func (*State) IsRemote

func (s *State) IsRemote() bool

IsRemote returns true if State represents a state that exists and is remote.

func (*State) Lock

func (s *State) Lock()

func (*State) ModuleByPath

func (s *State) ModuleByPath(path addrs.ModuleInstance) *ModuleState

ModuleByPath is used to lookup the module state for the given path. This should be the preferred lookup mechanism as it allows for future lookup optimizations.

func (*State) Remove

func (s *State) Remove(addr ...string) error

Remove removes the item in the state at the given address, returning any errors that may have occurred.

If the address references a module state or resource, it will delete all children as well. To check what will be deleted, use a StateFilter first.

func (*State) RootModule

func (s *State) RootModule() *ModuleState

RootModule returns the ModuleState for the root module

func (*State) SameLineage

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

SameLineage returns true only if the state given in argument belongs to the same "lineage" of states as the receiver.

func (*State) String

func (s *State) String() string

func (*State) Unlock

func (s *State) Unlock()

func (*State) Validate

func (s *State) Validate() error

Validate validates the integrity of this state file.

Certain properties of the statefile are expected by Terraform in order to behave properly. The core of Terraform will assume that once it receives a State structure that it has been validated. This validation check should be called to ensure that.

If this returns an error, then the user should be notified. The error response will include detailed information on the nature of the error.

type StateAgeComparison

type StateAgeComparison int
const (
	StateAgeEqual         StateAgeComparison = 0
	StateAgeReceiverNewer StateAgeComparison = 1
	StateAgeReceiverOlder StateAgeComparison = -1
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL