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 DirFromModule(ctx context.Context, loader *configload.Loader, ...) tfdiags.Diagnostics
• func LoadConfigForTests(t *testing.T, rootDir string, testsDir string) (*configs.Config, *configload.Loader, func(), tfdiags.Diagnostics)
• func MustLoadConfigForTests(t *testing.T, rootDir, testsDir string) (*configs.Config, *configload.Loader, func())
• 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, loader *configload.Loader, reg *registry.Client) *ModuleInstaller
  • func (i *ModuleInstaller) InstallModules(ctx context.Context, rootDir, testsDir string, upgrade, installErrsOnly bool, ...) (*configs.Config, tfdiags.Diagnostics)

Functions

func DirFromModule

func DirFromModule(ctx context.Context, loader *configload.Loader, rootDir, modulesDir, sourceAddrStr 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 LoadConfigForTests

func LoadConfigForTests(t *testing.T, rootDir string, testsDir 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, testsDir 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 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, loader *configload.Loader, reg *registry.Client) *ModuleInstaller

func (*ModuleInstaller) InstallModules

func (i *ModuleInstaller) InstallModules(ctx context.Context, rootDir, testsDir string, upgrade, installErrsOnly bool, hooks ModuleInstallHooks) (*configs.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.

installErrsOnly installs modules but converts validation errors from building the configuration after installation to warnings. This is used by commands like `get` or `init -from-module` where the established behavior was only to install the requested module, and extra validation can break compatibility.

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.