addrs

package
v1.2.4 Latest Latest
Warning

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

 Go to latest Published: Jun 29, 2022 License: MPL-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package addrs contains types that represent "addresses", which are references to specific objects within a Terraform configuration or state.

All addresses have string representations based on HCL traversal syntax which should be used in the user-interface, and also in-memory representations that can be used internally.

For object types that exist within Terraform modules a pair of types is used. The "local" part of the address is represented by a type, and then an absolute path to that object in the context of its module is represented by a type of the same name with an "Abs" prefix added, for "absolute".

All types within this package should be treated as immutable, even if this is not enforced by the Go compiler. It is always an implementation error to modify an address object in-place after it is initially constructed.

Index

Constants

View Source 
const BuiltInProviderHost = svchost.Hostname("terraform.io")

BuiltInProviderHost is the pseudo-hostname used for the "built-in" provider namespace. Built-in provider addresses must also have their namespace set to BuiltInProviderNamespace in order to be considered as built-in.

View Source 
const BuiltInProviderNamespace = "builtin"

BuiltInProviderNamespace is the provider namespace used for "built-in" providers. Built-in provider addresses must also have their hostname set to BuiltInProviderHost in order to be considered as built-in.

The this namespace is literally named "builtin", in the hope that users who see FQNs containing this will be able to infer the way in which they are special, even if they haven't encountered the concept formally yet.

View Source 
const DefaultModuleRegistryHost = svchost.Hostname("registry.terraform.io")

DefaultModuleRegistryHost is the hostname used for registry-based module source addresses that do not have an explicit hostname.

View Source 
const DefaultProviderRegistryHost = svchost.Hostname("registry.terraform.io")

DefaultProviderRegistryHost is the hostname used for provider addresses that do not have an explicit hostname.

View Source 
const LegacyProviderNamespace = "-"

LegacyProviderNamespace is the special string used in the Namespace field of type Provider to mark a legacy provider address. This special namespace value would normally be invalid, and can be used only when the hostname is DefaultRegistryHost because that host owns the mapping from legacy name to FQN.

View Source 
const Self selfT = 0

Self is the address of the special object "self" that behaves as an alias for a containing object currently in scope.

Variables

This section is empty.

Functions

func InstanceKeyLess 

func InstanceKeyLess(i, j InstanceKey) bool

InstanceKeyLess returns true if the first given instance key i should sort before the second key j, and false otherwise.

func IsProviderPartNormalized 

func IsProviderPartNormalized(str string) (bool, error)

IsProviderPartNormalized compares a given string to the result of ParseProviderPart(string)

func MustParseProviderPart 

func MustParseProviderPart(given string) string

MustParseProviderPart is a wrapper around ParseProviderPart that panics if it returns an error.

func ParseProviderPart 

func ParseProviderPart(given string) (string, error)

ParseProviderPart processes an addrs.Provider namespace or type string provided by an end-user, producing a normalized version if possible or an error if the string contains invalid characters.

A provider part is processed in the same way as an individual label in a DNS domain name: it is transformed to lowercase per the usual DNS case mapping and normalization rules and may contain only letters, digits, and dashes. Additionally, dashes may not appear at the start or end of the string.

These restrictions are intended to allow these names to appear in fussy contexts such as directory/file names on case-insensitive filesystems, repository names on GitHub, etc. We're using the DNS rules in particular, rather than some similar rules defined locally, because the hostname part of an addrs.Provider is already a hostname and it's ideal to use exactly the same case folding and normalization rules for all of the parts.

In practice a provider type string conventionally does not contain dashes either. Such names are permitted, but providers with such type names will be hard to use because their resource type names will not be able to contain the provider type name and thus each resource will need an explicit provider address specified. (A real-world example of such a provider is the "google-beta" variant of the GCP provider, which has resource types that start with the "google_" prefix instead.)

It's valid to pass the result of this function as the argument to a subsequent call, in which case the result will be identical.

Types

type AbsInputVariableInstance 

type AbsInputVariableInstance struct {
	Module   ModuleInstance
	Variable InputVariable
}

AbsInputVariableInstance is the address of an input variable within a particular module instance.

func (AbsInputVariableInstance) String 

func (v AbsInputVariableInstance) String() string

type AbsLocalValue 

type AbsLocalValue struct {
	Module     ModuleInstance
	LocalValue LocalValue
}

AbsLocalValue is the absolute address of a local value within a module instance.

func (AbsLocalValue) String 

func (v AbsLocalValue) String() string

type AbsModuleCall added in v1.1.0 

type AbsModuleCall struct {
	Module ModuleInstance
	Call   ModuleCall
}

AbsModuleCall is the address of a "module" block relative to the root of the configuration.

This is similar to ModuleInstance alone, but specifically represents the module block itself rather than any one of the instances that module block declares.

func (AbsModuleCall) Equal added in v1.1.0 

func (c AbsModuleCall) Equal(other AbsModuleCall) bool

func (AbsModuleCall) Instance added in v1.1.0 

func (c AbsModuleCall) Instance(key InstanceKey) ModuleInstance

func (AbsModuleCall) String added in v1.1.0 

func (c AbsModuleCall) String() string

func (AbsModuleCall) UniqueKey added in v1.1.0 

func (c AbsModuleCall) UniqueKey() UniqueKey

type AbsMoveable added in v1.1.0 

type AbsMoveable interface {
	UniqueKeyer

	String() string
	// contains filtered or unexported methods
}

AbsMoveable is an interface implemented by address types that can be either the source or destination of a "moved" statement in configuration, along with any other similar cross-module state refactoring statements we might allow.

Note that AbsMoveable represents an absolute address relative to the root of the configuration, which is different than the direct representation of these in configuration where the author gives an address relative to the current module where the address is defined. The type MoveEndpoint

type AbsMoveableResource added in v1.1.0 

type AbsMoveableResource interface {
	AbsMoveable
	AffectedAbsResource() AbsResource
}

AbsMoveableResource is an AbsMoveable that is either a resource or a resource instance.

type AbsOutputValue 

type AbsOutputValue struct {
	Module      ModuleInstance
	OutputValue OutputValue
	// contains filtered or unexported fields
}

AbsOutputValue is the absolute address of an output value within a module instance.

This represents an output globally within the namespace of a particular configuration. It is related to but separate from ModuleCallOutput, which represents a module output from the perspective of its parent module.

func ParseAbsOutputValue added in v1.2.0 

func ParseAbsOutputValue(traversal hcl.Traversal) (AbsOutputValue, tfdiags.Diagnostics)

func ParseAbsOutputValueStr added in v1.2.0 

func ParseAbsOutputValueStr(str string) (AbsOutputValue, tfdiags.Diagnostics)

func (AbsOutputValue) Check added in v1.2.0 

func (v AbsOutputValue) Check(t CheckType, i int) Check

func (AbsOutputValue) Equal 

func (v AbsOutputValue) Equal(o AbsOutputValue) bool

func (AbsOutputValue) ModuleCallOutput 

func (v AbsOutputValue) ModuleCallOutput() (ModuleInstance, ModuleCallInstanceOutput)

ModuleCallOutput converts an AbsModuleOutput into a ModuleCallOutput, returning also the module instance that the ModuleCallOutput is relative to.

The root module does not have a call, and so this method cannot be used with outputs in the root module, and will panic in that case.

func (AbsOutputValue) String 

func (v AbsOutputValue) String() string

type AbsProviderConfig 

type AbsProviderConfig struct {
	Module   Module
	Provider Provider
	Alias    string
}

AbsProviderConfig is the absolute address of a provider configuration within a particular module instance.

func ParseAbsProviderConfig 

func ParseAbsProviderConfig(traversal hcl.Traversal) (AbsProviderConfig, tfdiags.Diagnostics)

ParseAbsProviderConfig parses the given traversal as an absolute provider address. The following are examples of traversals that can be successfully parsed as absolute provider configuration addresses: 

provider["registry.terraform.io/hashicorp/aws"]
provider["registry.terraform.io/hashicorp/aws"].foo
module.bar.provider["registry.terraform.io/hashicorp/aws"]
module.bar.module.baz.provider["registry.terraform.io/hashicorp/aws"].foo

This type of address is used, for example, to record the relationships between resources and provider configurations in the state structure. This type of address is not generally used in the UI, except in error messages that refer to provider configurations.

func ParseAbsProviderConfigStr 

func ParseAbsProviderConfigStr(str string) (AbsProviderConfig, tfdiags.Diagnostics)

ParseAbsProviderConfigStr is a helper wrapper around ParseAbsProviderConfig that takes a string and parses it with the HCL native syntax traversal parser before interpreting it.

This should be used only in specialized situations since it will cause the created references to not have any meaningful source location information. If a reference string is coming from a source that should be identified in error messages then the caller should instead parse it directly using a suitable function from the HCL API and pass the traversal itself to ParseAbsProviderConfig.

Error diagnostics are returned if either the parsing fails or the analysis of the traversal fails. There is no way for the caller to distinguish the two kinds of diagnostics programmatically. If error diagnostics are returned the returned address is invalid.

func ParseLegacyAbsProviderConfig 

func ParseLegacyAbsProviderConfig(traversal hcl.Traversal) (AbsProviderConfig, tfdiags.Diagnostics)

