initwd

Documentation

Overview

Package initwd contains various helper functions used by the "terraform init" command to initialize a working directory.

These functions may also be used from testing code to simulate the behaviors of "terraform init" against test fixtures, but should not be used elsewhere in the main code.

Index

• func CheckCoreVersionRequirements(earlyConfig *earlyconfig.Config) tfdiags.Diagnostics
• func DirFromModule(rootDir, modulesDir, sourceAddr string, reg *registry.Client, ...) tfdiags.Diagnostics
• func LoadConfig(rootDir, modulesDir string) (*earlyconfig.Config, tfdiags.Diagnostics)
• func LoadConfigForTests(t *testing.T, rootDir string) (*configs.Config, *configload.Loader, func(), tfdiags.Diagnostics)
• func MustLoadConfigForTests(t *testing.T, rootDir string) (*configs.Config, *configload.Loader, func())
• type MaybeRelativePathErr
  • func (e *MaybeRelativePathErr) Error() string
• type ModuleInstallHooks
• type ModuleInstallHooksImpl
  • func (h ModuleInstallHooksImpl) Download(moduleAddr, packageAddr string, version *version.Version)
  • func (h ModuleInstallHooksImpl) Install(moduleAddr string, version *version.Version, localPath string)
• type ModuleInstaller
  • func NewModuleInstaller(modsDir string, reg *registry.Client) *ModuleInstaller
  • func (i *ModuleInstaller) InstallModules(rootDir string, upgrade bool, hooks ModuleInstallHooks) (*earlyconfig.Config, tfdiags.Diagnostics)

Functions

func CheckCoreVersionRequirements

func CheckCoreVersionRequirements(earlyConfig *earlyconfig.Config) tfdiags.Diagnostics

CheckCoreVersionRequirements visits each of the modules in the given early configuration tree and verifies that any given Core version constraints match with the version of Terraform Core that is being used.

The returned diagnostics will contain errors if any constraints do not match. The returned diagnostics might also return warnings, which should be displayed to the user.

func DirFromModule

func DirFromModule(rootDir, modulesDir, sourceAddr string, reg *registry.Client, hooks ModuleInstallHooks) tfdiags.Diagnostics

DirFromModule populates the given directory (which must exist and be empty) with the contents of the module at the given source address.

It does this by installing the given module and all of its descendent modules in a temporary root directory and then copying the installed files into suitable locations. As a consequence, any diagnostics it generates will reveal the location of this temporary directory to the user.

This rather roundabout installation approach is taken to ensure that installation proceeds in a manner identical to normal module installation.

If the given source address specifies a sub-directory of the given package then only the sub-directory and its descendents will be copied into the given root directory, which will cause any relative module references using ../ from that module to be unresolvable. Error diagnostics are produced in that case, to prompt the user to rewrite the source strings to be absolute references to the original remote module.

func LoadConfig

func LoadConfig(rootDir, modulesDir string) (*earlyconfig.Config, tfdiags.Diagnostics)

LoadConfig loads a full configuration tree that has previously had all of its dependent modules installed to the given modulesDir using a ModuleInstaller.

This uses the early configuration loader and thus only reads top-level metadata from the modules in the configuration. Most callers should use the configs/configload package to fully load a configuration.

func LoadConfigForTests

func LoadConfigForTests(t *testing.T, rootDir string) (*configs.Config, *configload.Loader, func(), tfdiags.Diagnostics)

LoadConfigForTests is a convenience wrapper around configload.NewLoaderForTests, ModuleInstaller.InstallModules and configload.Loader.LoadConfig that allows a test configuration to be loaded in a single step.

If module installation fails, t.Fatal (or similar) is called to halt execution of the test, under the assumption that installation failures are not expected. If installation failures _are_ expected then use NewLoaderForTests and work with the loader object directly. If module installation succeeds but generates warnings, these warnings are discarded.

If installation succeeds but errors are detected during loading then a possibly-incomplete config is returned along with error diagnostics. The test run is not aborted in this case, so that the caller can make assertions against the returned diagnostics.

As with NewLoaderForTests, a cleanup function is returned which must be called before the test completes in order to remove the temporary modules directory.

func MustLoadConfigForTests

func MustLoadConfigForTests(t *testing.T, rootDir string) (*configs.Config, *configload.Loader, func())

MustLoadConfigForTests is a variant of LoadConfigForTests which calls t.Fatal (or similar) if there are any errors during loading, and thus does not return diagnostics at all.

This is useful for concisely writing tests that don't expect errors at all. For tests that expect errors and need to assert against them, use LoadConfigForTests instead.

Types

type MaybeRelativePathErr

type MaybeRelativePathErr struct {
	Addr string
}

func (*MaybeRelativePathErr) Error

func (e *MaybeRelativePathErr) Error() string

type ModuleInstallHooks

type ModuleInstallHooks interface {
	// Download is called for modules that are retrieved from a remote source
	// before that download begins, to allow a caller to give feedback
	// on progress through a possibly-long sequence of downloads.
	Download(moduleAddr, packageAddr string, version *version.Version)

	// Install is called for each module that is installed, even if it did
	// not need to be downloaded from a remote source.
	Install(moduleAddr string, version *version.Version, localPath string)
}

ModuleInstallHooks is an interface used to provide notifications about the installation process being orchestrated by InstallModules.

This interface may have new methods added in future, so implementers should embed InstallHooksImpl to get no-op implementations of any unimplemented methods.

type ModuleInstallHooksImpl

type ModuleInstallHooksImpl struct {
}

ModuleInstallHooksImpl is a do-nothing implementation of InstallHooks that can be embedded in another implementation struct to allow only partial implementation of the interface.

func (ModuleInstallHooksImpl) Download

func (h ModuleInstallHooksImpl) Download(moduleAddr, packageAddr string, version *version.Version)

func (ModuleInstallHooksImpl) Install

func (h ModuleInstallHooksImpl) Install(moduleAddr string, version *version.Version, localPath string)

type ModuleInstaller

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

func NewModuleInstaller

func NewModuleInstaller(modsDir string, reg *registry.Client) *ModuleInstaller

func (*ModuleInstaller) InstallModules

func (i *ModuleInstaller) InstallModules(rootDir string, upgrade bool, hooks ModuleInstallHooks) (*earlyconfig.Config, tfdiags.Diagnostics)

InstallModules analyses the root module in the given directory and installs all of its direct and transitive dependencies into the given modules directory, which must already exist.

Since InstallModules makes possibly-time-consuming calls to remote services, a hook interface is supported to allow the caller to be notified when each module is installed and, for remote modules, when downloading begins. LoadConfig guarantees that two hook calls will not happen concurrently but it does not guarantee any particular ordering of hook calls. This mechanism is for UI feedback only and does not give the caller any control over the process.

If modules are already installed in the target directory, they will be skipped unless their source address or version have changed or unless the upgrade flag is set.

InstallModules never deletes any directory, except in the case where it needs to replace a directory that is already present with a newly-extracted package.

If the returned diagnostics contains errors then the module installation may have wholly or partially completed. Modules must be loaded in order to find their dependencies, so this function does many of the same checks as LoadConfig as a side-effect.

If successful (the returned diagnostics contains no errors) then the first return value is the early configuration tree that was constructed by the installation process.