instances

Documentation

Index

• type Expander
  • func NewExpander() *Expander
  • func (e *Expander) AllInstances() Set
  • func (e *Expander) ExpandModule(addr addrs.Module) []addrs.ModuleInstance
  • func (e *Expander) ExpandModuleResource(moduleAddr addrs.Module, resourceAddr addrs.Resource) []addrs.AbsResourceInstance
  • func (e *Expander) ExpandResource(resourceAddr addrs.AbsResource) []addrs.AbsResourceInstance
  • func (e *Expander) GetDeepestExistingModuleInstance(given addrs.ModuleInstance) addrs.ModuleInstance
  • func (e *Expander) GetModuleInstanceRepetitionData(addr addrs.ModuleInstance) RepetitionData
  • func (e *Expander) GetResourceInstanceRepetitionData(addr addrs.AbsResourceInstance) RepetitionData
  • func (e *Expander) SetModuleCount(parentAddr addrs.ModuleInstance, callAddr addrs.ModuleCall, count int)
  • func (e *Expander) SetModuleForEach(parentAddr addrs.ModuleInstance, callAddr addrs.ModuleCall, ...)
  • func (e *Expander) SetModuleSingle(parentAddr addrs.ModuleInstance, callAddr addrs.ModuleCall)
  • func (e *Expander) SetResourceCount(moduleAddr addrs.ModuleInstance, resourceAddr addrs.Resource, count int)
  • func (e *Expander) SetResourceForEach(moduleAddr addrs.ModuleInstance, resourceAddr addrs.Resource, ...)
  • func (e *Expander) SetResourceSingle(moduleAddr addrs.ModuleInstance, resourceAddr addrs.Resource)
• type RepetitionData
• type Set
  • func (s Set) HasModuleCall(want addrs.AbsModuleCall) bool
  • func (s Set) HasModuleInstance(want addrs.ModuleInstance) bool
  • func (s Set) HasResource(want addrs.AbsResource) bool
  • func (s Set) HasResourceInstance(want addrs.AbsResourceInstance) bool
  • func (s Set) InstancesForModule(modAddr addrs.Module) []addrs.ModuleInstance

Types

type Expander

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

Expander instances serve as a coordination point for gathering object repetition values (count and for_each in configuration) and then later making use of them to fully enumerate all of the instances of an object.

The two repeatable object types in OpenTofu are modules and resources. Because resources belong to modules and modules can nest inside other modules, module expansion in particular has a recursive effect that can cause deep objects to expand exponentially. Expander assumes that all instances of a module have the same static objects inside, and that they differ only in the repetition count for some of those objects.

Expander is a synchronized object whose methods can be safely called from concurrent threads of execution. However, it does expect a certain sequence of operations which is normally obtained by the caller traversing a dependency graph: each object must have its repetition mode set exactly once, and this must be done before any calls that depend on the repetition mode. In other words, the count or for_each expression value for a module must be provided before any object nested directly or indirectly inside that module can be expanded. If this ordering is violated, the methods will panic to enforce internal consistency.

The Expand* methods of Expander only work directly with modules and with resources. Addresses for other objects that nest within modules but do not themselves support repetition can be obtained by calling ExpandModule with the containing module path and then producing one absolute instance address per module instance address returned.

func NewExpander

func NewExpander() *Expander

NewExpander initializes and returns a new Expander, empty and ready to use.

func (*Expander) AllInstances

func (e *Expander) AllInstances() Set

AllInstances returns a set of all of the module and resource instances known to the expander.

It generally doesn't make sense to call this until everything has already been fully expanded by calling the SetModule* and SetResource* functions. After that, the returned set is a convenient small API only for querying whether particular instance addresses appeared as a result of those expansions.

func (*Expander) ExpandModule

func (e *Expander) ExpandModule(addr addrs.Module) []addrs.ModuleInstance

ExpandModule finds the exhaustive set of module instances resulting from the expansion of the given module and all of its ancestor modules.

All of the modules on the path to the identified module must already have had their expansion registered using one of the SetModule* methods before calling, or this method will panic.

func (*Expander) ExpandModuleResource

func (e *Expander) ExpandModuleResource(moduleAddr addrs.Module, resourceAddr addrs.Resource) []addrs.AbsResourceInstance

ExpandModuleResource finds the exhaustive set of resource instances resulting from the expansion of the given resource and all of its containing modules.

All of the modules on the path to the identified resource and the resource itself must already have had their expansion registered using one of the SetModule*/SetResource* methods before calling, or this method will panic.

func (*Expander) ExpandResource

func (e *Expander) ExpandResource(resourceAddr addrs.AbsResource) []addrs.AbsResourceInstance

ExpandResource finds the set of resource instances resulting from the expansion of the given resource within its module instance.

All of the modules on the path to the identified resource and the resource itself must already have had their expansion registered using one of the SetModule*/SetResource* methods before calling, or this method will panic.

ExpandModuleResource returns all instances of a resource across all instances of its containing module, whereas this ExpandResource function is more specific and only expands within a single module instance. If any of the module instances selected in the module path of the given address aren't valid for that module's expansion then ExpandResource returns an empty result, reflecting that a non-existing module instance can never contain any existing resource instances.

