terraform: github.com/hashicorp/terraform/config Index | Files

package config

import "github.com/hashicorp/terraform/config"

The config package is responsible for loading and validating the configuration.

Index

Package Files

append.go config.go config_string.go config_terraform.go config_tree.go import_tree.go interpolate.go interpolate_funcs.go interpolate_walk.go lang.go loader.go loader_hcl.go loader_hcl2.go merge.go providers.go provisioner_enums.go raw_config.go resource_mode.go resource_mode_string.go testing.go

Variables

var NameRegexp = regexp.MustCompile(`(?i)\A[A-Z0-9_][A-Z0-9\-\_]*\z`)

NameRegexp is the regular expression that all names (modules, providers, resources, etc.) must follow.

var ReservedDataSourceFields = []string{
    "connection",
    "count",
    "depends_on",
    "lifecycle",
    "provider",
    "provisioner",
}
var ReservedProviderFields = []string{
    "alias",
    "version",
}
var ReservedResourceFields = []string{
    "connection",
    "count",
    "depends_on",
    "id",
    "lifecycle",
    "provider",
    "provisioner",
}

func Funcs Uses

func Funcs() map[string]ast.Function

Funcs used to return a mapping of built-in functions for configuration.

However, these function implementations are no longer used. To find the current function implementations, refer to ../lang/functions.go instead.

func IsIgnoredFile Uses

func IsIgnoredFile(name string) bool

IsIgnoredFile returns true or false depending on whether the provided file name is a file that should be ignored.

func ProviderConfigName Uses

func ProviderConfigName(t string, pcs []*ProviderConfig) string

ProviderConfigName returns the name of the provider configuration in the given mapping that maps to the proper provider configuration for this resource.

type AtlasConfig Uses

type AtlasConfig struct {
    Name    string
    Include []string
    Exclude []string
}

AtlasConfig is the configuration for building in HashiCorp's Atlas.

type Backend Uses

type Backend struct {
    Type      string
    RawConfig *RawConfig

    // Hash is a unique hash code representing the original configuration
    // of the backend. This won't be recomputed unless Rehash is called.
    Hash uint64
}

Backend is the configuration for the "backend" to use with Terraform. A backend is responsible for all major behavior of Terraform's core. The abstraction layer above the core (the "backend") allows for behavior such as remote operation.

func (*Backend) Rehash Uses

func (b *Backend) Rehash() uint64

Rehash returns a unique content hash for this backend's configuration as a uint64 value.

func (*Backend) Validate Uses

func (b *Backend) Validate() []error

type Config Uses

type Config struct {
    // Dir is the path to the directory where this configuration was
    // loaded from. If it is blank, this configuration wasn't loaded from
    // any meaningful directory.
    Dir string

    Terraform       *Terraform
    Atlas           *AtlasConfig
    Modules         []*Module
    ProviderConfigs []*ProviderConfig
    Resources       []*Resource
    Variables       []*Variable
    Locals          []*Local
    Outputs         []*Output
    // contains filtered or unexported fields
}

Config is the configuration that comes from loading a collection of Terraform templates.

func Append Uses

func Append(c1, c2 *Config) (*Config, error)

Append appends one configuration to another.

Append assumes that both configurations will not have conflicting variables, resources, etc. If they do, the problems will be caught in the validation phase.

It is possible that c1, c2 on their own are not valid. For example, a resource in c2 may reference a variable in c1. But together, they would be valid.

func LoadDir Uses

func LoadDir(root string) (*Config, error)

LoadDir loads all the Terraform configuration files in a single directory and appends them together.

Special files known as "override files" can also be present, which are merged into the loaded configuration. That is, the non-override files are loaded first to create the configuration. Then, the overrides are merged into the configuration to create the final configuration.

Files are loaded in lexical order.

func LoadFile Uses

func LoadFile(path string) (*Config, error)

LoadFile loads the Terraform configuration from a given file.

This file can be any format that Terraform recognizes, and import any other format that Terraform recognizes.

func LoadJSON Uses

func LoadJSON(raw json.RawMessage) (*Config, error)

LoadJSON loads a single Terraform configuration from a given JSON document.

The document must be a complete Terraform configuration. This function will NOT try to load any additional modules so only the given document is loaded.

func Merge Uses

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

Merge merges two configurations into a single configuration.

Merge allows for the two configurations to have duplicate resources, because the resources will be merged. This differs from a single Config which must only have unique resources.

func (*Config) InterpolatedVariables Uses

func (c *Config) InterpolatedVariables() map[string][]InterpolatedVariable

