configload

Documentation

Overview

Package configload knows how to install modules into the .terraform/modules directory and to load modules from those installed locations. It is used in conjunction with the LoadConfig function in the parent package.

Index

• type Config
• type Loader
  • func NewLoader(config *Config) (*Loader, error)
  • func NewLoaderForTests(t *testing.T) (*Loader, func())
  • func NewLoaderFromSnapshot(snap *Snapshot) *Loader
  • func (l *Loader) AllowLanguageExperiments(allowed bool)
  • func (l *Loader) ImportSources(sources map[string][]byte)
  • func (l *Loader) ImportSourcesFromSnapshot(snap *Snapshot)
  • func (l *Loader) IsConfigDir(path string) bool
  • func (l *Loader) LoadConfig(rootDir string) (*configs.Config, hcl.Diagnostics)
  • func (l *Loader) LoadConfigWithSnapshot(rootDir string) (*configs.Config, *Snapshot, hcl.Diagnostics)
  • func (l *Loader) ModulesDir() string
  • func (l *Loader) Parser() *configs.Parser
  • func (l *Loader) RefreshModules() error
  • func (l *Loader) Sources() map[string][]byte
• type Snapshot
  • func NewEmptySnapshot() *Snapshot
• type SnapshotModule

Types

type Config

type Config struct {
	// ModulesDir is a path to a directory where descendent modules are
	// (or should be) installed. (This is usually the
	// .terraform/modules directory, in the common case where this package
	// is being loaded from the main Terraform CLI package.)
	ModulesDir string

	// Services is the service discovery client to use when locating remote
	// module registry endpoints. If this is nil then registry sources are
	// not supported, which should be true only in specialized circumstances
	// such as in tests.
	Services *disco.Disco
}

Config is used with NewLoader to specify configuration arguments for the loader.

type Loader

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

A Loader instance is the main entry-point for loading configurations via this package.

It extends the general config-loading functionality in the parent package "configs" to support installation of modules from remote sources and loading full configurations using modules that were previously installed.

func NewLoader

func NewLoader(config *Config) (*Loader, error)

NewLoader creates and returns a loader that reads configuration from the real OS filesystem.

The loader has some internal state about the modules that are currently installed, which is read from disk as part of this function. If that manifest cannot be read then an error will be returned.

func NewLoaderForTests

func NewLoaderForTests(t *testing.T) (*Loader, func())

NewLoaderForTests is a variant of NewLoader that is intended to be more convenient for unit tests.

The loader's modules directory is a separate temporary directory created for each call. Along with the created loader, this function returns a cleanup function that should be called before the test completes in order to remove that temporary directory.

In the case of any errors, t.Fatal (or similar) will be called to halt execution of the test, so the calling test does not need to handle errors itself.

func NewLoaderFromSnapshot

func NewLoaderFromSnapshot(snap *Snapshot) *Loader

NewLoaderFromSnapshot creates a Loader that reads files only from the given snapshot.

A snapshot-based loader cannot install modules, so calling InstallModules on the return value will cause a panic.

A snapshot-based loader also has access only to configuration files. Its underlying parser does not have access to other files in the native filesystem, such as values files. For those, either use a normal loader (created by NewLoader) or use the configs.Parser API directly.

func (*Loader) AllowLanguageExperiments

func (l *Loader) AllowLanguageExperiments(allowed bool)

AllowLanguageExperiments specifies whether subsequent LoadConfig (and similar) calls will allow opting in to experimental language features.

If this method is never called for a particular loader, the default behavior is to disallow language experiments.

Main code should set this only for alpha or development builds. Test code is responsible for deciding for itself whether and how to call this method.

func (*Loader) ImportSources

func (l *Loader) ImportSources(sources map[string][]byte)

ImportSources writes into the receiver's source code map the given source code buffers.

This is useful in the situation where an ancillary loader is created for some reason (e.g. loading config from a plan file) but the cached source code from that loader must be imported into the "main" loader in order to return source code snapshots in diagnostic messages.

