addrs

package
v0.0.0-...-c924774 Latest Latest
Warning

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

Go to latest
Published: May 29, 2024 License: MPL-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package addrs contains types that represent "addresses", which are references to specific objects within a OpenTofu 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 OpenTofu 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 (
	FunctionNamespaceProvider = "provider"
	FunctionNamespaceCore     = "core"
)
View Source
const BuiltInProviderHost = tfaddr.BuiltInProviderHost

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 = tfaddr.BuiltInProviderNamespace

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 = tfaddr.DefaultModuleRegistryHost

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

View Source
const DefaultProviderRegistryHost = tfaddr.DefaultProviderRegistryHost

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

View Source
const LegacyProviderNamespace = tfaddr.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

Functions

func Equivalent

func Equivalent[T UniqueKeyer](a, b T) bool

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 IsDefaultProvider

func IsDefaultProvider(addr Provider) bool

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.

func ParseProviderSourceString

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

ParseProviderSourceString parses a value of the form expected in the "source" argument of a required_providers entry and returns the corresponding fully-qualified provider address. 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

Types

type AbsCheck

type AbsCheck struct {
	Module ModuleInstance
	Check  Check
}

AbsCheck is an absolute address for a check block under a given module path.

This contains an actual ModuleInstance address (compared to the Module within a ConfigCheck), meaning this uniquely describes a check block within the entire configuration after any "count" or "foreach" meta arguments have been evaluated on the containing module.

func (AbsCheck) CheckRule

func (c AbsCheck) CheckRule(typ CheckRuleType, i int) CheckRule

CheckRule returns an address for a given rule type within the check block.

There will be at most one CheckDataResource rule within a check block (with an index of 0). There will be at least one, but potentially many, CheckAssertion rules within a check block.

func (AbsCheck) CheckableKind

func (c AbsCheck) CheckableKind() CheckableKind

func (AbsCheck) ConfigCheckable

func (c AbsCheck) ConfigCheckable() ConfigCheckable

ConfigCheckable returns the ConfigCheck address for this absolute reference.

func (AbsCheck) String

func (c AbsCheck) String() string

func (AbsCheck) UniqueKey

func (c AbsCheck) UniqueKey() UniqueKey

type AbsInputVariableInstance

type AbsInputVariableInstance struct {
	Module   ModuleInstance
	Variable InputVariable
}

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

func (AbsInputVariableInstance) CheckRule

func (AbsInputVariableInstance) CheckableKind

func (v AbsInputVariableInstance) CheckableKind() CheckableKind

func (AbsInputVariableInstance) ConfigCheckable

func (v AbsInputVariableInstance) ConfigCheckable() ConfigCheckable

func (AbsInputVariableInstance) String

func (v AbsInputVariableInstance) String() string

func (AbsInputVariableInstance) UniqueKey

func (v AbsInputVariableInstance) UniqueKey() UniqueKey

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

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

func (c AbsModuleCall) Equal(other AbsModuleCall) bool

func (AbsModuleCall) Instance

func (c AbsModuleCall) Instance(key InstanceKey) ModuleInstance

func (AbsModuleCall) String

func (c AbsModuleCall) String() string

func (AbsModuleCall) UniqueKey

func (c AbsModuleCall) UniqueKey() UniqueKey

type AbsMoveable

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

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
}

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

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

func ParseAbsOutputValueStr

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

func (AbsOutputValue) CheckRule

func (v AbsOutputValue) CheckRule(t CheckRuleType, i int) CheckRule

func (AbsOutputValue) CheckableKind

func (v AbsOutputValue) CheckableKind() CheckableKind

func (AbsOutputValue) ConfigCheckable

func (v AbsOutputValue) ConfigCheckable() ConfigCheckable

func (AbsOutputValue) ConfigOutputValue

func (v AbsOutputValue) ConfigOutputValue() ConfigOutputValue

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

func (AbsOutputValue) UniqueKey