InterpolatedVariables is a helper that returns a mapping of all the interpolated variables within the configuration. This is used to verify references are valid in the Validate step.

func (*Config) ProviderConfigsByFullName Uses

func (c *Config) ProviderConfigsByFullName() map[string]*ProviderConfig

ProviderConfigsByFullName returns a map from provider full names (as returned by ProviderConfig.FullName()) to the corresponding provider configs.

This function returns no new information than what's already in c.ProviderConfigs, but returns it in a more convenient shape. If there is more than one provider config with the same full name then the result is undefined, but that is guaranteed not to happen for any config that has passed validation.

func (*Config) TestString Uses

func (c *Config) TestString() string

TestString is a Stringer-like function that outputs a string that can be used to easily compare multiple Config structures in unit tests.

This function has no practical use outside of unit tests and debugging.

func (*Config) Validate Uses

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

Validate does some basic semantic checking of the configuration.

type CountValueType Uses

type CountValueType byte

CountValueType is the type of the count variable that is referenced.

const (
    CountValueInvalid CountValueType = iota
    CountValueIndex
)

type CountVariable Uses

type CountVariable struct {
    Type CountValueType
    // contains filtered or unexported fields
}

CountVariable is a variable for referencing information about the count.

func NewCountVariable Uses

func NewCountVariable(key string) (*CountVariable, error)

func (*CountVariable) FullKey Uses

func (c *CountVariable) FullKey() string

func (CountVariable) SourceRange Uses

func (r CountVariable) SourceRange() tfdiags.SourceRange

type ErrNoConfigsFound Uses

type ErrNoConfigsFound struct {
    Dir string
}

ErrNoConfigsFound is the error returned by LoadDir if no Terraform configuration files were found in the given directory.

func (ErrNoConfigsFound) Error Uses

func (e ErrNoConfigsFound) Error() string

type InterpolatedVariable Uses

type InterpolatedVariable interface {
    FullKey() string
    SourceRange() tfdiags.SourceRange
}

An InterpolatedVariable is a variable reference within an interpolation.

Implementations of this interface represents various sources where variables can come from: user variables, resources, etc.

func DetectVariables Uses

func DetectVariables(root ast.Node) ([]InterpolatedVariable, error)

DetectVariables takes an AST root and returns all the interpolated variables that are detected in the AST tree.

func NewInterpolatedVariable Uses

func NewInterpolatedVariable(v string) (InterpolatedVariable, error)

type Local Uses

type Local struct {
    Name      string
    RawConfig *RawConfig
}

Local is a local value defined within the configuration.

type LocalVariable Uses

type LocalVariable struct {
    Name string
    // contains filtered or unexported fields
}

A LocalVariable is a variable that references a local value defined within the current module, via a "locals" block. This looks like "${local.foo}".

func NewLocalVariable Uses

func NewLocalVariable(key string) (*LocalVariable, error)

func (*LocalVariable) FullKey Uses

func (v *LocalVariable) FullKey() string

func (*LocalVariable) GoString Uses

func (v *LocalVariable) GoString() string

func (LocalVariable) SourceRange Uses

func (r LocalVariable) SourceRange() tfdiags.SourceRange

type Module Uses

type Module struct {
    Name      string
    Source    string
    Version   string
    Providers map[string]string
    RawConfig *RawConfig
}

Module is a module used within a configuration.

This does not represent a module itself, this represents a module call-site within an existing configuration.

func (*Module) Id Uses

func (r *Module) Id() string

A unique identifier for this module.

type ModuleVariable Uses

type ModuleVariable struct {
    Name  string
    Field string
    // contains filtered or unexported fields
}

A ModuleVariable is a variable that is referencing the output of a module, such as "${module.foo.bar}"

func NewModuleVariable Uses

func NewModuleVariable(key string) (*ModuleVariable, error)

func (*ModuleVariable) FullKey Uses

func (v *ModuleVariable) FullKey() string

func (*ModuleVariable) GoString Uses

func (v *ModuleVariable) GoString() string

func (ModuleVariable) SourceRange Uses

func (r ModuleVariable) SourceRange() tfdiags.SourceRange

type Output Uses

type Output struct {
    Name        string
    DependsOn   []string
    Description string
    Sensitive   bool
    RawConfig   *RawConfig
}

Output is an output defined within the configuration. An output is resulting data that is highlighted by Terraform when finished. An output marked Sensitive will be output in a masked form following application, but will still be available in state.

type PathValueType Uses

type PathValueType byte
const (
    PathValueInvalid PathValueType = iota
    PathValueCwd
    PathValueModule
    PathValueRoot
)

type PathVariable Uses

type PathVariable struct {
    Type PathValueType
    // contains filtered or unexported fields
}