ParseLegacyAbsProviderConfig parses the given traversal as an absolute provider address. The following are examples of traversals that can be successfully parsed as legacy absolute provider configuration addresses: 

provider.aws
provider.aws.foo
module.bar.provider.aws
module.bar.module.baz.provider.aws.foo

This type of address is used in legacy state and may appear in state v4 if the provider config addresses have not been normalized to include provider FQN.

func ParseLegacyAbsProviderConfigStr 

func ParseLegacyAbsProviderConfigStr(str string) (AbsProviderConfig, tfdiags.Diagnostics)

func (AbsProviderConfig) Inherited 

func (pc AbsProviderConfig) Inherited() (AbsProviderConfig, bool)

Inherited returns an address that the receiving configuration address might inherit from in a parent module. The second bool return value indicates if such inheritance is possible, and thus whether the returned address is valid.

Inheritance is possible only for default (un-aliased) providers in modules other than the root module. Even if a valid address is returned, inheritence may not be performed for other reasons, such as if the calling module provided explicit provider configurations within the call for this module. The ProviderTransformer graph transform in the main terraform module has the authoritative logic for provider inheritance, and this method is here mainly just for its benefit.

func (AbsProviderConfig) LegacyString 

func (pc AbsProviderConfig) LegacyString() string

LegacyString() returns a legacy-style AbsProviderConfig string and should only be used for legacy state shimming.

func (AbsProviderConfig) String 

func (pc AbsProviderConfig) String() string

String() returns a string representation of an AbsProviderConfig in the following format: 

provider["example.com/namespace/name"]
provider["example.com/namespace/name"].alias
module.module-name.provider["example.com/namespace/name"]
module.module-name.provider["example.com/namespace/name"].alias

type AbsResource 

type AbsResource struct {
	Module   ModuleInstance
	Resource Resource
	// contains filtered or unexported fields
}

AbsResource is an absolute address for a resource under a given module path.

func ParseAbsResource 

func ParseAbsResource(traversal hcl.Traversal) (AbsResource, tfdiags.Diagnostics)

ParseAbsResource attempts to interpret the given traversal as an absolute resource address, using the same syntax as expected by ParseTarget.

If no error diagnostics are returned, the returned target includes the address that was extracted and the source range it was extracted from.

If error diagnostics are returned then the AbsResource value is invalid and must not be used.

func ParseAbsResourceStr 

func ParseAbsResourceStr(str string) (AbsResource, tfdiags.Diagnostics)

ParseAbsResourceStr is a helper wrapper around ParseAbsResource that takes a string and parses it with the HCL native syntax traversal parser before interpreting it.

Error diagnostics are returned if either the parsing fails or the analysis of the traversal fails. There is no way for the caller to distinguish the two kinds of diagnostics programmatically. If error diagnostics are returned the returned address may be incomplete.

Since this function has no context about the source of the given string, any returned diagnostics will not have meaningful source location information.

func (AbsResource) AddrType added in v1.1.0 

func (r AbsResource) AddrType() TargetableAddrType

func (AbsResource) AffectedAbsResource added in v1.1.0 

func (r AbsResource) AffectedAbsResource() AbsResource

AffectedAbsResource returns the AbsResource.

func (AbsResource) Config 

func (r AbsResource) Config() ConfigResource

Config returns the unexpanded ConfigResource for this AbsResource.

func (AbsResource) Equal 

func (r AbsResource) Equal(o AbsResource) bool

func (AbsResource) Instance 

func (r AbsResource) Instance(key InstanceKey) AbsResourceInstance

Instance produces the address for a specific instance of the receiver that is idenfied by the given key.

func (AbsResource) MoveDestination added in v1.1.0 

func (r AbsResource) MoveDestination(fromMatch, toMatch *MoveEndpointInModule) (AbsResource, bool)

MoveDestination considers a an address representing a resource in the context of source and destination move endpoints and then, if the resource address matches the from endpoint, returns the corresponding new resource address that the object should move to.

MoveDestination will return false in its second return value if the receiver doesn't match fromMatch, indicating that the given move statement doesn't apply to this object.

Both of the given endpoints must be from the same move statement and thus must have matching object types. If not, MoveDestination will panic.

func (AbsResource) String 

func (r AbsResource) String() string

func (AbsResource) TargetContains 

func (r AbsResource) TargetContains(other Targetable) bool

TargetContains implements Targetable by returning true if the given other address is either equal to the receiver or is an instance of the receiver.

func (AbsResource) UniqueKey added in v1.1.0 

func (r AbsResource) UniqueKey() UniqueKey

type AbsResourceInstance 

type AbsResourceInstance struct {
	Module   ModuleInstance
	Resource ResourceInstance
	// contains filtered or unexported fields
}

AbsResourceInstance is an absolute address for a resource instance under a given module path.

func ParseAbsResourceInstance 

func ParseAbsResourceInstance(traversal hcl.Traversal) (AbsResourceInstance, tfdiags.Diagnostics)

ParseAbsResourceInstance attempts to interpret the given traversal as an absolute resource instance address, using the same syntax as expected by ParseTarget.

If no error diagnostics are returned, the returned target includes the address that was extracted and the source range it was extracted from.

If error diagnostics are returned then the AbsResource value is invalid and must not be used.

func ParseAbsResourceInstanceStr 

func ParseAbsResourceInstanceStr(str string) (AbsResourceInstance, tfdiags.Diagnostics)

ParseAbsResourceInstanceStr is a helper wrapper around ParseAbsResourceInstance that takes a string and parses it with the HCL native syntax traversal parser before interpreting it.

Error diagnostics are returned if either the parsing fails or the analysis of the traversal fails. There is no way for the caller to distinguish the two kinds of diagnostics programmatically. If error diagnostics are returned the returned address may be incomplete.

Since this function has no context about the source of the given string, any returned diagnostics will not have meaningful source location information.

func (AbsResourceInstance) AddrType added in v1.1.0 

func (r AbsResourceInstance) AddrType() TargetableAddrType

func (AbsResourceInstance) AffectedAbsResource added in v1.1.0 

func (r AbsResourceInstance) AffectedAbsResource() AbsResource

AffectedAbsResource returns the AbsResource for the instance.

func (AbsResourceInstance) Check added in v1.2.0 

func (r AbsResourceInstance) Check(t CheckType, i int) Check

func (AbsResourceInstance) ContainingResource 

func (r AbsResourceInstance) ContainingResource() AbsResource

ContainingResource returns the address of the resource that contains the receving resource instance. In other words, it discards the key portion of the address to produce an AbsResource value.

func (AbsResourceInstance) Equal 

func (r AbsResourceInstance) Equal(o AbsResourceInstance) bool

func (AbsResourceInstance) Less 

func (r AbsResourceInstance) Less(o AbsResourceInstance) bool

Less returns true if the receiver should sort before the given other value in a sorted list of addresses.

func (AbsResourceInstance) MoveDestination added in v1.1.0 

func (r AbsResourceInstance) MoveDestination(fromMatch, toMatch *MoveEndpointInModule) (AbsResourceInstance, bool)

MoveDestination considers a an address representing a resource instance in the context of source and destination move endpoints and then, if the instance address matches the from endpoint, returns the corresponding new instance address that the object should move to.

MoveDestination will return false in its second return value if the receiver doesn't match fromMatch, indicating that the given move statement doesn't apply to this object.

Both of the given endpoints must be from the same move statement and thus must have matching object types. If not, MoveDestination will panic.

func (AbsResourceInstance) String 

func (r AbsResourceInstance) String() string

func (AbsResourceInstance) TargetContains 

func (r AbsResourceInstance) TargetContains(other Targetable) bool

TargetContains implements Targetable by returning true if the given other address is equal to the receiver.

func (AbsResourceInstance) UniqueKey added in v1.1.0 

func (r AbsResourceInstance) UniqueKey() UniqueKey

type Check added in v1.2.0 

type Check struct {
	Container Checkable
	Type      CheckType
	Index     int
}

Check is the address of a check rule within a checkable object.

This represents the check rule globally within a configuration, and is used during graph evaluation to identify a condition result object to update with the result of check rule evaluation.

The check address is not distinct from resource traversals, and check rule values are not intended to be available to the language, so the address is not Referenceable.

Note also that the check address is only relevant within the scope of a run, as reordering check blocks between runs will result in their addresses changing.

func (Check) String added in v1.2.0 

func (c Check) String() string

type CheckType added in v1.2.0 

type CheckType int

CheckType describes the category of check. 

const (
	InvalidCondition      CheckType = 0
	ResourcePrecondition  CheckType = 1
	ResourcePostcondition CheckType = 2
	OutputPrecondition    CheckType = 3
)

func (CheckType) Description added in v1.2.0 

func (c CheckType) Description() string

Description returns a human-readable description of the check type. This is presented in the user interface through a diagnostic summary.

func (CheckType) String added in v1.2.0 

func (i CheckType) String() string

type Checkable added in v1.2.0 

type Checkable interface {

	// Check returns the address of an individual check rule of a specified
	// type and index within this checkable container.
	Check(CheckType, int) Check
	String() string
	// contains filtered or unexported methods
}

Checkable is an interface implemented by all address types that can contain condition blocks.

type ConfigMoveable added in v1.1.0 

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

