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 InstallHooks
- type InstallHooksImpl
- type Loader
- func (l *Loader) CanInstallModules() bool
- func (l *Loader) InitDirFromModule(rootDir, sourceAddr string, hooks InstallHooks) hcl.Diagnostics
- func (l *Loader) InstallModules(rootDir string, upgrade bool, hooks InstallHooks) hcl.Diagnostics
- func (l *Loader) LoadConfig(rootDir string) (*configs.Config, hcl.Diagnostics)
- func (l *Loader) Parser() *configs.Parser
- func (l *Loader) Sources() map[string][]byte
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.
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 ¶
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 ¶
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 ¶
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 ¶
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.
Source Files