A PathVariable is a variable that references path information about the module.

func NewPathVariable Uses

func NewPathVariable(key string) (*PathVariable, error)

func (*PathVariable) FullKey Uses

func (v *PathVariable) FullKey() string

func (PathVariable) SourceRange Uses

func (r PathVariable) SourceRange() tfdiags.SourceRange

type ProviderConfig Uses

type ProviderConfig struct {
    Name      string
    Alias     string
    Version   string
    RawConfig *RawConfig
}

ProviderConfig is the configuration for a resource provider.

For example, Terraform needs to set the AWS access keys for the AWS resource provider.

func (*ProviderConfig) FullName Uses

func (c *ProviderConfig) FullName() string

func (*ProviderConfig) GoString Uses

func (c *ProviderConfig) GoString() string

type ProviderVersionConstraint Uses

type ProviderVersionConstraint struct {
    Constraint   string
    ProviderType string
}

ProviderVersionConstraint presents a constraint for a particular provider, identified by its full name.

type ProviderVersionConstraints Uses

type ProviderVersionConstraints map[string]ProviderVersionConstraint

ProviderVersionConstraints is a map from provider full name to its associated ProviderVersionConstraint, as produced by Config.RequiredProviders.

func (ProviderVersionConstraints) RequiredRanges Uses

func (cons ProviderVersionConstraints) RequiredRanges() map[string]semver.Range

RequiredRanges returns a semver.Range for each distinct provider type in the constraint map. If the same provider type appears more than once (e.g. because aliases are in use) then their respective constraints are combined such that they must *all* apply.

The result of this method can be passed to the PluginMetaSet.ConstrainVersions method within the plugin/discovery package in order to filter down the available plugins to those which satisfy the given constraints.

This function will panic if any of the constraints within cannot be parsed as semver ranges. This is guaranteed to never happen for a constraint set that was built from a configuration that passed validation.

type Provisioner Uses

type Provisioner struct {
    Type      string
    RawConfig *RawConfig
    ConnInfo  *RawConfig

    When      ProvisionerWhen
    OnFailure ProvisionerOnFailure
}

Provisioner is a configured provisioner step on a resource.

func (*Provisioner) Copy Uses

func (p *Provisioner) Copy() *Provisioner

Copy returns a copy of this Provisioner

type ProvisionerOnFailure Uses

type ProvisionerOnFailure int

ProvisionerOnFailure is an enum for valid values for on_failure options for provisioners.

const (
    ProvisionerOnFailureInvalid ProvisionerOnFailure = iota
    ProvisionerOnFailureContinue
    ProvisionerOnFailureFail
)

func (ProvisionerOnFailure) String Uses

func (v ProvisionerOnFailure) String() string

type ProvisionerWhen Uses

type ProvisionerWhen int

ProvisionerWhen is an enum for valid values for when to run provisioners.

const (
    ProvisionerWhenInvalid ProvisionerWhen = iota
    ProvisionerWhenCreate
    ProvisionerWhenDestroy
)

func (ProvisionerWhen) String Uses

func (v ProvisionerWhen) String() string

type RawConfig Uses

type RawConfig struct {
    Key string

    Raw  map[string]interface{}
    Body hcl2.Body

    Interpolations []ast.Node
    Variables      map[string]InterpolatedVariable
    // contains filtered or unexported fields
}

RawConfig is a structure that holds a piece of configuration where the overall structure is unknown since it will be used to configure a plugin or some other similar external component.

RawConfigs can be interpolated with variables that come from other resources, user variables, etc.

RawConfig supports a query-like interface to request information from deep within the structure.

func NewRawConfig Uses

func NewRawConfig(raw map[string]interface{}) (*RawConfig, error)

NewRawConfig creates a new RawConfig structure and populates the publicly readable struct fields.

func NewRawConfigHCL2 Uses

func NewRawConfigHCL2(body hcl2.Body) *RawConfig

NewRawConfigHCL2 creates a new RawConfig that is serving as a capsule to transport a hcl2.Body. In this mode, the publicly-readable struct fields are not populated since all operations should instead be diverted to the HCL2 body.

For a RawConfig object constructed with this function, the only valid use is to later retrieve the Body value and call its own methods. Callers may choose to set and then later handle the Key field, in a manner consistent with how it is handled by the Value method, but the Value method itself must not be used.

This is an experimental codepath to be used only by the HCL2 config loader. Non-experimental parsing should _always_ use NewRawConfig to produce a fully-functional RawConfig object.

func TestRawConfig Uses

func TestRawConfig(t *testing.T, c map[string]interface{}) *RawConfig