ConfigMoveable is similar to AbsMoveable but represents a static object in the configuration, rather than an instance of that object created by module expansion.

Note that ConfigMovable represents an absolute address relative to the root of the configuration, which is different than the direct representation of these in configuration where the author gives an address relative to the current module where the address is defined. The type MoveEndpoint represents the relative form given directly in configuration.

type ConfigResource 

type ConfigResource struct {
	Module   Module
	Resource Resource
	// contains filtered or unexported fields
}

ConfigResource is an address for a resource within a configuration.

func (ConfigResource) Absolute 

func (r ConfigResource) Absolute(module ModuleInstance) AbsResource

Absolute produces the address for the receiver within a specific module instance.

func (ConfigResource) AddrType added in v1.1.0 

func (r ConfigResource) AddrType() TargetableAddrType

func (ConfigResource) Equal 

func (r ConfigResource) Equal(o ConfigResource) bool

func (ConfigResource) String 

func (r ConfigResource) String() string

func (ConfigResource) TargetContains 

func (r ConfigResource) TargetContains(other Targetable) bool

TargetContains implements Targetable by returning true if the given other address is either equal to the receiver or is an instance of the receiver.

type CountAttr 

type CountAttr struct {
	Name string
	// contains filtered or unexported fields
}

CountAttr is the address of an attribute of the "count" object in the interpolation scope, like "count.index".

func (CountAttr) String 

func (ca CountAttr) String() string

func (CountAttr) UniqueKey added in v1.1.0 

func (ca CountAttr) UniqueKey() UniqueKey

type ForEachAttr 

type ForEachAttr struct {
	Name string
	// contains filtered or unexported fields
}

ForEachAttr is the address of an attribute referencing the current "for_each" object in the interpolation scope, addressed using the "each" keyword, ex. "each.key" and "each.value"

func (ForEachAttr) String 

func (f ForEachAttr) String() string

func (ForEachAttr) UniqueKey added in v1.1.0 

func (f ForEachAttr) UniqueKey() UniqueKey

type InputVariable 

type InputVariable struct {
	Name string
	// contains filtered or unexported fields
}

InputVariable is the address of an input variable.

func (InputVariable) Absolute 

func (v InputVariable) Absolute(m ModuleInstance) AbsInputVariableInstance

Absolute converts the receiver into an absolute address within the given module instance.

func (InputVariable) String 

func (v InputVariable) String() string

func (InputVariable) UniqueKey added in v1.1.0 

func (v InputVariable) UniqueKey() UniqueKey

type InstanceKey 

type InstanceKey interface {
	String() string

	// Value returns the cty.Value of the appropriate type for the InstanceKey
	// value.
	Value() cty.Value
	// contains filtered or unexported methods
}

InstanceKey represents the key of an instance within an object that contains multiple instances due to using "count" or "for_each" arguments in configuration.

IntKey and StringKey are the two implementations of this type. No other implementations are allowed. The single instance of an object that _isn't_ using "count" or "for_each" is represented by NoKey, which is a nil InstanceKey. 

var NoKey InstanceKey

NoKey represents the absense of an InstanceKey, for the single instance of a configuration object that does not use "count" or "for_each" at all.

func ParseInstanceKey 

func ParseInstanceKey(key cty.Value) (InstanceKey, error)

ParseInstanceKey returns the instance key corresponding to the given value, which must be known and non-null.

If an unknown or null value is provided then this function will panic. This function is intended to deal with the values that would naturally be found in a hcl.TraverseIndex, which (when parsed from source, at least) can never contain unknown or null values.

type InstanceKeyType 

type InstanceKeyType rune

InstanceKeyType represents the different types of instance key that are supported. Usually it is sufficient to simply type-assert an InstanceKey value to either IntKey or StringKey, but this type and its values can be used to represent the types themselves, rather than specific values of those types. 

const (
	NoKeyType     InstanceKeyType = 0
	IntKeyType    InstanceKeyType = 'I'
	StringKeyType InstanceKeyType = 'S'
)

type IntKey 

type IntKey int

IntKey is the InstanceKey representation representing integer indices, as used when the "count" argument is specified or if for_each is used with a sequence type.

func (IntKey) String 

func (k IntKey) String() string

func (IntKey) Value 

func (k IntKey) Value() cty.Value

type LocalProviderConfig 

type LocalProviderConfig struct {
	LocalName string

	// If not empty, Alias identifies which non-default (aliased) provider
	// configuration this address refers to.
	Alias string
}

LocalProviderConfig is the address of a provider configuration from the perspective of references in a particular module.

Finding the corresponding AbsProviderConfig will require looking up the LocalName in the providers table in the module's configuration; there is no syntax-only translation between these types.

func NewDefaultLocalProviderConfig 

func NewDefaultLocalProviderConfig(LocalNameName string) LocalProviderConfig

NewDefaultLocalProviderConfig returns the address of the default (un-aliased) configuration for the provider with the given local type name.

func (LocalProviderConfig) String 

func (pc LocalProviderConfig) String() string

func (LocalProviderConfig) StringCompact 

func (pc LocalProviderConfig) StringCompact() string

StringCompact is an alternative to String that returns the form that can be parsed by ParseProviderConfigCompact, without the "provider." prefix.

type LocalValue 

type LocalValue struct {
	Name string
	// contains filtered or unexported fields
}

LocalValue is the address of a local value.

func (LocalValue) Absolute 

func (v LocalValue) Absolute(m ModuleInstance) AbsLocalValue

Absolute converts the receiver into an absolute address within the given module instance.

func (LocalValue) String 

func (v LocalValue) String() string

func (LocalValue) UniqueKey added in v1.1.0 

func (v LocalValue) UniqueKey() UniqueKey

type Module 

type Module []string

Module is an address for a module call within configuration. This is the static counterpart of ModuleInstance, representing a traversal through the static module call tree in configuration and does not take into account the potentially-multiple instances of a module that might be created by "count" and "for_each" arguments within those calls.

This type should be used only in very specialized cases when working with the static module call tree. Type ModuleInstance is appropriate in more cases.

Although Module is a slice, it should be treated as immutable after creation. 

var RootModule Module

RootModule is the module address representing the root of the static module call tree, which is also the zero value of Module.

Note that this is not the root of the dynamic module tree, which is instead represented by RootModuleInstance.

func (Module) AddrType added in v1.1.0 

func (m Module) AddrType() TargetableAddrType

func (Module) Ancestors 

func (m Module) Ancestors() []Module

Ancestors returns a slice containing the receiver and all of its ancestor modules, all the way up to (and including) the root module. The result is ordered by depth, with the root module always first.

Since the result always includes the root module, a caller may choose to ignore it by slicing the result with [1:].

func (Module) Call 

func (m Module) Call() (Module, ModuleCall)

Call returns the module call address that corresponds to the given module instance, along with the address of the module that contains it.

There is no call for the root module, so this method will panic if called on the root module address.

In practice, this just turns the last element of the receiver into a ModuleCall and then returns a slice of the receiever that excludes that last part. This is just a convenience for situations where a call address is required, such as when dealing with *Reference and Referencable values.

func (Module) Child 

func (m Module) Child(name string) Module

Child returns the address of a child call in the receiver, identified by the given name.

func (Module) Equal 

func (m Module) Equal(other Module) bool

func (Module) IsRoot 

func (m Module) IsRoot() bool

IsRoot returns true if the receiver is the address of the root module, or false otherwise.

func (Module) Parent 

func (m Module) Parent() Module

