terraform

package
v2.34.0 Latest Latest
Warning

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

 Go to latest Published: May 17, 2024 License: MPL-2.0 Imports: 20 Imported by: 222

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

	RawConfig cty.Value
	RawState  cty.Value
	RawPlan   cty.Value

	// 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

	RawConfig cty.Value
	RawState  cty.Value
	RawPlan   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{}

	// CtyValue is the raw protocol configuration data from newer APIs.
	//
	// This field was only added as a targeted fix for passing raw protocol data
	// through the existing (helper/schema.Provider).Configure() exported method
	// and is only populated in that situation. The data could theoretically be
	// set in the NewResourceConfigShimmed() function, however the consequences
	// of doing this were not investigated at the time the fix was introduced.
	//
	// This field is ignored in the Equal() method to prevent a breaking
	// behavior change since the entirety of the terraform package and this type
	// are unintentionally exported in v2.
	//
	// Reference: https://github.com/hashicorp/terraform-plugin-sdk/issues/1270
	CtyValue cty.Value
}

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.

This method intentionally ignores the CtyValue field as a major version compatibility concern, as this exported field was later added to the type. Reference: https://github.com/hashicorp/terraform-plugin-sdk/issues/1270

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) Unlock 

func (s *ResourceState) Unlock()

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
)

Source Files

View all Source files

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.