TestRawConfig is used to create a RawConfig for testing.

func (*RawConfig) Config Uses

func (r *RawConfig) Config() map[string]interface{}

Config returns the entire configuration with the variables interpolated from any call to Interpolate.

If any interpolated variables are unknown (value set to UnknownVariableValue), the first non-container (map, slice, etc.) element will be removed from the config. The keys of unknown variables can be found using the UnknownKeys function.

By pruning out unknown keys from the configuration, the raw structure will always successfully decode into its ultimate structure using something like mapstructure.

func (*RawConfig) Copy Uses

func (r *RawConfig) Copy() *RawConfig

Copy returns a copy of this RawConfig, uninterpolated.

func (*RawConfig) GobDecode Uses

func (r *RawConfig) GobDecode(b []byte) error

See GobEncode

func (*RawConfig) GobEncode Uses

func (r *RawConfig) GobEncode() ([]byte, error)

GobEncode is a custom Gob encoder to use so that we only include the raw configuration. Interpolated variables and such are lost and the tree of interpolated variables is recomputed on decode, since it is referentially transparent.

func (*RawConfig) Interpolate Uses

func (r *RawConfig) Interpolate(vs map[string]ast.Variable) error

Interpolate uses the given mapping of variable values and uses those as the values to replace any variables in this raw configuration.

Any prior calls to Interpolate are replaced with this one.

If a variable key is missing, this will panic.

func (*RawConfig) Merge Uses

func (r *RawConfig) Merge(other *RawConfig) *RawConfig

Merge merges another RawConfig into this one (overriding any conflicting values in this config) and returns a new config. The original config is not modified.

func (*RawConfig) RawMap Uses

func (r *RawConfig) RawMap() map[string]interface{}

RawMap returns a copy of the RawConfig.Raw map.

func (*RawConfig) UnknownKeys Uses

func (r *RawConfig) UnknownKeys() []string

UnknownKeys returns the keys of the configuration that are unknown because they had interpolated variables that must be computed.

func (*RawConfig) Value Uses

func (r *RawConfig) Value() interface{}

Value returns the value of the configuration if this configuration has a Key set. If this does not have a Key set, nil will be returned.

type Resource Uses

type Resource struct {
    Mode         ResourceMode // which operations the resource supports
    Name         string
    Type         string
    RawCount     *RawConfig
    RawConfig    *RawConfig
    Provisioners []*Provisioner
    Provider     string
    DependsOn    []string
    Lifecycle    ResourceLifecycle
}

A resource represents a single Terraform resource in the configuration. A Terraform resource is something that supports some or all of the usual "create, read, update, delete" operations, depending on the given Mode.

func (*Resource) Copy Uses

func (r *Resource) Copy() *Resource

Copy returns a copy of this Resource. Helpful for avoiding shared config pointers across multiple pieces of the graph that need to do interpolation.

func (*Resource) Count Uses

func (r *Resource) Count() (int, error)

Count returns the count of this resource.

func (*Resource) Id Uses

func (r *Resource) Id() string

A unique identifier for this resource.

type ResourceLifecycle Uses

type ResourceLifecycle struct {
    CreateBeforeDestroy bool     `mapstructure:"create_before_destroy"`
    PreventDestroy      bool     `mapstructure:"prevent_destroy"`
    IgnoreChanges       []string `mapstructure:"ignore_changes"`
}

ResourceLifecycle is used to store the lifecycle tuning parameters to allow customized behavior

func (*ResourceLifecycle) Copy Uses

func (r *ResourceLifecycle) Copy() *ResourceLifecycle

Copy returns a copy of this ResourceLifecycle

type ResourceMode Uses

type ResourceMode int

go:generate go run golang.org/x/tools/cmd/stringer -type=ResourceMode -output=resource_mode_string.go resource_mode.go

const (
    ManagedResourceMode ResourceMode = iota
    DataResourceMode
)

func (ResourceMode) String Uses

func (i ResourceMode) String() string

func (ResourceMode) Taintable Uses

func (m ResourceMode) Taintable() bool

type ResourceVariable Uses

type ResourceVariable struct {
    Mode  ResourceMode
    Type  string // Resource type, i.e. "aws_instance"
    Name  string // Resource name
    Field string // Resource field

    Multi bool // True if multi-variable: aws_instance.foo.*.id
    Index int  // Index for multi-variable: aws_instance.foo.1.id == 1
    // contains filtered or unexported fields
}

A ResourceVariable is a variable that is referencing the field of a resource, such as "${aws_instance.foo.ami}"

func NewResourceVariable Uses