Parent returns the address of the parent module of the receiver, or the receiver itself if there is no parent (if it's the root module address).

func (Module) Resource 

func (m Module) Resource(mode ResourceMode, typeName string, name string) ConfigResource

Resource returns the address of a particular resource within the module.

func (Module) String 

func (m Module) String() string

func (Module) TargetContains 

func (m Module) TargetContains(other Targetable) bool

TargetContains implements Targetable for Module by returning true if the given other address either matches the receiver, is a sub-module-instance of the receiver, or is a targetable absolute address within a module that is contained within the receiver.

func (Module) UnkeyedInstanceShim 

func (m Module) UnkeyedInstanceShim() ModuleInstance

UnkeyedInstanceShim is a shim method for converting a Module address to the equivalent ModuleInstance address that assumes that no modules have keyed instances.

This is a temporary allowance for the fact that Terraform does not presently support "count" and "for_each" on modules, and thus graph building code that derives graph nodes from configuration must just assume unkeyed modules in order to construct the graph. At a later time when "count" and "for_each" support is added for modules, all callers of this method will need to be reworked to allow for keyed module instances.

type ModuleCall 

type ModuleCall struct {
	Name string
	// contains filtered or unexported fields
}

ModuleCall is the address of a call from the current module to a child module.

func (ModuleCall) Absolute added in v1.1.0 

func (c ModuleCall) Absolute(moduleAddr ModuleInstance) AbsModuleCall

func (ModuleCall) Equal added in v1.1.0 

func (c ModuleCall) Equal(other ModuleCall) bool

func (ModuleCall) Instance 

func (c ModuleCall) Instance(key InstanceKey) ModuleCallInstance

Instance returns the address of an instance of the receiver identified by the given key.

func (ModuleCall) String 

func (c ModuleCall) String() string

func (ModuleCall) UniqueKey added in v1.1.0 

func (c ModuleCall) UniqueKey() UniqueKey

type ModuleCallInstance 

type ModuleCallInstance struct {
	Call ModuleCall
	Key  InstanceKey
	// contains filtered or unexported fields
}

ModuleCallInstance is the address of one instance of a module created from a module call, which might create multiple instances using "count" or "for_each" arguments.

There is no "Abs" version of ModuleCallInstance because an absolute module path is represented by ModuleInstance.

func (ModuleCallInstance) Absolute added in v1.1.0 

func (c ModuleCallInstance) Absolute(moduleAddr ModuleInstance) ModuleInstance

func (ModuleCallInstance) ModuleInstance 

func (c ModuleCallInstance) ModuleInstance(caller ModuleInstance) ModuleInstance

ModuleInstance returns the address of the module instance that corresponds to the receiving call instance when resolved in the given calling module. In other words, it returns the child module instance that the receving call instance creates.

func (ModuleCallInstance) Output 

func (c ModuleCallInstance) Output(name string) ModuleCallInstanceOutput

Output returns the absolute address of an output of the receiver identified by its name.

func (ModuleCallInstance) String 

func (c ModuleCallInstance) String() string

func (ModuleCallInstance) UniqueKey added in v1.1.0 

func (c ModuleCallInstance) UniqueKey() UniqueKey

type ModuleCallInstanceOutput added in v1.1.0 

type ModuleCallInstanceOutput struct {
	Call ModuleCallInstance
	Name string
	// contains filtered or unexported fields
}

ModuleCallInstanceOutput is the address of a particular named output produced by an instance of a module call.

func (ModuleCallInstanceOutput) AbsOutputValue added in v1.1.0 

func (co ModuleCallInstanceOutput) AbsOutputValue(caller ModuleInstance) AbsOutputValue

AbsOutputValue returns the absolute output value address that corresponds to the receving module call output address, once resolved in the given calling module.

func (ModuleCallInstanceOutput) ModuleCallOutput added in v1.1.0 

func (co ModuleCallInstanceOutput) ModuleCallOutput() ModuleCallOutput

ModuleCallOutput returns the referenceable ModuleCallOutput for this particular instance.

func (ModuleCallInstanceOutput) String added in v1.1.0 

func (co ModuleCallInstanceOutput) String() string

func (ModuleCallInstanceOutput) UniqueKey added in v1.1.0 

func (co ModuleCallInstanceOutput) UniqueKey() UniqueKey

type ModuleCallOutput 

type ModuleCallOutput struct {
	Call ModuleCall
	Name string
	// contains filtered or unexported fields
}

ModuleCallOutput is the address of a named output and its associated ModuleCall, which may expand into multiple module instances

func (ModuleCallOutput) String 

func (m ModuleCallOutput) String() string

func (ModuleCallOutput) UniqueKey added in v1.1.0 

func (m ModuleCallOutput) UniqueKey() UniqueKey

type ModuleInstance 

type ModuleInstance []ModuleInstanceStep

ModuleInstance is an address for a particular module instance within the dynamic module tree. This is an extension of the static traversals represented by type Module that deals with the possibility of a single module call producing multiple instances via the "count" and "for_each" arguments.

Although ModuleInstance is a slice, it should be treated as immutable after creation. 

var RootModuleInstance ModuleInstance

RootModuleInstance is the module instance address representing the root module, which is also the zero value of ModuleInstance.

func ParseModuleInstance 

func ParseModuleInstance(traversal hcl.Traversal) (ModuleInstance, tfdiags.Diagnostics)

func ParseModuleInstanceStr 

func ParseModuleInstanceStr(str string) (ModuleInstance, tfdiags.Diagnostics)

ParseModuleInstanceStr is a helper wrapper around ParseModuleInstance that takes a string and parses it with the HCL native syntax traversal parser before interpreting it.

This should be used only in specialized situations since it will cause the created references to not have any meaningful source location information. If a reference string is coming from a source that should be identified in error messages then the caller should instead parse it directly using a suitable function from the HCL API and pass the traversal itself to ParseModuleInstance.

Error diagnostics are returned if either the parsing fails or the analysis of the traversal fails. There is no way for the caller to distinguish the two kinds of diagnostics programmatically. If error diagnostics are returned then the returned address is invalid.

func (ModuleInstance) AddrType added in v1.1.0 

func (m ModuleInstance) AddrType() TargetableAddrType

func (ModuleInstance) Ancestors 

func (m ModuleInstance) Ancestors() []ModuleInstance

Ancestors returns a slice containing the receiver and all of its ancestor module instances, all the way up to (and including) the root module. The result is ordered by depth, with the root module always first.

Since the result always includes the root module, a caller may choose to ignore it by slicing the result with [1:].

func (ModuleInstance) Call 

func (m ModuleInstance) Call() (ModuleInstance, ModuleCall)

Call returns the module call address that corresponds to the given module instance, along with the address of the module instance that contains it.

There is no call for the root module, so this method will panic if called on the root module address.

A single module call can produce potentially many module instances, so the result discards any instance key that might be present on the last step of the instance. To retain this, use CallInstance instead.

In practice, this just turns the last element of the receiver into a ModuleCall and then returns a slice of the receiever that excludes that last part. This is just a convenience for situations where a call address is required, such as when dealing with *Reference and Referencable values.

func (ModuleInstance) CallInstance 

func (m ModuleInstance) CallInstance() (ModuleInstance, ModuleCallInstance)

CallInstance returns the module call instance address that corresponds to the given module instance, along with the address of the module instance that contains it.

There is no call for the root module, so this method will panic if called on the root module address.

In practice, this just turns the last element of the receiver into a ModuleCallInstance and then returns a slice of the receiever that excludes that last part. This is just a convenience for situations where a call\ address is required, such as when dealing with *Reference and Referencable values.

func (ModuleInstance) Child 

func (m ModuleInstance) Child(name string, key InstanceKey) ModuleInstance

Child returns the address of a child module instance of the receiver, identified by the given name and key.

func (ModuleInstance) ChildCall added in v1.1.0 

func (m ModuleInstance) ChildCall(name string) AbsModuleCall

ChildCall returns the address of a module call within the receiver, identified by the given name.

func (ModuleInstance) Equal 

func (m ModuleInstance) Equal(o ModuleInstance) bool

Equal returns true if the receiver and the given other value contains the exact same parts.

func (ModuleInstance) InputVariable 

func (m ModuleInstance) InputVariable(name string) AbsInputVariableInstance

InputVariable returns the absolute address of the input variable of the given name inside the receiving module instance.

func (ModuleInstance) IsAncestor 

func (m ModuleInstance) IsAncestor(o ModuleInstance) bool

IsAncestor returns true if the receiver is an ancestor of the given other value.

func (ModuleInstance) IsDeclaredByCall added in v1.1.0 

func (m ModuleInstance) IsDeclaredByCall(other AbsModuleCall) bool

IsDeclaredByCall returns true if the receiver is an instance of the given AbsModuleCall.

func (ModuleInstance) IsRoot 

func (m ModuleInstance) IsRoot() bool

IsRoot returns true if the receiver is the address of the root module instance, or false otherwise.

func (ModuleInstance) Less 

func (m ModuleInstance) Less(o ModuleInstance) bool

Less returns true if the receiver should sort before the given other value in a sorted list of addresses.

func (ModuleInstance) LocalValue 

func (m ModuleInstance) LocalValue(name string) AbsLocalValue

LocalValue returns the absolute address of a local value of the given name within the receiving module instance.

func (ModuleInstance) Module 

func (m ModuleInstance) Module() Module

Module returns the address of the module that this instance is an instance of.

func (ModuleInstance) MoveDestination added in v1.1.0 

func (m ModuleInstance) MoveDestination(fromMatch, toMatch *MoveEndpointInModule) (ModuleInstance, bool)

MoveDestination considers a an address representing a module instance in the context of source and destination move endpoints and then, if the module address matches the from endpoint, returns the corresponding new module address that the object should move to.

MoveDestination will return false in its second return value if the receiver doesn't match fromMatch, indicating that the given move statement doesn't apply to this object.

Both of the given endpoints must be from the same move statement and thus must have matching object types. If not, MoveDestination will panic.

func (ModuleInstance) OutputValue 

func (m ModuleInstance) OutputValue(name string) AbsOutputValue

OutputValue returns the absolute address of an output value of the given name within the receiving module instance.

func (ModuleInstance) Parent 

func (m ModuleInstance) Parent() ModuleInstance

Parent returns the address of the parent module instance of the receiver, or the receiver itself if there is no parent (if it's the root module address).

func (ModuleInstance) ProviderConfigAliased 

func (m ModuleInstance) ProviderConfigAliased(provider Provider, alias string) AbsProviderConfig

ProviderConfigAliased returns the address of an aliased provider config of the given type and alias inside the recieving module instance.

func (ModuleInstance) ProviderConfigDefault 

func (m ModuleInstance) ProviderConfigDefault(provider Provider) AbsProviderConfig

ProviderConfigDefault returns the address of the default provider config of the given type inside the recieving module instance.

func (ModuleInstance) Resource 

func (m ModuleInstance) Resource(mode ResourceMode, typeName string, name string) AbsResource

Resource returns the address of a particular resource within the receiver.

func (ModuleInstance) ResourceInstance 

func (m ModuleInstance) ResourceInstance(mode ResourceMode, typeName string, name string, key InstanceKey) AbsResourceInstance

ResourceInstance returns the address of a particular resource instance within the receiver.

func (ModuleInstance) String 

func (m ModuleInstance) String() string

String returns a string representation of the receiver, in the format used within e.g. user-provided resource addresses.

The address of the root module has the empty string as its representation.

func (ModuleInstance) TargetContains 

func (m ModuleInstance) TargetContains(other Targetable) bool

TargetContains implements Targetable by returning true if the given other address either matches the receiver, is a sub-module-instance of the receiver, or is a targetable absolute address within a module that is contained within the reciever.

func (ModuleInstance) UniqueKey added in v1.1.0 

func (m ModuleInstance) UniqueKey() UniqueKey

type ModuleInstanceStep 

type ModuleInstanceStep struct {
	Name        string
	InstanceKey InstanceKey
}

ModuleInstanceStep is a single traversal step through the dynamic module tree. It is used only as part of ModuleInstance.

func (ModuleInstanceStep) String 

func (s ModuleInstanceStep) String() string

type ModulePackage added in v1.1.0 

type ModulePackage string

A ModulePackage represents a physical location where Terraform can retrieve a module package, which is an archive, repository, or other similar container which delivers the source code for one or more Terraform modules.

A ModulePackage is a string in go-getter's address syntax. By convention, we use ModulePackage-typed values only for the result of successfully running the go-getter "detectors", which produces an address string which includes an explicit installation method prefix along with an address string in the format expected by that installation method.

Note that although the "detector" phase of go-getter does do some simple normalization in certain cases, it isn't generally possible to compare two ModulePackage values to decide if they refer to the same package. Two equal ModulePackage values represent the same package, but there might be other non-equal ModulePackage values that also refer to that package, and there is no reliable way to determine that.

Don't convert a user-provided string directly to ModulePackage. Instead, use ParseModuleSource with a remote module address and then access the ModulePackage value from the result, making sure to also handle the selected subdirectory if any. You should convert directly to ModulePackage only for a string that is hard-coded into the program (e.g. in a unit test) where you've ensured that it's already in the expected syntax.

func (ModulePackage) String added in v1.1.0 

func (p ModulePackage) String() string

type ModuleRegistryPackage added in v1.1.0 

type ModuleRegistryPackage struct {
	Host         svchost.Hostname
	Namespace    string
	Name         string
	TargetSystem string
}

A ModuleRegistryPackage is an extra indirection over a ModulePackage where we use a module registry to translate a more symbolic address (and associated version constraint given out of band) into a physical source location.

ModuleRegistryPackage is distinct from ModulePackage because they have disjoint use-cases: registry package addresses are only used to query a registry in order to find a real module package address. These being distinct is intended to help future maintainers more easily follow the series of steps in the module installer, with the help of the type checker.

func (ModuleRegistryPackage) ForDisplay added in v1.1.0 

func (s ModuleRegistryPackage) ForDisplay() string

func (ModuleRegistryPackage) ForRegistryProtocol added in v1.1.0 

func (s ModuleRegistryPackage) ForRegistryProtocol() string

ForRegistryProtocol returns a string representation of just the namespace, name, and target system portions of the address, always omitting the registry hostname and the subdirectory portion, if any.

This is primarily intended for generating addresses to send to the registry in question via the registry protocol, since the protocol skips sending the registry its own hostname as part of identifiers.

func (ModuleRegistryPackage) String added in v1.1.0 

func (s ModuleRegistryPackage) String() string

type ModuleSource added in v1.1.0 

type ModuleSource interface {
	// String returns a full representation of the address, including any
	// additional components that are typically implied by omission in
	// user-written addresses.
	//
	// We typically use this longer representation in error message, in case
	// the inclusion of normally-omitted components is helpful in debugging
	// unexpected behavior.
	String() string

	// ForDisplay is similar to String but instead returns a representation of
	// the idiomatic way to write the address in configuration, omitting
	// components that are commonly just implied in addresses written by
	// users.
	//
	// We typically use this shorter representation in informational messages,
	// such as the note that we're about to start downloading a package.
	ForDisplay() string
	// contains filtered or unexported methods
}

ModuleSource is the general type for all three of the possible module source address types. The concrete implementations of this are ModuleSourceLocal, ModuleSourceRegistry, and ModuleSourceRemote.

func ParseModuleSource added in v1.1.0 

func ParseModuleSource(raw string) (ModuleSource, error)

ParseModuleSource parses a module source address as given in the "source" argument inside a "module" block in the configuration.

For historical reasons this syntax is a bit overloaded, supporting three different address types:

  • Local paths starting with either ./ or ../, which are special because Terraform considers them to belong to the same "package" as the caller.
  • Module registry addresses, given as either NAMESPACE/NAME/SYSTEM or HOST/NAMESPACE/NAME/SYSTEM, in which case the remote registry serves as an indirection over the third address type that follows.
  • Various URL-like and other heuristically-recognized strings which we currently delegate to the external library go-getter.

There is some ambiguity between the module registry addresses and go-getter's very liberal heuristics and so this particular function will typically treat an invalid registry address as some other sort of remote source address rather than returning an error. If you know that you're expecting a registry address in particular, use ParseModuleSourceRegistry instead, which can therefore expose more detailed error messages about registry address parsing in particular.

func ParseModuleSourceRegistry added in v1.2.0 

func ParseModuleSourceRegistry(raw string) (ModuleSource, error)

ParseModuleSourceRegistry is a variant of ParseModuleSource which only accepts module registry addresses, and will reject any other address type.

Use this instead of ParseModuleSource if you know from some other surrounding context that an address is intended to be a registry address rather than some other address type, which will then allow for better error reporting due to the additional information about user intent.

type ModuleSourceLocal added in v1.1.0 

type ModuleSourceLocal string

ModuleSourceLocal is a ModuleSource representing a local path reference from the caller's directory to the callee's directory within the same module package.

A "module package" here means a set of modules distributed together in the same archive, repository, or similar. That's a significant distinction because we always download and cache entire module packages at once, and then create relative references within the same directory in order to ensure all modules in the package are looking at a consistent filesystem layout. We also assume that modules within a package are maintained together, which means that cross-cutting maintenence across all of them would be possible.

The actual value of a ModuleSourceLocal is a normalized relative path using forward slashes, even on operating systems that have other conventions, because we're representing traversal within the logical filesystem represented by the containing package, not actually within the physical filesystem we unpacked the package into. We should typically not construct ModuleSourceLocal values directly, except in tests where we can ensure the value meets our assumptions. Use ParseModuleSource instead if the input string is not hard-coded in the program.

func (ModuleSourceLocal) ForDisplay added in v1.1.0 

func (s ModuleSourceLocal) ForDisplay() string

func (ModuleSourceLocal) String added in v1.1.0 

func (s ModuleSourceLocal) String() string

type ModuleSourceRegistry added in v1.1.0 

type ModuleSourceRegistry struct {
	// PackageAddr is the registry package that the target module belongs to.
	// The module installer must translate this into a ModuleSourceRemote
	// using the registry API and then take that underlying address's
	// PackageAddr in order to find the actual package location.
	PackageAddr ModuleRegistryPackage

	// If Subdir is non-empty then it represents a sub-directory within the
	// remote package that the registry address eventually resolves to.
	// This will ultimately become the suffix of the Subdir of the
	// ModuleSourceRemote that the registry address translates to.
	//
	// Subdir uses a normalized forward-slash-based path syntax within the
	// virtual filesystem represented by the final package. It will never
	// include `../` or `./` sequences.
	Subdir string
}

ModuleSourceRegistry is a ModuleSource representing a module listed in a Terraform module registry.

A registry source isn't a direct source location but rather an indirection over a ModuleSourceRemote. The job of a registry is to translate the combination of a ModuleSourceRegistry and a module version number into a concrete ModuleSourceRemote that Terraform will then download and install.

func (ModuleSourceRegistry) ForDisplay added in v1.1.0 

func (s ModuleSourceRegistry) ForDisplay() string

func (ModuleSourceRegistry) String added in v1.1.0 

func (s ModuleSourceRegistry) String() string

type ModuleSourceRemote added in v1.1.0 

type ModuleSourceRemote struct {
	// PackageAddr is the address of the remote package that the requested
	// module belongs to.
	PackageAddr ModulePackage

	// If Subdir is non-empty then it represents a sub-directory within the
	// remote package which will serve as the entry-point for the package.
	//
	// Subdir uses a normalized forward-slash-based path syntax within the
	// virtual filesystem represented by the final package. It will never
	// include `../` or `./` sequences.
	Subdir string
}

ModuleSourceRemote is a ModuleSource representing a remote location from which we can retrieve a module package.

A ModuleSourceRemote can optionally include a "subdirectory" path, which means that it's selecting a sub-directory of the given package to use as the entry point into the package.

func (ModuleSourceRemote) ForDisplay added in v1.1.0 

func (s ModuleSourceRemote) ForDisplay() string

func (ModuleSourceRemote) FromRegistry added in v1.1.0 

func (s ModuleSourceRemote) FromRegistry(given ModuleSourceRegistry) ModuleSourceRemote

FromRegistry can be called on a remote source address that was returned from a module registry, passing in the original registry source address that the registry was asked about, in order to get the effective final remote source address.

Specifically, this method handles the situations where one or both of the two addresses contain subdirectory paths, combining both when necessary in order to ensure that both the registry's given path and the user's given path are both respected.

This will return nonsense if given a registry address other than the one that generated the reciever via a registry lookup.

func (ModuleSourceRemote) String added in v1.1.0 

func (s ModuleSourceRemote) String() string

type MoveEndpoint added in v1.1.0 

type MoveEndpoint struct {
	// SourceRange is the location of the physical endpoint address
	// in configuration, if this MoveEndpoint was decoded from a
	// configuration expresson.
	SourceRange tfdiags.SourceRange
	// contains filtered or unexported fields
}

MoveEndpoint is to AbsMoveable and ConfigMoveable what Target is to Targetable: a wrapping struct that captures the result of decoding an HCL traversal representing a relative path from the current module to a moveable object.

Its name reflects that its primary purpose is for the "from" and "to" addresses in a "moved" statement in the configuration, but it's also valid to use MoveEndpoint for other similar mechanisms that give Terraform hints about historical configuration changes that might prompt creating a different plan than Terraform would by default.

To obtain a full address from a MoveEndpoint you must use either the package function UnifyMoveEndpoints (to get an AbsMoveable) or the method ConfigMoveable (to get a ConfigMoveable).

func ParseMoveEndpoint added in v1.1.0 

func ParseMoveEndpoint(traversal hcl.Traversal) (*MoveEndpoint, tfdiags.Diagnostics)

ParseMoveEndpoint attempts to interpret the given traversal as a "move endpoint" address, which is a relative path from the module containing the traversal to a movable object in either the same module or in some child module.

This deals only with the syntactic element of a move endpoint expression in configuration. Before the result will be useful you'll need to combine it with the address of the module where it was declared in order to get an absolute address relative to the root module.

func (*MoveEndpoint) ConfigMoveable added in v1.1.0 

func (e *MoveEndpoint) ConfigMoveable(baseModule Module) ConfigMoveable

ConfigMovable transforms the reciever into a ConfigMovable by resolving it relative to the given base module, which should be the module where the MoveEndpoint expression was found.

The result is useful for finding the target object in the configuration, but it's not sufficient for fully interpreting a move statement because it lacks the specific module and resource instance keys.

func (*MoveEndpoint) Equal added in v1.1.0 

func (e *MoveEndpoint) Equal(other *MoveEndpoint) bool

func (*MoveEndpoint) MightUnifyWith added in v1.1.0 

func (e *MoveEndpoint) MightUnifyWith(other *MoveEndpoint) bool

MightUnifyWith returns true if it is possible that a later call to UnifyMoveEndpoints might succeed if given the reciever and the other given endpoint.

This is intended for early static validation of obviously-wrong situations, although there are still various semantic errors that this cannot catch.

func (*MoveEndpoint) ObjectKind added in v1.1.0 

func (e *MoveEndpoint) ObjectKind() MoveEndpointKind

func (*MoveEndpoint) String added in v1.1.0 

func (e *MoveEndpoint) String() string

type MoveEndpointInModule added in v1.1.0 

type MoveEndpointInModule struct {
	// SourceRange is the location of the physical endpoint address
	// in configuration, if this MoveEndpoint was decoded from a
	// configuration expresson.
	SourceRange tfdiags.SourceRange
	// contains filtered or unexported fields
}

MoveEndpointInModule annotates a MoveEndpoint with the address of the module where it was declared, which is the form we use for resolving whether move statements chain from or are nested within other move statements.

func ImpliedMoveStatementEndpoint added in v1.1.0 

func ImpliedMoveStatementEndpoint(addr AbsResourceInstance, rng tfdiags.SourceRange) *MoveEndpointInModule

ImpliedMoveStatementEndpoint is a special constructor for MoveEndpointInModule which is suitable only for constructing "implied" move statements, which means that we inferred the statement automatically rather than building it from an explicit block in the configuration.

Implied move endpoints, just as for the statements they are embedded in, have somewhat-related-but-imprecise source ranges, typically referring to some general configuration construct that implied the statement, because by definition there is no explicit move endpoint expression in this case.

func UnifyMoveEndpoints added in v1.1.0 

func UnifyMoveEndpoints(moduleAddr Module, relFrom, relTo *MoveEndpoint) (modFrom, modTo *MoveEndpointInModule)

UnifyMoveEndpoints takes a pair of MoveEndpoint objects representing the "from" and "to" addresses in a moved block, and returns a pair of MoveEndpointInModule addresses guaranteed to be of the same dynamic type that represent what the two MoveEndpoint addresses refer to.

moduleAddr must be the address of the module where the move was declared.

This function deals both with the conversion from relative to absolute addresses and with resolving the ambiguity between no-key instance addresses and whole-object addresses, returning the least specific address type possible.

Not all combinations of addresses are unifyable: the two addresses must either both include resources or both just be modules. If the two given addresses are incompatible then UnifyMoveEndpoints returns (nil, nil), in which case the caller should typically report an error to the user stating the unification constraints.

func (*MoveEndpointInModule) CanChainFrom added in v1.1.0 

func (e *MoveEndpointInModule) CanChainFrom(other *MoveEndpointInModule) bool

CanChainFrom returns true if the reciever describes an address that could potentially select an object that the other given address could select.

In other words, this decides whether the move chaining rule applies, if the reciever is the "to" from one statement and the other given address is the "from" of another statement.

func (*MoveEndpointInModule) Equal added in v1.1.0 

func (e *MoveEndpointInModule) Equal(other *MoveEndpointInModule) bool

Equal returns true if the reciever represents the same matching pattern as the other given endpoint, ignoring the source location information.

This is not an optimized function and is here primarily to help with writing concise assertions in test code.

func (*MoveEndpointInModule) InModuleInstance added in v1.1.0 

func (e *MoveEndpointInModule) InModuleInstance(modInst ModuleInstance) AbsMoveable

InModuleInstance returns an AbsMoveable address which concatenates the given module instance address with the receiver's relative object selection to produce one example of an instance that might be affected by this move statement.

The result is meaningful only if the given module instance is an instance of the same module returned by the method Module. InModuleInstance doesn't fully verify that (aside from some cheap/easy checks), but it will produce meaningless garbage if not.

func (*MoveEndpointInModule) IsModuleReIndex added in v1.1.3 

func (from *MoveEndpointInModule) IsModuleReIndex(to *MoveEndpointInModule) bool

IsModuleReIndex takes the From and To endpoints from a single move statement, and returns true if the only changes are to module indexes, and all non-absolute paths remain the same.

func (*MoveEndpointInModule) Module added in v1.1.0 

func (e *MoveEndpointInModule) Module() Module

Module returns the address of the module where the receiving address was declared.

func (*MoveEndpointInModule) ModuleCallTraversals added in v1.1.0 

func (e *MoveEndpointInModule) ModuleCallTraversals() (Module, []ModuleCall)

ModuleCallTraversals returns both the address of the module where the receiver was declared and any other module calls it traverses through while selecting a particular object to move.

This is a rather special-purpose function here mainly to support our validation rule that a module can only traverse down into child modules that belong to the same module package.

func (*MoveEndpointInModule) NestedWithin added in v1.1.0 

func (e *MoveEndpointInModule) NestedWithin(other *MoveEndpointInModule) bool

NestedWithin returns true if the receiver describes an address that is contained within one of the objects that the given other address could select.

func (*MoveEndpointInModule) ObjectKind added in v1.1.0 

func (e *MoveEndpointInModule) ObjectKind() MoveEndpointKind

func (*MoveEndpointInModule) SelectsModule added in v1.1.0 

func (e *MoveEndpointInModule) SelectsModule(addr ModuleInstance) bool

SelectsModule returns true if the reciever directly selects either the given module or a resource nested directly inside that module.

This is a good function to use to decide which modules in a state to consider when processing a particular move statement. For a module move the given module itself is what will move, while a resource move indicates that we should search each of the resources in the given module to see if they match.

func (*MoveEndpointInModule) SelectsResource added in v1.1.0 

func (e *MoveEndpointInModule) SelectsResource(addr AbsResource) bool

SelectsResource returns true if the receiver directly selects either the given resource or one of its instances.

func (*MoveEndpointInModule) String added in v1.1.0 

func (e *MoveEndpointInModule) String() string

String produces a string representation of the object matching pattern represented by the reciever.

Since there is no direct syntax for representing such an object matching pattern, this function uses a splat-operator-like representation to stand in for the wildcard instance keys.

type MoveEndpointKind added in v1.1.0 

type MoveEndpointKind rune

MoveEndpointKind represents the different kinds of object that a movable address can refer to. 

const (
	// MoveEndpointModule indicates that a move endpoint either refers to
	// an individual module instance or to all instances of a particular
	// module call.
	MoveEndpointModule MoveEndpointKind = 'M'

	// MoveEndpointResource indicates that a move endpoint either refers to
	// an individual resource instance or to all instances of a particular
	// resource.
	MoveEndpointResource MoveEndpointKind = 'R'
)

func (MoveEndpointKind) String added in v1.1.0 

func (i MoveEndpointKind) String() string

type OutputValue 

type OutputValue struct {
	Name string
}

OutputValue is the address of an output value, in the context of the module that is defining it.

This is related to but separate from ModuleCallOutput, which represents a module output from the perspective of its parent module. Since output values cannot be represented from the module where they are defined, OutputValue is not Referenceable, while ModuleCallOutput is.

func (OutputValue) Absolute 

func (v OutputValue) Absolute(m ModuleInstance) AbsOutputValue

Absolute converts the receiver into an absolute address within the given module instance.

func (OutputValue) String 

func (v OutputValue) String() string

type PathAttr 

type PathAttr struct {
	Name string
	// contains filtered or unexported fields
}

PathAttr is the address of an attribute of the "path" object in the interpolation scope, like "path.module".

func (PathAttr) String 

func (pa PathAttr) String() string

func (PathAttr) UniqueKey added in v1.1.0 

func (pa PathAttr) UniqueKey() UniqueKey

type Provider 

type Provider struct {
	Type      string
	Namespace string
	Hostname  svchost.Hostname
}

Provider encapsulates a single provider type. In the future this will be extended to include additional fields including Namespace and SourceHost

func ImpliedProviderForUnqualifiedType 

func ImpliedProviderForUnqualifiedType(typeName string) Provider

ImpliedProviderForUnqualifiedType represents the rules for inferring what provider FQN a user intended when only a naked type name is available.

For all except the type name "terraform" this returns a so-called "default" provider, which is under the registry.terraform.io/hashicorp/ namespace.

As a special case, the string "terraform" maps to "terraform.io/builtin/terraform" because that is the more likely user intent than the now-unmaintained "registry.terraform.io/hashicorp/terraform" which remains only for compatibility with older Terraform versions.

func MustParseProviderSourceString 

func MustParseProviderSourceString(str string) Provider

MustParseProviderSourceString is a wrapper around ParseProviderSourceString that panics if it returns an error.

func NewBuiltInProvider 

func NewBuiltInProvider(name string) Provider

NewBuiltInProvider returns the address of a "built-in" provider. See the docs for Provider.IsBuiltIn for more information.

func NewDefaultProvider 

func NewDefaultProvider(name string) Provider

NewDefaultProvider returns the default address of a HashiCorp-maintained, Registry-hosted provider.

func NewLegacyProvider 

func NewLegacyProvider(name string) Provider

NewLegacyProvider returns a mock address for a provider. This will be removed when ProviderType is fully integrated.

func NewProvider 

func NewProvider(hostname svchost.Hostname, namespace, typeName string) Provider

NewProvider constructs a provider address from its parts, and normalizes the namespace and type parts to lowercase using unicode case folding rules so that resulting addrs.Provider values can be compared using standard Go equality rules (==).

The hostname is given as a svchost.Hostname, which is required by the contract of that type to have already been normalized for equality testing.

This function will panic if the given namespace or type name are not valid. When accepting namespace or type values from outside the program, use ParseProviderPart first to check that the given value is valid.

func ParseProviderSourceString 

func ParseProviderSourceString(str string) (Provider, tfdiags.Diagnostics)

ParseProviderSourceString parses the source attribute and returns a provider. This is intended primarily to parse the FQN-like strings returned by terraform-config-inspect.

The following are valid source string formats: 

name
namespace/name
hostname/namespace/name

func (Provider) Equals 

func (pt Provider) Equals(other Provider) bool

Equals returns true if the receiver and other provider have the same attributes.

func (Provider) ForDisplay 

func (pt Provider) ForDisplay() string

ForDisplay returns a user-friendly FQN string, simplified for readability. If the provider is using the default hostname, the hostname is omitted.

func (Provider) IsBuiltIn 

func (pt Provider) IsBuiltIn() bool

IsBuiltIn returns true if the receiver is the address of a "built-in" provider. That is, a provider under terraform.io/builtin/ which is included as part of the Terraform binary itself rather than one to be installed from elsewhere.

These are ignored by the provider installer because they are assumed to already be available without any further installation.

func (Provider) IsDefault 

func (pt Provider) IsDefault() bool

IsDefault returns true if the provider is a default hashicorp provider

func (Provider) IsLegacy 

func (pt Provider) IsLegacy() bool

IsLegacy returns true if the provider is a legacy-style provider

func (Provider) IsZero 

func (pt Provider) IsZero() bool

IsZero returns true if the receiver is the zero value of addrs.Provider.

The zero value is not a valid addrs.Provider and calling other methods on such a value is likely to either panic or otherwise misbehave.

func (Provider) LegacyString 

func (pt Provider) LegacyString() string

LegacyString returns the provider type, which is frequently used interchangeably with provider name. This function can and should be removed when provider type is fully integrated. As a safeguard for future refactoring, this function panics if the Provider is not a legacy provider.

func (Provider) LessThan 

func (pt Provider) LessThan(other Provider) bool

LessThan returns true if the receiver should sort before the other given address in an ordered list of provider addresses.

This ordering is an arbitrary one just to allow deterministic results from functions that would otherwise have no natural ordering. It's subject to change in future.

func (Provider) String 

func (pt Provider) String() string

String returns an FQN string, indended for use in machine-readable output.

type ProviderConfig 

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

ProviderConfig is an interface type whose dynamic type can be either LocalProviderConfig or AbsProviderConfig, in order to represent situations where a value might either be module-local or absolute but the decision cannot be made until runtime.

Where possible, use either LocalProviderConfig or AbsProviderConfig directly instead, to make intent more clear. ProviderConfig can be used only in situations where the recipient of the value has some out-of-band way to determine a "current module" to use if the value turns out to be a LocalProviderConfig.

Recipients of non-nil ProviderConfig values that actually need AbsProviderConfig values should call ResolveAbsProviderAddr on the *configs.Config value representing the root module configuration, which handles the translation from local to fully-qualified using mapping tables defined in the configuration.

Recipients of a ProviderConfig value can assume it can contain only a LocalProviderConfig value, an AbsProviderConfigValue, or nil to represent the absense of a provider config in situations where that is meaningful.

type Reference 

type Reference struct {
	Subject     Referenceable
	SourceRange tfdiags.SourceRange
	Remaining   hcl.Traversal
}

Reference describes a reference to an address with source location information.

func ParseRef 

func ParseRef(traversal hcl.Traversal) (*Reference, tfdiags.Diagnostics)

ParseRef attempts to extract a referencable address from the prefix of the given traversal, which must be an absolute traversal or this function will panic.

If no error diagnostics are returned, the returned reference includes the address that was extracted, the source range it was extracted from, and any remaining relative traversal that was not consumed as part of the reference.

If error diagnostics are returned then the Reference value is invalid and must not be used.

func ParseRefStr 

func ParseRefStr(str string) (*Reference, tfdiags.Diagnostics)

ParseRefStr is a helper wrapper around ParseRef that takes a string and parses it with the HCL native syntax traversal parser before interpreting it.

This should be used only in specialized situations since it will cause the created references to not have any meaningful source location information. If a reference string is coming from a source that should be identified in error messages then the caller should instead parse it directly using a suitable function from the HCL API and pass the traversal itself to ParseRef.

Error diagnostics are returned if either the parsing fails or the analysis of the traversal fails. There is no way for the caller to distinguish the two kinds of diagnostics programmatically. If error diagnostics are returned the returned reference may be nil or incomplete.

func (*Reference) DisplayString added in v1.2.0 

func (r *Reference) DisplayString() string

DisplayString returns a string that approximates the subject and remaining traversal of the reciever in a way that resembles the Terraform language syntax that could've produced it.

It's not guaranteed to actually be a valid Terraform language expression, since the intended use here is primarily for UI messages such as diagnostics.

type Referenceable 

type Referenceable interface {

	// All Referenceable address types must have unique keys.
	UniqueKeyer

	// String produces a string representation of the address that could be
	// parsed as a HCL traversal and passed to ParseRef to produce an identical
	// result.
	String() string
	// contains filtered or unexported methods
}

Referenceable is an interface implemented by all address types that can appear as references in configuration language expressions.

type Resource 

type Resource struct {
	Mode ResourceMode
	Type string
	Name string
	// contains filtered or unexported fields
}

Resource is an address for a resource block within configuration, which contains potentially-multiple resource instances if that configuration block uses "count" or "for_each".

func (Resource) Absolute 

func (r Resource) Absolute(module ModuleInstance) AbsResource

Absolute returns an AbsResource from the receiver and the given module instance address.

func (Resource) Equal 

func (r Resource) Equal(o Resource) bool

func (Resource) ImpliedProvider 

func (r Resource) ImpliedProvider() string

ImpliedProvider returns the implied provider type name, for e.g. the "aws" in "aws_instance"

func (Resource) InModule 

func (r Resource) InModule(module Module) ConfigResource

InModule returns a ConfigResource from the receiver and the given module address.

func (Resource) Instance 

func (r Resource) Instance(key InstanceKey) ResourceInstance

Instance produces the address for a specific instance of the receiver that is idenfied by the given key.

func (Resource) Phase 

func (r Resource) Phase(rpt ResourceInstancePhaseType) ResourcePhase

Phase returns a special "phase address" for the receving instance. See the documentation of ResourceInstancePhase for the limited situations where this is intended to be used.

func (Resource) String 

func (r Resource) String() string

func (Resource) UniqueKey added in v1.1.0 

func (r Resource) UniqueKey() UniqueKey

type ResourceInstance 

type ResourceInstance struct {
	Resource Resource
	Key      InstanceKey
	// contains filtered or unexported fields
}

ResourceInstance is an address for a specific instance of a resource. When a resource is defined in configuration with "count" or "for_each" it produces zero or more instances, which can be addressed using this type.

func (ResourceInstance) Absolute 

func (r ResourceInstance) Absolute(module ModuleInstance) AbsResourceInstance

Absolute returns an AbsResourceInstance from the receiver and the given module instance address.

func (ResourceInstance) ContainingResource 

func (r ResourceInstance) ContainingResource() Resource

func (ResourceInstance) Equal 

func (r ResourceInstance) Equal(o ResourceInstance) bool

func (ResourceInstance) Phase 

func (r ResourceInstance) Phase(rpt ResourceInstancePhaseType) ResourceInstancePhase

Phase returns a special "phase address" for the receving instance. See the documentation of ResourceInstancePhase for the limited situations where this is intended to be used.

func (ResourceInstance) String 

func (r ResourceInstance) String() string

func (ResourceInstance) UniqueKey added in v1.1.0 

func (r ResourceInstance) UniqueKey() UniqueKey

type ResourceInstancePhase 

type ResourceInstancePhase struct {
	ResourceInstance ResourceInstance
	Phase            ResourceInstancePhaseType
	// contains filtered or unexported fields
}

ResourceInstancePhase is a special kind of reference used only internally during graph building to represent resource instances that are in a non-primary state.

Graph nodes can declare themselves referenceable via an instance phase or can declare that they reference an instance phase in order to accomodate secondary graph nodes dealing with, for example, destroy actions.

This special reference type cannot be accessed directly by end-users, and should never be shown in the UI.

func (ResourceInstancePhase) ContainingResource 

func (rp ResourceInstancePhase) ContainingResource() ResourcePhase

ContainingResource returns an address for the same phase of the resource that this instance belongs to.

func (ResourceInstancePhase) String 

func (rp ResourceInstancePhase) String() string

func (ResourceInstancePhase) UniqueKey added in v1.1.0 

func (rp ResourceInstancePhase) UniqueKey() UniqueKey

type ResourceInstancePhaseType 

type ResourceInstancePhaseType string

ResourceInstancePhaseType is an enumeration used with ResourceInstancePhase. 

const (
	// ResourceInstancePhaseDestroy represents the "destroy" phase of a
	// resource instance.
	ResourceInstancePhaseDestroy ResourceInstancePhaseType = "destroy"

	// ResourceInstancePhaseDestroyCBD is similar to ResourceInstancePhaseDestroy
	// but is used for resources that have "create_before_destroy" set, thus
	// requiring a different dependency ordering.
	ResourceInstancePhaseDestroyCBD ResourceInstancePhaseType = "destroy-cbd"
)

func (ResourceInstancePhaseType) String 

func (rpt ResourceInstancePhaseType) String() string

type ResourceMode 

type ResourceMode rune

ResourceMode defines which lifecycle applies to a given resource. Each resource lifecycle has a slightly different address format. 

const (
	// InvalidResourceMode is the zero value of ResourceMode and is not
	// a valid resource mode.
	InvalidResourceMode ResourceMode = 0

	// ManagedResourceMode indicates a managed resource, as defined by
	// "resource" blocks in configuration.
	ManagedResourceMode ResourceMode = 'M'

	// DataResourceMode indicates a data resource, as defined by
	// "data" blocks in configuration.
	DataResourceMode ResourceMode = 'D'
)

func (ResourceMode) String 

func (i ResourceMode) String() string

type ResourcePhase 

type ResourcePhase struct {
	Resource Resource
	Phase    ResourceInstancePhaseType
	// contains filtered or unexported fields
}

ResourcePhase is a special kind of reference used only internally during graph building to represent resources that are in a non-primary state.

Graph nodes can declare themselves referenceable via a resource phase or can declare that they reference a resource phase in order to accomodate secondary graph nodes dealing with, for example, destroy actions.

Since resources (as opposed to instances) aren't actually phased, this address type is used only as an approximation during initial construction of the resource-oriented plan graph, under the assumption that resource instances with ResourceInstancePhase addresses will be created in dynamic subgraphs during the graph walk.

This special reference type cannot be accessed directly by end-users, and should never be shown in the UI.

func (ResourcePhase) String 

func (rp ResourcePhase) String() string

func (ResourcePhase) UniqueKey added in v1.1.0 

func (rp ResourcePhase) UniqueKey() UniqueKey

type Set added in v1.1.0 

type Set map[UniqueKey]UniqueKeyer

Set represents a set of addresses of types that implement UniqueKeyer.

func (Set) Add added in v1.1.0 

func (s Set) Add(addr UniqueKeyer)

func (Set) Has added in v1.1.0 

func (s Set) Has(addr UniqueKeyer) bool

func (Set) Intersection added in v1.1.0 

func (s Set) Intersection(other Set) Set

func (Set) Remove added in v1.1.0 

func (s Set) Remove(addr UniqueKeyer)

func (Set) Union added in v1.1.0 

func (s Set) Union(other Set) Set

type StringKey 

type StringKey string

StringKey is the InstanceKey representation representing string indices, as used when the "for_each" argument is specified with a map or object type.

func (StringKey) String 

func (k StringKey) String() string

func (StringKey) Value 

func (k StringKey) Value() cty.Value

type Target 

type Target struct {
	Subject     Targetable
	SourceRange tfdiags.SourceRange
}

Target describes a targeted address with source location information.

func ParseTarget 

func ParseTarget(traversal hcl.Traversal) (*Target, tfdiags.Diagnostics)

ParseTarget attempts to interpret the given traversal as a targetable address. The given traversal must be absolute, or this function will panic.

If no error diagnostics are returned, the returned target includes the address that was extracted and the source range it was extracted from.

If error diagnostics are returned then the Target value is invalid and must not be used.

func ParseTargetStr 

func ParseTargetStr(str string) (*Target, tfdiags.Diagnostics)

ParseTargetStr is a helper wrapper around ParseTarget that takes a string and parses it with the HCL native syntax traversal parser before interpreting it.

This should be used only in specialized situations since it will cause the created references to not have any meaningful source location information. If a target string is coming from a source that should be identified in error messages then the caller should instead parse it directly using a suitable function from the HCL API and pass the traversal itself to ParseTarget.

Error diagnostics are returned if either the parsing fails or the analysis of the traversal fails. There is no way for the caller to distinguish the two kinds of diagnostics programmatically. If error diagnostics are returned the returned target may be nil or incomplete.

func (*Target) ModuleAddr added in v1.1.0 

func (t *Target) ModuleAddr() ModuleInstance

ModuleAddr returns the module address portion of the subject of the recieving target.

Regardless of specific address type, all targets always include a module address. They might also include something in that module, which this method always discards if so.

type Targetable 

type Targetable interface {

	// TargetContains returns true if the receiver is considered to contain
	// the given other address. Containment, for the purpose of targeting,
	// means that if a container address is targeted then all of the
	// addresses within it are also implicitly targeted.
	//
	// A targetable address always contains at least itself.
	TargetContains(other Targetable) bool

	// AddrType returns the address type for comparison with other Targetable
	// addresses.
	AddrType() TargetableAddrType

	// String produces a string representation of the address that could be
	// parsed as a HCL traversal and passed to ParseTarget to produce an
	// identical result.
	String() string
	// contains filtered or unexported methods
}

Targetable is an interface implemented by all address types that can be used as "targets" for selecting sub-graphs of a graph.

type TargetableAddrType added in v1.1.0 

type TargetableAddrType int
const (
	ConfigResourceAddrType TargetableAddrType = iota
	AbsResourceInstanceAddrType
	AbsResourceAddrType
	ModuleAddrType
	ModuleInstanceAddrType
)

type TerraformAttr 

type TerraformAttr struct {
	Name string
	// contains filtered or unexported fields
}

TerraformAttr is the address of an attribute of the "terraform" object in the interpolation scope, like "terraform.workspace".

func (TerraformAttr) String 

func (ta TerraformAttr) String() string

func (TerraformAttr) UniqueKey added in v1.1.0 

func (ta TerraformAttr) UniqueKey() UniqueKey

type UniqueKey added in v1.1.0 

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

UniqueKey is an interface implemented by values that serve as unique map keys for particular addresses.

All implementations of UniqueKey are comparable and can thus be used as map keys. Unique keys generated from different address types are always distinct. All functionally-equivalent keys for the same address type always compare equal, and likewise functionally-different values do not.

type UniqueKeyer added in v1.1.0 

type UniqueKeyer interface {
	UniqueKey() UniqueKey
}

UniqueKeyer is an interface implemented by types that can be represented by a unique key.

Some address types naturally comply with the expectations of a UniqueKey and may thus be their own unique key type. However, address types that are not naturally comparable can implement this interface by returning proxy values.

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.