cliconfig

Documentation

Overview

Package cliconfig has the types representing and the logic to load CLI-level configuration settings.

The CLI config is a small collection of settings that a user can override via some files in their home directory or, in some cases, via environment variables. The CLI config is not the same thing as a Terraform configuration written in the Terraform language; the logic for those lives in the top-level directory "configs".

Index

• func ConfigDir() (string, error)
• func ConfigFile() (string, error)
• type Config
  • func EnvConfig() *Config
  • func LoadConfig() (*Config, tfdiags.Diagnostics)
  • func (c *Config) CredentialsSource(helperPlugins pluginDiscovery.PluginMetaSet) (*CredentialsSource, error)
  • func (c1 *Config) Merge(c2 *Config) *Config
  • func (c *Config) Validate() tfdiags.Diagnostics
• type ConfigCredentialsHelper
• type ConfigHost
• type CredentialsLocation
• type CredentialsSource
  • func EmptyCredentialsSourceForTests(credentialsFilePath string) *CredentialsSource
  • func (s *CredentialsSource) CredentialsFilePath() (string, error)
  • func (s *CredentialsSource) CredentialsHelperType() string
  • func (s *CredentialsSource) ForHost(host svchost.Hostname) (svcauth.HostCredentials, error)
  • func (s *CredentialsSource) ForgetForHost(host svchost.Hostname) error
  • func (s *CredentialsSource) HostCredentialsLocation(host svchost.Hostname) CredentialsLocation
  • func (s *CredentialsSource) StoreForHost(host svchost.Hostname, credentials svcauth.HostCredentialsWritable) error
• type ErrUnwritableHostCredentials
  • func (err ErrUnwritableHostCredentials) Error() string
  • func (err ErrUnwritableHostCredentials) Hostname() svchost.Hostname
• type ProviderInstallation
• type ProviderInstallationFilesystemMirror
  • func (i ProviderInstallationFilesystemMirror) GoString() string
• type ProviderInstallationLocation
• type ProviderInstallationMethod
• type ProviderInstallationNetworkMirror
  • func (i ProviderInstallationNetworkMirror) GoString() string

Functions

func ConfigDir

func ConfigDir() (string, error)

ConfigDir returns the configuration directory for Terraform.

func ConfigFile

func ConfigFile() (string, error)

ConfigFile returns the default path to the configuration file.

On Unix-like systems this is the ".terraformrc" file in the home directory. On Windows, this is the "terraform.rc" file in the application data directory.

Types

type Config

type Config struct {
	Providers    map[string]string
	Provisioners map[string]string

	DisableCheckpoint          bool `hcl:"disable_checkpoint"`
	DisableCheckpointSignature bool `hcl:"disable_checkpoint_signature"`

	// If set, enables local caching of plugins in this directory to
	// avoid repeatedly re-downloading over the Internet.
	PluginCacheDir string `hcl:"plugin_cache_dir"`

	Hosts map[string]*ConfigHost `hcl:"host"`

	Credentials        map[string]map[string]interface{}   `hcl:"credentials"`
	CredentialsHelpers map[string]*ConfigCredentialsHelper `hcl:"credentials_helper"`

	// ProviderInstallation represents any provider_installation blocks
	// in the configuration. Only one of these is allowed across the whole
	// configuration, but we decode into a slice here so that we can handle
	// that validation at validation time rather than initial decode time.
	ProviderInstallation []*ProviderInstallation
}

Config is the structure of the configuration for the Terraform CLI.

This is not the configuration for Terraform itself. That is in the "config" package.

var BuiltinConfig Config

BuiltinConfig is the built-in defaults for the configuration. These can be overridden by user configurations.

func EnvConfig

func EnvConfig() *Config

EnvConfig returns a Config populated from environment variables.

Any values specified in this config should override those set in the configuration file.

func LoadConfig

func LoadConfig() (*Config, tfdiags.Diagnostics)

LoadConfig reads the CLI configuration from the various filesystem locations and from the environment, returning a merged configuration along with any diagnostics (errors and warnings) encountered along the way.

func (*Config) CredentialsSource

func (c *Config) CredentialsSource(helperPlugins pluginDiscovery.PluginMetaSet) (*CredentialsSource, error)

CredentialsSource creates and returns a service credentials source whose behavior depends on which "credentials" and "credentials_helper" blocks, if any, are present in the receiving config.

func (*Config) Merge

func (c1 *Config) Merge(c2 *Config) *Config

Merge merges two configurations and returns a third entirely new configuration with the two merged.

func (*Config) Validate

func (c *Config) Validate() tfdiags.Diagnostics

Validate checks for errors in the configuration that cannot be detected just by HCL decoding, returning any problems as diagnostics.

On success, the returned diagnostics will return false from the HasErrors method. A non-nil diagnostics is not necessarily an error, since it may contain just warnings.

type ConfigCredentialsHelper

type ConfigCredentialsHelper struct {
	Args []string `hcl:"args"`
}

ConfigCredentialsHelper is the structure of the "credentials_helper" nested block within the CLI configuration.

type ConfigHost

type ConfigHost struct {
	Services map[string]interface{} `hcl:"services"`
}

ConfigHost is the structure of the "host" nested block within the CLI configuration, which can be used to override the default service host discovery behavior for a particular hostname.

type CredentialsLocation

type CredentialsLocation rune