func NewResourceVariable(key string) (*ResourceVariable, error)

func (*ResourceVariable) FullKey Uses

func (v *ResourceVariable) FullKey() string

func (*ResourceVariable) ResourceId Uses

func (v *ResourceVariable) ResourceId() string

func (ResourceVariable) SourceRange Uses

func (r ResourceVariable) SourceRange() tfdiags.SourceRange

type SelfVariable Uses

type SelfVariable struct {
    Field string
    // contains filtered or unexported fields
}

SelfVariable is a variable that is referencing the same resource it is running on: "${self.address}"

func NewSelfVariable Uses

func NewSelfVariable(key string) (*SelfVariable, error)

func (*SelfVariable) FullKey Uses

func (v *SelfVariable) FullKey() string

func (*SelfVariable) GoString Uses

func (v *SelfVariable) GoString() string

func (SelfVariable) SourceRange Uses

func (r SelfVariable) SourceRange() tfdiags.SourceRange

type SimpleVariable Uses

type SimpleVariable struct {
    Key string
    // contains filtered or unexported fields
}

SimpleVariable is an unprefixed variable, which can show up when users have strings they are passing down to resources that use interpolation internally. The template_file resource is an example of this.

func NewSimpleVariable Uses

func NewSimpleVariable(key string) (*SimpleVariable, error)

func (*SimpleVariable) FullKey Uses

func (v *SimpleVariable) FullKey() string

func (*SimpleVariable) GoString Uses

func (v *SimpleVariable) GoString() string

func (SimpleVariable) SourceRange Uses

func (r SimpleVariable) SourceRange() tfdiags.SourceRange

type Terraform Uses

type Terraform struct {
    RequiredVersion string   `hcl:"required_version"` // Required Terraform version (constraint)
    Backend         *Backend // See Backend struct docs
}

Terraform is the Terraform meta-configuration that can be present in configuration files for configuring Terraform itself.

func (*Terraform) Merge Uses

func (t *Terraform) Merge(t2 *Terraform)

Merge t with t2. Any conflicting fields are overwritten by t2.

func (*Terraform) Validate Uses

func (t *Terraform) Validate() []error

Validate performs the validation for just the Terraform configuration.

type TerraformVariable Uses

type TerraformVariable struct {
    Field string
    // contains filtered or unexported fields
}

TerraformVariable is a "terraform."-prefixed variable used to access metadata about the Terraform run.

func NewTerraformVariable Uses

func NewTerraformVariable(key string) (*TerraformVariable, error)

func (*TerraformVariable) FullKey Uses

func (v *TerraformVariable) FullKey() string

func (*TerraformVariable) GoString Uses

func (v *TerraformVariable) GoString() string

func (TerraformVariable) SourceRange Uses

func (r TerraformVariable) SourceRange() tfdiags.SourceRange

type UserVariable Uses

type UserVariable struct {
    Name string
    Elem string
    // contains filtered or unexported fields
}

A UserVariable is a variable that is referencing a user variable that is inputted from outside the configuration. This looks like "${var.foo}"

func NewUserVariable Uses

func NewUserVariable(key string) (*UserVariable, error)

func (*UserVariable) FullKey Uses

func (v *UserVariable) FullKey() string

func (*UserVariable) GoString Uses

func (v *UserVariable) GoString() string

func (UserVariable) SourceRange Uses

func (r UserVariable) SourceRange() tfdiags.SourceRange

type Variable Uses

type Variable struct {
    Name         string
    DeclaredType string `mapstructure:"type"`
    Default      interface{}
    Description  string
}

Variable is a module argument defined within the configuration.

func (*Variable) Merge Uses

func (v *Variable) Merge(v2 *Variable) *Variable

Merge merges two variables to create a new third variable.

func (*Variable) Required Uses

func (v *Variable) Required() bool

Required tests whether a variable is required or not.

func (*Variable) Type Uses

func (v *Variable) Type() VariableType

Type returns the type of variable this is.

func (*Variable) ValidateTypeAndDefault Uses

func (v *Variable) ValidateTypeAndDefault() error

ValidateTypeAndDefault ensures that default variable value is compatible with the declared type (if one exists), and that the type is one which is known to Terraform

type VariableType Uses

type VariableType byte

VariableType is the type of value a variable is holding, and returned by the Type() function on variables.

const (
    VariableTypeUnknown VariableType = iota
    VariableTypeString
    VariableTypeList
    VariableTypeMap
)

func (VariableType) Printable Uses

func (v VariableType) Printable() string

Package config imports 37 packages (graph) and is imported by 579 packages. Updated 2019-10-30. Refresh now. Tools for package owners.