configload

package
v0.11.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 15, 2018 License: MPL-2.0 Imports: 18 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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 InstallHooks

type InstallHooks 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)
}

InstallHooks 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 InstallHooksImpl

type InstallHooksImpl struct {
}

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

func (InstallHooksImpl) Download

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

func (InstallHooksImpl) Install

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

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 (*Loader) CanInstallModules

func (l *Loader) CanInstallModules() bool

CanInstallModules returns true if InstallModules can be used with this loader.

Loaders created with NewLoader can always install modules. Loaders created from plan files (where the configuration is embedded in the plan file itself) cannot install modules, because the plan file is read-only.

func (*Loader) InitDirFromModule

func (l *Loader) InitDirFromModule(rootDir, sourceAddr string, hooks InstallHooks) hcl.Diagnostics

InitDirFromModule 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.

This can be installed only on a loder that can install modules, and will panic otherwise. Use CanInstallModules to determine if this method can be used, or refer to the documentation of that method for situations where install ability is guaranteed.

func (*Loader) InstallModules

func (l *Loader) InstallModules(rootDir string, upgrade bool, hooks InstallHooks) hcl.Diagnostics

InstallModules analyses the root module in the given directory and installs all of its direct and transitive dependencies into the loader's 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.

This function will panic if called on a loader that cannot install modules. Use CanInstallModules to determine if a loader can install modules, or refer to the documentation for that method for situations where module installation capability is guaranteed.

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, and also detects

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) 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().

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL