12 "github.com/hashicorp/terraform/tfdiags"
14 getter "github.com/hashicorp/go-getter"
15 "github.com/hashicorp/terraform/config"
18 // RootName is the name of the root tree.
19 const RootName = "root"
21 // Tree represents the module import tree of configurations.
23 // This Tree structure can be used to get (download) new modules, load
24 // all the modules without getting, flatten the tree into something
25 // Terraform can use, etc.
29 children map[string]*Tree
33 // version is the final version of the config loaded for the Tree's module
35 // source is the "source" string used to load this module. It's possible
36 // for a module source to change, but the path remains the same, preventing
37 // it from being reloaded.
39 // parent allows us to walk back up the tree and determine if there are any
40 // versioned ancestor modules which may effect the stored location of
45 // NewTree returns a new Tree for the given config structure.
46 func NewTree(name string, c *config.Config) *Tree {
47 return &Tree{config: c, name: name}
50 // NewEmptyTree returns a new tree that is empty (contains no configuration).
51 func NewEmptyTree() *Tree {
52 t := &Tree{config: &config.Config{}}
54 // We do this dummy load so that the tree is marked as "loaded". It
55 // should never fail because this is just about a no-op. If it does fail
56 // we panic so we can know its a bug.
57 if err := t.Load(&Storage{Mode: GetModeGet}); err != nil {
64 // NewTreeModule is like NewTree except it parses the configuration in
65 // the directory and gives it a specific name. Use a blank name "" to specify
67 func NewTreeModule(name, dir string) (*Tree, error) {
68 c, err := config.LoadDir(dir)
73 return NewTree(name, c), nil
76 // Config returns the configuration for this module.
77 func (t *Tree) Config() *config.Config {
81 // Child returns the child with the given path (by name).
82 func (t *Tree) Child(path []string) *Tree {
91 c := t.Children()[path[0]]
96 return c.Child(path[1:])
99 // Children returns the children of this tree (the modules that are
100 // imported by this root).
102 // This will only return a non-nil value after Load is called.
103 func (t *Tree) Children() map[string]*Tree {
105 defer t.lock.RUnlock()
109 // DeepEach calls the provided callback for the receiver and then all of
110 // its descendents in the tree, allowing an operation to be performed on
111 // all modules in the tree.
113 // Parents will be visited before their children but otherwise the order is
115 func (t *Tree) DeepEach(cb func(*Tree)) {
117 defer t.lock.RUnlock()
121 func (t *Tree) deepEach(cb func(*Tree)) {
123 for _, c := range t.children {
128 // Loaded says whether or not this tree has been loaded or not yet.
129 func (t *Tree) Loaded() bool {
131 defer t.lock.RUnlock()
132 return t.children != nil
135 // Modules returns the list of modules that this tree imports.
137 // This is only the imports of _this_ level of the tree. To retrieve the
138 // full nested imports, you'll have to traverse the tree.
139 func (t *Tree) Modules() []*Module {
140 result := make([]*Module, len(t.config.Modules))
141 for i, m := range t.config.Modules {
146 Providers: m.Providers,
153 // Name returns the name of the tree. This will be "<root>" for the root
154 // tree and then the module name given for any children.
155 func (t *Tree) Name() string {
163 // Load loads the configuration of the entire tree.
165 // The parameters are used to tell the tree where to find modules and
166 // whether it can download/update modules along the way.
168 // Calling this multiple times will reload the tree.
170 // Various semantic-like checks are made along the way of loading since
171 // module trees inherently require the configuration to be in a reasonably
172 // sane state: no circular dependencies, proper module sources, etc. A full
173 // suite of validations can be done by running Validate (after loading).
174 func (t *Tree) Load(s *Storage) error {
176 defer t.lock.Unlock()
178 children, err := t.getChildren(s)
183 // Go through all the children and load them.
184 for _, c := range children {
185 if err := c.Load(s); err != nil {
191 t.children = children
196 func (t *Tree) getChildren(s *Storage) (map[string]*Tree, error) {
197 children := make(map[string]*Tree)
199 // Go through all the modules and get the directory for them.
200 for _, m := range t.Modules() {
201 if _, ok := children[m.Name]; ok {
202 return nil, fmt.Errorf(
203 "module %s: duplicated. module names must be unique", m.Name)
206 // Determine the path to this child
207 modPath := make([]string, len(t.path), len(t.path)+1)
208 copy(modPath, t.path)
209 modPath = append(modPath, m.Name)
211 log.Printf("[TRACE] module source: %q", m.Source)
213 // add the module path to help indicate where modules with relative
214 // paths are being loaded from
215 s.output(fmt.Sprintf("- module.%s", strings.Join(modPath, ".")))
217 // Lookup the local location of the module.
218 // dir is the local directory where the module is stored
219 mod, err := s.findRegistryModule(m.Source, m.Version)
224 // The key is the string that will be used to uniquely id the Source in
225 // the local storage. The prefix digit can be incremented to
226 // invalidate the local module storage.
227 key := "1." + t.versionedPathKey(m)
228 if mod.Version != "" {
229 key += "." + mod.Version
232 // Check for the exact key if it's not a registry module
234 mod.Dir, err = s.findModule(key)
240 if mod.Dir != "" && s.Mode != GetModeUpdate {
241 // We found it locally, but in order to load the Tree we need to
242 // find out if there was another subDir stored from detection.
243 subDir, err := s.getModuleRoot(mod.Dir)
245 // If there's a problem with the subdir record, we'll let the
246 // recordSubdir method fix it up. Any other filesystem errors
247 // will turn up again below.
248 log.Println("[WARN] error reading subdir record:", err)
251 fullDir := filepath.Join(mod.Dir, subDir)
253 child, err := NewTreeModule(m.Name, fullDir)
255 return nil, fmt.Errorf("module %s: %s", m.Name, err)
259 child.version = mod.Version
260 child.source = m.Source
261 children[m.Name] = child
265 // Split out the subdir if we have one.
266 // Terraform keeps the entire requested tree, so that modules can
267 // reference sibling modules from the same archive or repo.
268 rawSource, subDir := getter.SourceDirSubdir(m.Source)
270 // we haven't found a source, so fallback to the go-getter detectors
273 source, err = getter.Detect(rawSource, t.config.Dir, getter.Detectors)
275 return nil, fmt.Errorf("module %s: %s", m.Name, err)
279 log.Printf("[TRACE] detected module source %q", source)
281 // Check if the detector introduced something new.
282 // For example, the registry always adds a subdir of `//*`,
283 // indicating that we need to strip off the first component from the
284 // tar archive, though we may not yet know what it is called.
285 source, detectedSubDir := getter.SourceDirSubdir(source)
286 if detectedSubDir != "" {
287 subDir = filepath.Join(detectedSubDir, subDir)
293 output = fmt.Sprintf(" Updating source %q", m.Source)
295 output = fmt.Sprintf(" Getting source %q", m.Source)
299 dir, ok, err := s.getStorage(key, source)
304 return nil, fmt.Errorf("module %s: not found, may need to run 'terraform init'", m.Name)
307 log.Printf("[TRACE] %q stored in %q", source, dir)
309 // expand and record the subDir for later
312 fullDir, err = getter.SubdirGlob(dir, subDir)
317 // +1 to account for the pathsep
318 if len(dir)+1 > len(fullDir) {
319 return nil, fmt.Errorf("invalid module storage path %q", fullDir)
321 subDir = fullDir[len(dir)+1:]
324 // add new info to the module record
329 // record the module in our manifest
330 if err := s.recordModule(mod); err != nil {
334 child, err := NewTreeModule(m.Name, fullDir)
336 return nil, fmt.Errorf("module %s: %s", m.Name, err)
340 child.version = mod.Version
341 child.source = m.Source
342 children[m.Name] = child
348 // Path is the full path to this tree.
349 func (t *Tree) Path() []string {
353 // String gives a nice output to describe the tree.
354 func (t *Tree) String() string {
355 var result bytes.Buffer
356 path := strings.Join(t.path, ", ")
358 path = fmt.Sprintf(" (path: %s)", path)
360 result.WriteString(t.Name() + path + "\n")
364 result.WriteString(" not loaded")
366 // Go through each child and get its string value, then indent it
368 for _, c := range cs {
369 r := strings.NewReader(c.String())
370 scanner := bufio.NewScanner(r)
372 result.WriteString(" ")
373 result.WriteString(scanner.Text())
374 result.WriteString("\n")
379 return result.String()
382 // Validate does semantic checks on the entire tree of configurations.
384 // This will call the respective config.Config.Validate() functions as well
385 // as verifying things such as parameters/outputs between the various modules.
387 // Load must be called prior to calling Validate or an error will be returned.
388 func (t *Tree) Validate() tfdiags.Diagnostics {
389 var diags tfdiags.Diagnostics
392 diags = diags.Append(fmt.Errorf(
393 "tree must be loaded before calling Validate",
398 // Terraform core does not handle root module children named "root".
399 // We plan to fix this in the future but this bug was brought up in
400 // the middle of a release and we don't want to introduce wide-sweeping
401 // changes at that time.
402 if len(t.path) == 1 && t.name == "root" {
403 diags = diags.Append(fmt.Errorf(
404 "root module cannot contain module named 'root'",
409 // Validate our configuration first.
410 diags = diags.Append(t.config.Validate())
412 // If we're the root, we do extra validation. This validation usually
413 // requires the entire tree (since children don't have parent pointers).
414 if len(t.path) == 0 {
415 if err := t.validateProviderAlias(); err != nil {
416 diags = diags.Append(err)
420 // Get the child trees
421 children := t.Children()
423 // Validate all our children
424 for _, c := range children {
425 childDiags := c.Validate()
426 diags = diags.Append(childDiags)
427 if diags.HasErrors() {
432 // Go over all the modules and verify that any parameters are valid
433 // variables into the module in question.
434 for _, m := range t.config.Modules {
435 tree, ok := children[m.Name]
437 // This should never happen because Load watches us
438 panic("module not found in children: " + m.Name)
441 // Build the variables that the module defines
442 requiredMap := make(map[string]struct{})
443 varMap := make(map[string]struct{})
444 for _, v := range tree.config.Variables {
445 varMap[v.Name] = struct{}{}
448 requiredMap[v.Name] = struct{}{}
452 // Compare to the keys in our raw config for the module
453 for k, _ := range m.RawConfig.Raw {
454 if _, ok := varMap[k]; !ok {
455 diags = diags.Append(fmt.Errorf(
456 "module %q: %q is not a valid argument",
461 // Remove the required
462 delete(requiredMap, k)
465 // If we have any required left over, they aren't set.
466 for k, _ := range requiredMap {
467 diags = diags.Append(fmt.Errorf(
468 "module %q: missing required argument %q",
474 // Go over all the variables used and make sure that any module
475 // variables represent outputs properly.
476 for source, vs := range t.config.InterpolatedVariables() {
477 for _, v := range vs {
478 mv, ok := v.(*config.ModuleVariable)
483 tree, ok := children[mv.Name]
485 diags = diags.Append(fmt.Errorf(
486 "%s: reference to undefined module %q",
493 for _, o := range tree.config.Outputs {
494 if o.Name == mv.Field {
500 diags = diags.Append(fmt.Errorf(
501 "%s: %q is not a valid output for module %q",
502 source, mv.Field, mv.Name,
511 // versionedPathKey returns a path string with every levels full name, version
512 // and source encoded. This is to provide a unique key for our module storage,
513 // since submodules need to know which versions of their ancestor modules they
515 // For example, if module A has a subdirectory B, if module A's source or
516 // version is updated B's storage key must reflect this change in order for the
517 // correct version of B's source to be loaded.
518 func (t *Tree) versionedPathKey(m *Module) string {
519 path := make([]string, len(t.path)+1)
520 path[len(path)-1] = m.Name + ";" + m.Source
521 // We're going to load these in order for easier reading and debugging, but
522 // in practice they only need to be unique and consistent.
530 // we may have been loaded under a blank Tree, so always check for a name
537 seg += "#" + p.version
541 seg += ";" + p.source
548 key := strings.Join(path, "|")
552 // treeError is an error use by Tree.Validate to accumulates all
553 // validation errors.
554 type treeError struct {
557 Children []*treeError
560 func (e *treeError) Add(err error) {
561 e.Errs = append(e.Errs, err)
564 func (e *treeError) AddChild(err *treeError) {
565 e.Children = append(e.Children, err)
568 func (e *treeError) ErrOrNil() error {
569 if len(e.Errs) > 0 || len(e.Children) > 0 {
575 func (e *treeError) Error() string {
576 name := strings.Join(e.Name, ".")
578 fmt.Fprintf(&out, "module %s: ", name)
580 if len(e.Errs) == 1 {
582 out.WriteString(e.Errs[0].Error())
585 for _, err := range e.Errs {
586 fmt.Fprintf(&out, "\n %s", err)
590 if len(e.Children) > 0 {
591 // start the next error on a new line
592 out.WriteString("\n ")
594 for _, child := range e.Children {
595 out.WriteString(child.Error())