CredentialsLocation describes a type of storage used for the credentials for a particular hostname.

const (
	// CredentialsNotAvailable means that we know that there are no credential
	// available for the host.
	//
	// Note that CredentialsViaHelper might also lead to no credentials being
	// available, depending on how the helper answers when we request credentials
	// from it.
	CredentialsNotAvailable CredentialsLocation = 0

	// CredentialsInPrimaryFile means that there is already a credentials object
	// for the host in the credentials.tfrc.json file.
	CredentialsInPrimaryFile CredentialsLocation = 'P'

	// CredentialsInOtherFile means that there is already a credentials object
	// for the host in a CLI config file other than credentials.tfrc.json.
	CredentialsInOtherFile CredentialsLocation = 'O'

	// CredentialsViaHelper indicates that no statically-configured credentials
	// are available for the host but a helper program is available that may
	// or may not have credentials for the host.
	CredentialsViaHelper CredentialsLocation = 'H'
)

type CredentialsSource

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

CredentialsSource is an implementation of svcauth.CredentialsSource that can read and write the CLI configuration, and possibly also delegate to a credentials helper when configured.

func EmptyCredentialsSourceForTests

func EmptyCredentialsSourceForTests(credentialsFilePath string) *CredentialsSource

EmptyCredentialsSourceForTests constructs a CredentialsSource with no credentials pre-loaded and which writes new credentials to a file at the given path.

As the name suggests, this function is here only for testing and should not be used in normal application code.

func (*CredentialsSource) CredentialsFilePath

func (s *CredentialsSource) CredentialsFilePath() (string, error)

CredentialsFilePath returns the full path to the local credentials configuration file, so that a caller can mention this path in order to be transparent about where credentials will be stored.

This file will be used for writes only if HostCredentialsLocation for the relevant host returns CredentialsInPrimaryFile or CredentialsNotAvailable.

The credentials file path is found relative to the current user's home directory, so this function will return an error in the unlikely event that we cannot determine a suitable home directory to resolve relative to.

func (*CredentialsSource) CredentialsHelperType

func (s *CredentialsSource) CredentialsHelperType() string

CredentialsHelperType returns the name of the configured credentials helper type, or an empty string if no credentials helper is configured.

func (*CredentialsSource) ForHost

func (s *CredentialsSource) ForHost(host svchost.Hostname) (svcauth.HostCredentials, error)

func (*CredentialsSource) ForgetForHost

func (s *CredentialsSource) ForgetForHost(host svchost.Hostname) error

func (*CredentialsSource) HostCredentialsLocation

func (s *CredentialsSource) HostCredentialsLocation(host svchost.Hostname) CredentialsLocation

HostCredentialsLocation returns a value indicating what type of storage is currently used for the credentials for the given hostname.

The current location of credentials determines whether updates are possible at all and, if they are, where any updates will be written.

func (*CredentialsSource) StoreForHost

func (s *CredentialsSource) StoreForHost(host svchost.Hostname, credentials svcauth.HostCredentialsWritable) error

type ErrUnwritableHostCredentials

type ErrUnwritableHostCredentials svchost.Hostname

ErrUnwritableHostCredentials is an error type that is returned when a caller tries to write credentials for a host that has existing credentials configured in a file that we cannot automatically update.

func (ErrUnwritableHostCredentials) Error

func (err ErrUnwritableHostCredentials) Error() string

func (ErrUnwritableHostCredentials) Hostname

func (err ErrUnwritableHostCredentials) Hostname() svchost.Hostname

Hostname returns the host that could not be written.

type ProviderInstallation

type ProviderInstallation struct {
	Methods []*ProviderInstallationMethod
}

ProviderInstallation is the structure of the "provider_installation" nested block within the CLI configuration.

type ProviderInstallationFilesystemMirror

type ProviderInstallationFilesystemMirror string

ProviderInstallationFilesystemMirror is a ProviderInstallationSourceLocation representing installation from a particular local filesystem mirror. The string value is the filesystem path to the mirror directory.

func (ProviderInstallationFilesystemMirror) GoString

func (i ProviderInstallationFilesystemMirror) GoString() string

type ProviderInstallationLocation

type ProviderInstallationLocation interface {
	// contains filtered or unexported methods
}

ProviderInstallationLocation is an interface type representing the different installation location types. The concrete implementations of this interface are:

ProviderInstallationDirect:                install from the provider's origin registry
ProviderInstallationFilesystemMirror(dir): install from a local filesystem mirror
ProviderInstallationNetworkMirror(host):   install from a network mirror

var ProviderInstallationDirect ProviderInstallationLocation = providerInstallationDirect{}

ProviderInstallationDirect is a ProviderInstallationSourceLocation representing installation from a provider's origin registry.

type ProviderInstallationMethod

type ProviderInstallationMethod struct {
	Location ProviderInstallationLocation
	Include  []string `hcl:"include"`
	Exclude  []string `hcl:"exclude"`
}

ProviderInstallationMethod represents an installation method block inside a provider_installation block.

type ProviderInstallationNetworkMirror

type ProviderInstallationNetworkMirror string

ProviderInstallationNetworkMirror is a ProviderInstallationSourceLocation representing installation from a particular local network mirror. The string value is the HTTP base URL exactly as written in the configuration, without any normalization.

func (ProviderInstallationNetworkMirror) GoString

func (i ProviderInstallationNetworkMirror) GoString() string