loader.ImportSources(otherLoader.Sources())

func (*Loader) ImportSourcesFromSnapshot

func (l *Loader) ImportSourcesFromSnapshot(snap *Snapshot)

ImportSourcesFromSnapshot writes into the receiver's source code the source files from the given snapshot.

This is similar to ImportSources but knows how to unpack and flatten a snapshot data structure to get the corresponding flat source file map.

func (*Loader) IsConfigDir

func (l *Loader) IsConfigDir(path string) bool

IsConfigDir returns true if and only if the given directory contains at least one Terraform configuration file. This is a wrapper around calling the same method name on the loader's parser.

func (*Loader) LoadConfig

func (l *Loader) LoadConfig(rootDir string) (*configs.Config, hcl.Diagnostics)

LoadConfig reads the Terraform module in the given directory and uses it as the root module to build the static module tree that represents a configuration, assuming that all required descendent modules have already been installed.

If error diagnostics are returned, the returned configuration may be either nil or incomplete. In the latter case, cautious static analysis is possible in spite of the errors.

LoadConfig performs the basic syntax and uniqueness validations that are required to process the individual modules

func (*Loader) LoadConfigWithSnapshot

func (l *Loader) LoadConfigWithSnapshot(rootDir string) (*configs.Config, *Snapshot, hcl.Diagnostics)

LoadConfigWithSnapshot is a variant of LoadConfig that also simultaneously creates an in-memory snapshot of the configuration files used, which can be later used to create a loader that may read only from this snapshot.

func (*Loader) ModulesDir

func (l *Loader) ModulesDir() string

ModulesDir returns the path to the directory where the loader will look for the local cache of remote module packages.

func (*Loader) Parser

func (l *Loader) Parser() *configs.Parser

Parser returns the underlying parser for this loader.

This is useful for loading other sorts of files than the module directories that a loader deals with, since then they will share the source code cache for this loader and can thus be shown as snippets in diagnostic messages.

func (*Loader) RefreshModules

func (l *Loader) RefreshModules() error

RefreshModules updates the in-memory cache of the module manifest from the module manifest file on disk. This is not necessary in normal use because module installation and configuration loading are separate steps, but it can be useful in tests where module installation is done as a part of configuration loading by a helper function.

Call this function after any module installation where an existing loader is already alive and may be used again later.

An error is returned if the manifest file cannot be read.

func (*Loader) Sources

func (l *Loader) Sources() map[string][]byte

Sources returns the source code cache for the underlying parser of this loader. This is a shorthand for l.Parser().Sources().

type Snapshot

type Snapshot struct {
	// Modules is a map from opaque module keys (suitable for use as directory
	// names on all supported operating systems) to the snapshot information
	// about each module.
	Modules map[string]*SnapshotModule
}

Snapshot is an in-memory representation of the source files from a configuration, which can be used as an alternative configurations source for a loader with NewLoaderFromSnapshot.

The primary purpose of a Snapshot is to build the configuration portion of a plan file (see ../../plans/planfile) so that it can later be reloaded and used to recover the exact configuration that the plan was built from.

func NewEmptySnapshot

func NewEmptySnapshot() *Snapshot

NewEmptySnapshot constructs and returns a snapshot containing only an empty root module. This is not useful for anything except placeholders in tests.

type SnapshotModule

type SnapshotModule struct {
	// Dir is the path, relative to the root directory given when the
	// snapshot was created, where the module appears in the snapshot's
	// virtual filesystem.
	Dir string

	// Files is a map from each configuration file filename for the
	// module to a raw byte representation of the source file contents.
	Files map[string][]byte

	// SourceAddr is the source address given for this module in configuration.
	SourceAddr string `json:"Source"`

	// Version is the version of the module that is installed, or nil if
	// the module is installed from a source that does not support versions.
	Version *version.Version `json:"-"`
}

SnapshotModule represents a single module within a Snapshot.