func (*Expander) GetDeepestExistingModuleInstance

func (e *Expander) GetDeepestExistingModuleInstance(given addrs.ModuleInstance) addrs.ModuleInstance

GetDeepestExistingModuleInstance is a funny specialized function for determining how many steps we can traverse through the given module instance address before encountering an undeclared instance of a declared module.

The result is the longest prefix of the given address which steps only through module instances that exist.

All of the modules on the given path must already have had their expansion registered using one of the SetModule* methods before calling, or this method will panic.

func (*Expander) GetModuleInstanceRepetitionData

func (e *Expander) GetModuleInstanceRepetitionData(addr addrs.ModuleInstance) RepetitionData

GetModuleInstanceRepetitionData returns an object describing the values that should be available for each.key, each.value, and count.index within the call block for the given module instance.

func (*Expander) GetResourceInstanceRepetitionData

func (e *Expander) GetResourceInstanceRepetitionData(addr addrs.AbsResourceInstance) RepetitionData

GetResourceInstanceRepetitionData returns an object describing the values that should be available for each.key, each.value, and count.index within the definition block for the given resource instance.

func (*Expander) SetModuleCount

func (e *Expander) SetModuleCount(parentAddr addrs.ModuleInstance, callAddr addrs.ModuleCall, count int)

SetModuleCount records that the given module call inside the given parent module instance uses the "count" repetition argument, with the given value.

func (*Expander) SetModuleForEach

func (e *Expander) SetModuleForEach(parentAddr addrs.ModuleInstance, callAddr addrs.ModuleCall, mapping map[string]cty.Value)

SetModuleForEach records that the given module call inside the given parent module instance uses the "for_each" repetition argument, with the given map value.

In the configuration language the for_each argument can also accept a set. It's the caller's responsibility to convert that into an identity map before calling this method.

func (*Expander) SetModuleSingle

func (e *Expander) SetModuleSingle(parentAddr addrs.ModuleInstance, callAddr addrs.ModuleCall)

SetModuleSingle records that the given module call inside the given parent module does not use any repetition arguments and is therefore a singleton.

func (*Expander) SetResourceCount

func (e *Expander) SetResourceCount(moduleAddr addrs.ModuleInstance, resourceAddr addrs.Resource, count int)

SetResourceCount records that the given resource inside the given module uses the "count" repetition argument, with the given value.

func (*Expander) SetResourceForEach

func (e *Expander) SetResourceForEach(moduleAddr addrs.ModuleInstance, resourceAddr addrs.Resource, mapping map[string]cty.Value)

SetResourceForEach records that the given resource inside the given module uses the "for_each" repetition argument, with the given map value.

In the configuration language the for_each argument can also accept a set. It's the caller's responsibility to convert that into an identity map before calling this method.

func (*Expander) SetResourceSingle

func (e *Expander) SetResourceSingle(moduleAddr addrs.ModuleInstance, resourceAddr addrs.Resource)

SetResourceSingle records that the given resource inside the given module does not use any repetition arguments and is therefore a singleton.

type RepetitionData

type RepetitionData struct {
	// CountIndex is the value for count.index, or cty.NilVal if evaluating
	// in a context where the "count" argument is not active.
	//
	// For correct operation, this should always be of type cty.Number if not
	// nil.
	CountIndex cty.Value

	// EachKey and EachValue are the values for each.key and each.value
	// respectively, or cty.NilVal if evaluating in a context where the
	// "for_each" argument is not active. These must either both be set
	// or neither set.
	//
	// For correct operation, EachKey must always be either of type cty.String
	// or cty.Number if not nil.
	EachKey, EachValue cty.Value
}

RepetitionData represents the values available to identify individual repetitions of a particular object.

This corresponds to the each.key, each.value, and count.index symbols in the configuration language.

type Set

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

Set is a set of instances, intended mainly for the return value of Expander.AllInstances, where it therefore represents all of the module and resource instances known to the expander.

func (Set) HasModuleCall

func (s Set) HasModuleCall(want addrs.AbsModuleCall) bool

HasModuleCall returns true if and only if the set contains the module call with the given address, even if that module call has no instances.

func (Set) HasModuleInstance

func (s Set) HasModuleInstance(want addrs.ModuleInstance) bool

HasModuleInstance returns true if and only if the set contains the module instance with the given address.

func (Set) HasResource

func (s Set) HasResource(want addrs.AbsResource) bool

HasResource returns true if and only if the set contains the resource with the given address, even if that resource has no instances. TODO:

func (Set) HasResourceInstance

func (s Set) HasResourceInstance(want addrs.AbsResourceInstance) bool

HasResourceInstance returns true if and only if the set contains the resource instance with the given address. TODO:

func (Set) InstancesForModule

func (s Set) InstancesForModule(modAddr addrs.Module) []addrs.ModuleInstance

InstancesForModule returns all of the module instances that correspond with the given static module path.

If there are multiple module calls in the path that have repetition enabled then the result is the full expansion of all combinations of all of their declared instance keys.