func (v AbsOutputValue) UniqueKey() UniqueKey

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 configuration address. The following are examples of traversals that can be successfully parsed as absolute provider configuration addresses:

  • provider["registry.opentofu.org/hashicorp/aws"]
  • provider["registry.opentofu.org/hashicorp/aws"].foo
  • module.bar.provider["registry.opentofu.org/hashicorp/aws"]
  • module.bar.module.baz.provider["registry.opentofu.org/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 typically not used prominently 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 in the legacy form used by OpenTofu v0.12 and earlier. 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

We can encounter this kind of address in a historical state snapshot that hasn't yet been upgraded by refreshing or applying a plan with OpenTofu v0.13. Later versions of OpenTofu reject state snapshots using this format, and so users must follow the OpenTofu v0.13 upgrade guide in that case.

We will not use this address form for any new file formats.

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 tofu 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 a format like the following examples:

  • 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

func (r AbsResource) AddrType() TargetableAddrType

func (AbsResource) AffectedAbsResource

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

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

func (AbsResource) Less

func (r AbsResource) Less(o AbsResource) bool

func (AbsResource) MoveDestination

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

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

func (AbsResourceInstance) AffectedAbsResource

func (r AbsResourceInstance) AffectedAbsResource() AbsResource

AffectedAbsResource returns the AbsResource for the instance.

func (AbsResourceInstance) CheckRule

func (r AbsResourceInstance) CheckRule(t CheckRuleType, i int) CheckRule

func (AbsResourceInstance) CheckableKind

func (v AbsResourceInstance) CheckableKind() CheckableKind

func (AbsResourceInstance) ConfigCheckable

func (r AbsResourceInstance) ConfigCheckable() ConfigCheckable

func (AbsResourceInstance) ConfigResource

func (r AbsResourceInstance) ConfigResource() ConfigResource

ConfigResource returns the address of the configuration block that declared this instance.

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 (AbsResourceInstance) Less

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

func (AbsResourceInstance) MoveDestination

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

func (r AbsResourceInstance) UniqueKey() UniqueKey

type Check

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

Check is the address of a check block within a module.

For now, checks do not support meta arguments such as "count" or "for_each" so this address uniquely describes a single check within a module.

func (Check) Absolute

func (c Check) Absolute(modAddr ModuleInstance) AbsCheck

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

func (Check) Equal

func (c Check) Equal(o Check) bool

func (Check) InModule

func (c Check) InModule(modAddr Module) ConfigCheck

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

func (Check) String

func (c Check) String() string

func (Check) UniqueKey

func (c Check) UniqueKey() UniqueKey

type CheckRule

type CheckRule struct {
	Container Checkable
	Type      CheckRuleType
	Index     int
}

CheckRule 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. CheckRule is therefore for internal use only and should not be exposed in durable artifacts such as state snapshots.

func DiagnosticOriginatesFromCheckRule

func DiagnosticOriginatesFromCheckRule(diag tfdiags.Diagnostic) (CheckRule, bool)

DiagnosticOriginatesFromCheckRule checks if the provided diagnostic contains a CheckRule as ExtraInfo and returns that CheckRule and true if it does. This function returns an empty CheckRule and false if the diagnostic does not contain a CheckRule.

func NewCheckRule

func NewCheckRule(container Checkable, typ CheckRuleType, index int) CheckRule

func (CheckRule) String

func (c CheckRule) String() string

func (CheckRule) UniqueKey

func (c CheckRule) UniqueKey() UniqueKey

type CheckRuleDiagnosticExtra

type CheckRuleDiagnosticExtra struct {
	CheckRule CheckRule
	// contains filtered or unexported fields
}

CheckRuleDiagnosticExtra is an object that can be attached to diagnostics that originate from check rules.

It implements the DiagnosticExtraCheckRule interface for retrieving the concrete CheckRule that spawned the diagnostic.

It also implements the tfdiags.DiagnosticExtraDoNotConsolidate interface, to stop diagnostics created by check blocks being consolidated.

It also implements the tfdiags.DiagnosticExtraUnwrapper interface, as nested data blocks will attach this struct but do want to lose any extra info embedded in the original diagnostic.

func (*CheckRuleDiagnosticExtra) DiagnosticOriginatesFromCheckRule

func (c *CheckRuleDiagnosticExtra) DiagnosticOriginatesFromCheckRule() CheckRule

func (*CheckRuleDiagnosticExtra) DoNotConsolidateDiagnostic

func (c *CheckRuleDiagnosticExtra) DoNotConsolidateDiagnostic() bool

func (*CheckRuleDiagnosticExtra) UnwrapDiagnosticExtra

func (c *CheckRuleDiagnosticExtra) UnwrapDiagnosticExtra() interface{}

func (*CheckRuleDiagnosticExtra) WrapDiagnosticExtra

func (c *CheckRuleDiagnosticExtra) WrapDiagnosticExtra(inner interface{})

type CheckRuleType

type CheckRuleType int

CheckRuleType describes a category of check. We use this only to establish uniqueness for Check values, and do not expose this concept of "check types" (which is subject to change in future) in any durable artifacts such as state snapshots.

(See CheckableKind for an enumeration that we _do_ use externally, to describe the type of object being checked rather than the type of the check itself.)

const (
	InvalidCondition      CheckRuleType = 0
	ResourcePrecondition  CheckRuleType = 1
	ResourcePostcondition CheckRuleType = 2
	OutputPrecondition    CheckRuleType = 3
	CheckDataResource     CheckRuleType = 4
	CheckAssertion        CheckRuleType = 5
	InputValidation       CheckRuleType = 6
)

func (CheckRuleType) Description

func (c CheckRuleType) Description() string

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

func (CheckRuleType) String

func (i CheckRuleType) String() string

type Checkable

type Checkable interface {
	UniqueKeyer

	// CheckRule returns the address of an individual check rule of a specified
	// type and index within this checkable container.
	CheckRule(CheckRuleType, int) CheckRule

	// ConfigCheckable returns the address of the configuration construct that
	// this Checkable belongs to.
	//
	// Checkable objects can potentially be dynamically declared during a
	// plan operation using constructs like resource for_each, and so
	// ConfigCheckable gives us a way to talk about the static containers
	// those dynamic objects belong to, in case we wish to group together
	// dynamic checkable objects into their static checkable for reporting
	// purposes.
	ConfigCheckable() ConfigCheckable

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

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

func ParseCheckableStr

func ParseCheckableStr(kind CheckableKind, src string) (Checkable, tfdiags.Diagnostics)

ParseCheckableStr attempts to parse the given string as a Checkable address of the given kind.

This should be the opposite of Checkable.String for any Checkable address type, as long as "kind" is set to the value returned by the address's CheckableKind method.

We do not typically expect users to write out checkable addresses as input, but we use them as part of some of our wire formats for persisting check results between runs.

type CheckableKind

type CheckableKind rune

CheckableKind describes the different kinds of checkable objects.

const (
	CheckableKindInvalid   CheckableKind = 0
	CheckableResource      CheckableKind = 'R'
	CheckableOutputValue   CheckableKind = 'O'
	CheckableCheck         CheckableKind = 'C'
	CheckableInputVariable CheckableKind = 'I'
)

func (CheckableKind) String

func (i CheckableKind) String() string

type ConfigCheck

type ConfigCheck struct {
	Module Module
	Check  Check
}

ConfigCheck is an address for a check block within a configuration.

This contains a Check address and a Module address, meaning this describes a check block within the entire configuration.

func (ConfigCheck) CheckableKind

func (c ConfigCheck) CheckableKind() CheckableKind

func (ConfigCheck) String

func (c ConfigCheck) String() string

func (ConfigCheck) UniqueKey

func (c ConfigCheck) UniqueKey() UniqueKey

type ConfigCheckable

type ConfigCheckable interface {
	UniqueKeyer

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

ConfigCheckable is an interfaces implemented by address types that represent configuration constructs that can have Checkable addresses associated with them.

This address type therefore in a sense represents a container for zero or more checkable objects all declared by the same configuration construct, so that we can talk about these groups of checkable objects before we're ready to decide how many checkable objects belong to each one.

type ConfigInputVariable

type ConfigInputVariable struct {
	Module   Module
	Variable InputVariable
}

func (ConfigInputVariable) CheckableKind

func (v ConfigInputVariable) CheckableKind() CheckableKind

func (ConfigInputVariable) String

func (v ConfigInputVariable) String() string

func (ConfigInputVariable) UniqueKey

func (v ConfigInputVariable) UniqueKey() UniqueKey

type ConfigMoveable

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 ConfigOutputValue

type ConfigOutputValue struct {
	Module      Module
	OutputValue OutputValue
}

ConfigOutputValue represents a particular "output" block in the configuration, which might have many AbsOutputValue addresses associated with it at runtime if it belongs to a module that was called using "count" or "for_each".

func (ConfigOutputValue) CheckableKind

func (v ConfigOutputValue) CheckableKind() CheckableKind

func (ConfigOutputValue) String

func (v ConfigOutputValue) String() string

func (ConfigOutputValue) UniqueKey

func (v ConfigOutputValue) UniqueKey() UniqueKey

type ConfigRemovable

type ConfigRemovable interface {
	Targetable

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

ConfigRemovable is an interface implemented by address types that represents the destination of a "removed" statement in configuration.

Note that ConfigRemovable might represent:

  1. An absolute address relative to the root of the configuration.
  2. A direct representation of these in configuration where the author gives an address relative to the current module where the address is defined.

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

func (r ConfigResource) AddrType() TargetableAddrType

func (ConfigResource) CheckableKind

func (v ConfigResource) CheckableKind() CheckableKind

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.

func (ConfigResource) UniqueKey

func (r ConfigResource) UniqueKey() UniqueKey

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

func (ca CountAttr) UniqueKey() UniqueKey

type DiagnosticExtraCheckRule

type DiagnosticExtraCheckRule interface {
	// DiagnosticOriginatesFromCheckRule returns the CheckRule that the
	// surrounding diagnostic originated from.
	DiagnosticOriginatesFromCheckRule() CheckRule
}

DiagnosticExtraCheckRule provides an interface for diagnostic ExtraInfo to retrieve an embedded CheckRule from within a tfdiags.Diagnostic.

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

func (f ForEachAttr) UniqueKey() UniqueKey

type Function

type Function struct {
	Namespaces []string
	Name       string
}

func ParseFunction

func ParseFunction(input string) Function

func (Function) AsProviderFunction

func (f Function) AsProviderFunction() (pf ProviderFunction, err error)

func (Function) IsNamespace

func (f Function) IsNamespace(namespace string) bool

func (Function) String

func (f Function) String() string

type InputVariable

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

InputVariable is the address of an input variable.

func (InputVariable) Absolute

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

func (InputVariable) InModule

func (v InputVariable) InModule(module Module) ConfigInputVariable

func (InputVariable) String

func (v InputVariable) String() string

func (InputVariable) UniqueKey

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

func (v LocalValue) UniqueKey() UniqueKey

type Map

type Map[K UniqueKeyer, V any] struct {
	// Elems is the internal data structure of the map.
	//
	// This is exported to allow for comparisons during tests and other similar
	// careful read operations, but callers MUST NOT modify this map directly.
	// Use only the methods of Map to modify the contents of this structure,
	// to ensure that it remains correct and consistent.
	Elems map[UniqueKey]MapElem[K, V]
}

Map represents a mapping whose keys are address types that implement UniqueKeyer.

Since not all address types are comparable in the Go language sense, this type cannot work with the typical Go map access syntax, and so instead has a method-based syntax. Use this type only for situations where the key type isn't guaranteed to always be a valid key for a standard Go map.

func MakeMap

func MakeMap[K UniqueKeyer, V any](initialElems ...MapElem[K, V]) Map[K, V]

func (Map[K, V]) Elements

func (m Map[K, V]) Elements() []MapElem[K, V]

Elements returns a slice containing a snapshot of the current elements of the map, in an unpredictable order.

func (Map[K, V]) Get

func (m Map[K, V]) Get(key K) V

Get returns the value of the element with the given key, or the zero value of V if there is no such element.

func (Map[K, V]) GetOk

func (m Map[K, V]) GetOk(key K) (V, bool)

GetOk is like Get but additionally returns a flag for whether there was an element with the given key present in the map.

func (Map[K, V]) Has

func (m Map[K, V]) Has(key K) bool

Has returns true if and only if there is an element in the map which has the given key.

func (Map[K, V]) Keys

func (m Map[K, V]) Keys() Set[K]

Keys returns a Set[K] containing a snapshot of the current keys of elements of the map.

func (Map[K, V]) Len

func (m Map[K, V]) Len() int

Len returns the number of elements in the map.

func (Map[K, V]) Put

func (m Map[K, V]) Put(key K, value V)

Put inserts a new element into the map, or replaces an existing element which has an equivalent key.

func (Map[K, V]) PutElement

func (m Map[K, V]) PutElement(elem MapElem[K, V])

PutElement is like Put but takes the key and value from the given MapElement structure instead of as individual arguments.

func (Map[K, V]) Remove

func (m Map[K, V]) Remove(key K)

Remove deletes the element with the given key from the map, or does nothing if there is no such element.

func (Map[K, V]) Values

func (m Map[K, V]) Values() []V

Values returns a slice containing a snapshot of the current values of elements of the map, in an unpredictable order.

type MapElem

type MapElem[K UniqueKeyer, V any] struct {
	Key   K
	Value V
}

func MakeMapElem

func MakeMapElem[K UniqueKeyer, V any](key K, value V) MapElem[K, V]

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

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

func (c ModuleCall) Absolute(moduleAddr ModuleInstance) AbsModuleCall

func (ModuleCall) Equal

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

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

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

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

func (c ModuleCallInstance) UniqueKey() UniqueKey

type ModuleCallInstanceOutput

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

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

func (co ModuleCallInstanceOutput) ModuleCallOutput() ModuleCallOutput

ModuleCallOutput returns the referenceable ModuleCallOutput for this particular instance.

func (ModuleCallInstanceOutput) String

func (co ModuleCallInstanceOutput) String() string

func (ModuleCallInstanceOutput) UniqueKey

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

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

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

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

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

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

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

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

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

type ModulePackage string

A ModulePackage represents a physical location where OpenTofu can retrieve a module package, which is an archive, repository, or other similar container which delivers the source code for one or more OpenTofu 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

func (p ModulePackage) String() string

type ModuleRegistryPackage

type ModuleRegistryPackage = tfaddr.ModulePackage

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.

type ModuleSource

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

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

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

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

func (s ModuleSourceLocal) ForDisplay() string

func (ModuleSourceLocal) String

func (s ModuleSourceLocal) String() string

type ModuleSourceRegistry

type ModuleSourceRegistry tfaddr.Module

ModuleSourceRegistry is a ModuleSource representing a module listed in a OpenTofu 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 OpenTofu will then download and install.

func (ModuleSourceRegistry) ForDisplay

func (s ModuleSourceRegistry) ForDisplay() string

func (ModuleSourceRegistry) String

func (s ModuleSourceRegistry) String() string

type ModuleSourceRemote

type ModuleSourceRemote struct {
	// Package is the address of the remote package that the requested
	// module belongs to.
	Package 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

func (s ModuleSourceRemote) ForDisplay() string

func (ModuleSourceRemote) FromRegistry

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

func (s ModuleSourceRemote) String() string

type MoveEndpoint

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 OpenTofu hints about historical configuration changes that might prompt creating a different plan than OpenTofu 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

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

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

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

func (*MoveEndpoint) MightUnifyWith

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

func (e *MoveEndpoint) ObjectKind() MoveEndpointKind

func (*MoveEndpoint) String

func (e *MoveEndpoint) String() string

type MoveEndpointInModule

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

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

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

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

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

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

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

func (e *MoveEndpointInModule) Module() Module

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

func (*MoveEndpointInModule) ModuleCallTraversals

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.

func (*MoveEndpointInModule) NestedWithin

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

func (e *MoveEndpointInModule) ObjectKind() MoveEndpointKind

func (*MoveEndpointInModule) SelectsModule

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

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

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

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

func (i MoveEndpointKind) String() string

type OutputValue

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

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. Outputs are referencable from the testing scope, in general tofu operation users will be referencing ModuleCallOutput.

func (OutputValue) Absolute

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

func (OutputValue) Equal

func (v OutputValue) Equal(o OutputValue) bool

func (OutputValue) InModule

func (v OutputValue) InModule(m Module) ConfigOutputValue

InModule converts the receiver into a config address within the given module.

func (OutputValue) String

func (v OutputValue) String() string

func (OutputValue) UniqueKey

func (v OutputValue) UniqueKey() UniqueKey

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

func (pa PathAttr) UniqueKey() UniqueKey

type Provider

type Provider = tfaddr.Provider

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 OpenTofu 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.

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 ProviderFunction

type ProviderFunction struct {
	ProviderName  string
	ProviderAlias string
	Function      string
	// contains filtered or unexported fields
}

ProviderFunction is the address of a provider defined function.

func (ProviderFunction) String

func (v ProviderFunction) String() string

func (ProviderFunction) UniqueKey

func (v ProviderFunction) UniqueKey() UniqueKey

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 ParseRefFromTestingScope

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

ParseRefFromTestingScope adds check blocks and outputs into the available references returned by ParseRef.

The testing files and functionality have a slightly expanded referencing scope and so should use this function to retrieve references.

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 ParseRefStrFromTestingScope

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

ParseRefStrFromTestingScope matches ParseRefStr except it supports the references supported by ParseRefFromTestingScope.

func (*Reference) DisplayString

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 OpenTofu language syntax that could've produced it.

It's not guaranteed to actually be a valid OpenTofu 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 RemoveEndpoint

type RemoveEndpoint struct {
	// SourceRange is the location of the physical endpoint address
	// in configuration, if this RemoveEndpoint was decoded from a
	// configuration expression.
	SourceRange tfdiags.SourceRange

	// the representation of our relative address as a ConfigRemovable
	RelSubject ConfigRemovable
}

RemoveEndpoint is to ConfigRemovable 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 removable object. It is very similar to MoveEndpoint.

Its purpose is to represent the "from" address in a "removed" block in the configuration.

To obtain a full address from a RemoveEndpoint we need to combine it with any ancestor modules in the configuration

func ParseRemoveEndpoint

func ParseRemoveEndpoint(traversal hcl.Traversal) (*RemoveEndpoint, tfdiags.Diagnostics)

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

This deals only with the syntactic element of a remove 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.

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

func (r Resource) Less(o Resource) bool

func (Resource) Phase

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

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

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 (ResourceInstance) Less

func (ResourceInstance) Phase

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

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

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

func (rp ResourcePhase) UniqueKey() UniqueKey

type Set

type Set[T UniqueKeyer] map[UniqueKey]T

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

Modify the set only by the methods on this type. This type exposes its internals for convenience during reading, such as iterating over set elements by ranging over the map values, but making direct modifications could potentially make the set data invalid or inconsistent, leading to undefined behavior elsewhere.

func MakeSet

func MakeSet[T UniqueKeyer](elems ...T) Set[T]

func (Set[T]) Add

func (s Set[T]) Add(addr T)

Add inserts the given address into the set, if not already present. If an equivalent address is already in the set, this replaces that address with the new value.

func (Set[T]) Has

func (s Set[T]) Has(addr T) bool

Has returns true if and only if the set includes the given address.

func (Set[T]) Intersection

func (s Set[T]) Intersection(other Set[T]) Set[T]

Intersection returns a new set which contains the intersection of all of the elements of both the reciever and the given other set.

func (Set[T]) Remove

func (s Set[T]) Remove(addr T)

Remove deletes the given address from the set, if present. If not present, this is a no-op.

func (Set[T]) Union

func (s Set[T]) Union(other Set[T]) Set[T]

Union returns a new set which contains the union of all of the elements of both the reciever and the given other 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

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

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

func (ta TerraformAttr) UniqueKey() UniqueKey

type UniqueKey

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

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL