Locals

README.md

@@ -1205,6 +1205,7 @@ at all.
 This section contains detailed documentation for the following aspects of Terragrunt:
 
 1. [Inputs](#inputs)
+1. [Locals](#locals)
 1. [AWS credentials](#aws-credentials)
 1. [AWS IAM policies](#aws-iam-policies)
 1. [Built-in Functions](#built-in-functions)
@@ -1228,7 +1229,7 @@ You can set values for your module's input parameters by specifying an `inputs`
 inputs = {
   instance_type  = "t2.micro"
   instance_count = 10
-  
+
   tags = {
     Name = "example-app"
   }
@@ -1253,6 +1254,79 @@ Note that Terragrunt will respect any `TF_VAR_xxx` variables you've manually set
 anything in `inputs` will NOT be override anything you've already set in your environment.  
 
 
+### Locals
+
+You can use locals to bind a name to an expression, so you can reuse that expression without having to repeat it multiple times (keeping your Terragrunt configuration DRY).
+config. For example, suppose that you need to use the AWS region in multiple inputs. You can bind the name `aws_region`
+using locals:
+
+```
+locals {
+  aws_region = "us-east-1"
+}
+
+inputs = {
+  aws_region  = local.aws_region
+  s3_endpoint = "com.amazonaws.${local.aws_region}.s3"
+}
+```
+
+You can use any valid terragrunt expression in the `locals` configuration. The `locals` block also supports referencing other `locals`:
+
+```
+locals {
+  x = 2
+  y = 40
+  answer = local.x + local.y
+}
+```
+
+##### Including globally defined locals
+
+Currently you can only reference `locals` defined in the same config file. `terragrunt` does not automatically include
+`locals` defined in the parent config of an `include` block into the current context. If you wish to reuse variables
+globally, consider using `yaml` or `json` files that are included and merged using the `terraform` built in functions
+available to `terragrunt`.
+
+For example, suppose you had the following directory tree:
+
+```
+.
+├── terragrunt.hcl
+├── mysql
+│   └── terragrunt.hcl
+└── vpc
+    └── terragrunt.hcl
+```
+
+Instead of adding the `locals` block to the parent `terragrunt.hcl` file, you can define a file `common_vars.yaml`
+that contains the global variables you wish to pull in:
+
+```
+.
+├── terragrunt.hcl
+├── common_vars.yaml
+├── mysql
+│   └── terragrunt.hcl
+└── vpc
+    └── terragrunt.hcl
+```
+
+You can then include them into the `locals` block of the child terragrunt config using `yamldecode` and `file`:
+
+```
+# child terragrunt.hcl
+locals {
+  common_vars = yamldecode(file("${get_terragrunt_dir()}/${find_in_parent_folders("common_vars.yaml")}")),
+  region = "us-east-1"
+}
+```
+
+This configuration will load in the `common_vars.yaml` file and bind it to the attribute `common_vars` so that it is available
+in the current context. Note that because `locals` is a block, there currently is a way to merge the map into the top
+level.
+
+
 ### AWS credentials
 
 Terragrunt uses the official [AWS SDK for Go](https://aws.amazon.com/sdk-for-go/), which

cli/hclfmt.go

@@ -4,11 +4,9 @@ import (
 	"io/ioutil"
 	"os"
 
-	"github.com/hashicorp/hcl2/hcl"
 	"github.com/hashicorp/hcl2/hclparse"
 	"github.com/hashicorp/hcl2/hclwrite"
 	"github.com/mattn/go-zglob"
-	"golang.org/x/crypto/ssh/terminal"
 
 	"github.com/gruntwork-io/terragrunt/options"
 	"github.com/gruntwork-io/terragrunt/util"
@@ -65,21 +63,11 @@ func formatTgHCL(terragruntOptions *options.TerragruntOptions, tgHclFile string)
 	return ioutil.WriteFile(tgHclFile, newContents, info.Mode())
 }
 
-// getDiagnosticsWriter returns a hcl2 parsing diagnostics emitter for the current terminal.
-func getDiagnosticsWriter(parser *hclparse.Parser) hcl.DiagnosticWriter {
-	termColor := terminal.IsTerminal(int(os.Stderr.Fd()))
-	termWidth, _, err := terminal.GetSize(int(os.Stdout.Fd()))
-	if err != nil {
-		termWidth = 80
-	}
-	return hcl.NewDiagnosticTextWriter(os.Stderr, parser.Files(), uint(termWidth), termColor)
-}
-
 // checkErrors takes in the contents of a terragrunt.hcl file and looks for syntax errors.
 func checkErrors(contents []byte, tgHclFile string) error {
 	parser := hclparse.NewParser()
 	_, diags := parser.ParseHCL(contents, tgHclFile)
-	diagWriter := getDiagnosticsWriter(parser)
+	diagWriter := util.GetDiagnosticsWriter(parser)
 	diagWriter.WriteDiagnostics(diags)
 	if diags.HasErrors() {
 		return diags

config/config.go

@@ -2,15 +2,16 @@ package config
 
 import (
 	"fmt"
-	"github.com/hashicorp/hcl2/gohcl"
-	"github.com/hashicorp/hcl2/hcl"
-	"github.com/hashicorp/hcl2/hclparse"
-	"github.com/zclconf/go-cty/cty"
 	"os"
 	"path/filepath"
 	"reflect"
 	"strings"
 
+	"github.com/hashicorp/hcl2/gohcl"
+	"github.com/hashicorp/hcl2/hcl"
+	"github.com/hashicorp/hcl2/hclparse"
+	"github.com/zclconf/go-cty/cty"
+
 	"github.com/gruntwork-io/terragrunt/errors"
 	"github.com/gruntwork-io/terragrunt/options"
 	"github.com/gruntwork-io/terragrunt/remote"
@@ -28,6 +29,7 @@ type TerragruntConfig struct {
 	Skip           bool
 	IamRole        string
 	Inputs         map[string]interface{}
+	Locals         map[string]interface{}
 }
 
 func (conf *TerragruntConfig) String() string {
@@ -45,6 +47,17 @@ type terragruntConfigFile struct {
 	PreventDestroy *bool                  `hcl:"prevent_destroy,attr"`
 	Skip           *bool                  `hcl:"skip,attr"`
 	IamRole        *string                `hcl:"iam_role,attr"`
+
+	// This struct is used for validating and parsing the entire terragrunt config. Since locals are evaluated in a
+	// completely separate cycle, it should not be evaluated here. Otherwise, we can't support self referencing other
+	// elements in the same block.
+	Locals *terragruntLocal `hcl:"locals,block"`
+}
+
+// We use a struct designed to not parse the block, as locals are parsed and decoded using a special routine that allows
+// references to the other locals in the same block.
+type terragruntLocal struct {
+	Remain hcl.Body `hcl:",remain"`
 }
 
 type terragruntInclude struct {
@@ -240,13 +253,21 @@ func ParseConfigFile(filename string, terragruntOptions *options.TerragruntOptio
 // Parse the Terragrunt config contained in the given string and merge it with the given include config (if any)
 func ParseConfigString(configString string, terragruntOptions *options.TerragruntOptions, includeFromChild *IncludeConfig, filename string) (*TerragruntConfig, error) {
 	// Parse the HCL string into an AST body that can be decoded multiple times later without having to re-parse
-	file, err := parseHcl(configString, filename)
+	parser := hclparse.NewParser()
+	file, err := parseHcl(parser, configString, filename)
+	if err != nil {
+		return nil, err
+	}
+
+	// Evaluate all the expressions in the locals block separately and generate the variables list to use in the
+	// evaluation context.
+	locals, err := evaluateLocalsBlock(terragruntOptions, parser, file, filename)
 	if err != nil {
 		return nil, err
 	}
 
 	// Decode just the `include` block, and verify that it's allowed here
-	terragruntInclude, err := decodeAsTerragruntInclude(file, filename, terragruntOptions)
+	terragruntInclude, err := decodeAsTerragruntInclude(file, filename, terragruntOptions, locals)
 	if err != nil {
 		return nil, err
 	}
@@ -266,7 +287,7 @@ func ParseConfigString(configString string, terragruntOptions *options.Terragrun
 
 	// Decode the rest of the config, passing in this config's `include` block or the child's `include` block, whichever
 	// is appropriate
-	terragruntConfigFile, err := decodeAsTerragruntConfigFile(file, filename, terragruntOptions, includeForDecode)
+	terragruntConfigFile, err := decodeAsTerragruntConfigFile(file, filename, terragruntOptions, includeForDecode, locals)
 	if err != nil {
 		return nil, err
 	}
@@ -297,26 +318,44 @@ func ParseConfigString(configString string, terragruntOptions *options.Terragrun
 // For consistency, `include` in the call to `decodeHcl` is always assumed to be nil.
 // Either it really is nil (parsing the child config), or it shouldn't be used anyway (the parent config shouldn't have
 // an include block)
-func decodeAsTerragruntInclude(file *hcl.File, filename string, terragruntOptions *options.TerragruntOptions) (*terragruntInclude, error) {
+func decodeAsTerragruntInclude(
+	file *hcl.File,
+	filename string,
+	terragruntOptions *options.TerragruntOptions,
+	locals map[string]cty.Value,
+) (*terragruntInclude, error) {
 	terragruntInclude := terragruntInclude{}
-	err := decodeHcl(file, filename, &terragruntInclude, terragruntOptions, nil)
+	err := decodeHcl(file, filename, &terragruntInclude, terragruntOptions, nil, locals)
 	if err != nil {
 		return nil, err
 	}
 	return &terragruntInclude, nil
 }
 
-func decodeAsTerragruntConfigFile(file *hcl.File, filename string, terragruntOptions *options.TerragruntOptions, include *IncludeConfig) (*terragruntConfigFile, error) {
+func decodeAsTerragruntConfigFile(
+	file *hcl.File,
+	filename string,
+	terragruntOptions *options.TerragruntOptions,
+	include *IncludeConfig,
+	locals map[string]cty.Value,
+) (*terragruntConfigFile, error) {
 	terragruntConfig := terragruntConfigFile{}
-	err := decodeHcl(file, filename, &terragruntConfig, terragruntOptions, include)
+	err := decodeHcl(file, filename, &terragruntConfig, terragruntOptions, include, locals)
 	if err != nil {
 		return nil, err
 	}
 	return &terragruntConfig, nil
 }
 
 // decodeHcl uses the HCL2 parser to decode the parsed HCL into the struct specified by out.
-func decodeHcl(file *hcl.File, filename string, out interface{}, terragruntOptions *options.TerragruntOptions, include *IncludeConfig) (err error) {
+func decodeHcl(
+	file *hcl.File,
+	filename string,
+	out interface{},
+	terragruntOptions *options.TerragruntOptions,
+	include *IncludeConfig,
+	locals map[string]cty.Value,
+) (err error) {
 	// The HCL2 parser and especially cty conversions will panic in many types of errors, so we have to recover from
 	// those panics here and convert them to normal errors
 	defer func() {
@@ -325,7 +364,13 @@ func decodeHcl(file *hcl.File, filename string, out interface{}, terragruntOptio
 		}
 	}()
 
-	evalContext := CreateTerragruntEvalContext(filename, terragruntOptions, include)
+	// Convert locals to a cty object for use in the evaluation context. Otherwise, we can't bind the whole map under
+	// the name `local`.
+	localsAsCty, err := convertLocalsMapToCtyVal(locals)
+	if err != nil {
+		return err
+	}
+	evalContext := CreateTerragruntEvalContext(filename, terragruntOptions, include, localsAsCty)
 
 	decodeDiagnostics := gohcl.DecodeBody(file.Body, evalContext, out)
 	if decodeDiagnostics != nil && decodeDiagnostics.HasErrors() {
@@ -336,7 +381,7 @@ func decodeHcl(file *hcl.File, filename string, out interface{}, terragruntOptio
 }
 
 // parseHcl uses the HCL2 parser to parse the given string into an HCL file body.
-func parseHcl(hcl string, filename string) (file *hcl.File, err error) {
+func parseHcl(parser *hclparse.Parser, hcl string, filename string) (file *hcl.File, err error) {
 	// The HCL2 parser and especially cty conversions will panic in many types of errors, so we have to recover from
 	// those panics here and convert them to normal errors
 	defer func() {
@@ -345,8 +390,6 @@ func parseHcl(hcl string, filename string) (file *hcl.File, err error) {
 		}
 	}()
 
-	parser := hclparse.NewParser()
-
 	file, parseDiagnostics := parser.ParseHCL([]byte(hcl), filename)
 	if parseDiagnostics != nil && parseDiagnostics.HasErrors() {
 		return nil, parseDiagnostics

config/config_helpers.go

@@ -2,17 +2,19 @@ package config
 
 import (
 	"fmt"
-	"github.com/gruntwork-io/terragrunt/shell"
-	"github.com/hashicorp/hcl2/hcl"
-	tflang "github.com/hashicorp/terraform/lang"
-	"github.com/zclconf/go-cty/cty/function"
 	"path/filepath"
 
 	"github.com/aws/aws-sdk-go/aws/credentials/stscreds"
 	"github.com/aws/aws-sdk-go/aws/session"
 	"github.com/aws/aws-sdk-go/service/sts"
+	"github.com/hashicorp/hcl2/hcl"
+	tflang "github.com/hashicorp/terraform/lang"
+	"github.com/zclconf/go-cty/cty"
+	"github.com/zclconf/go-cty/cty/function"
+
 	"github.com/gruntwork-io/terragrunt/errors"
 	"github.com/gruntwork-io/terragrunt/options"
+	"github.com/gruntwork-io/terragrunt/shell"
 	"github.com/gruntwork-io/terragrunt/util"
 )
 
@@ -63,7 +65,12 @@ type EnvVar struct {
 
 // Create an EvalContext for the HCL2 parser. We can define functions and variables in this context that the HCL2 parser
 // will make available to the Terragrunt configuration during parsing.
-func CreateTerragruntEvalContext(filename string, terragruntOptions *options.TerragruntOptions, include *IncludeConfig) *hcl.EvalContext {
+func CreateTerragruntEvalContext(
+	filename string,
+	terragruntOptions *options.TerragruntOptions,
+	include *IncludeConfig,
+	locals *cty.Value,
+) *hcl.EvalContext {
 	tfscope := tflang.Scope{
 		BaseDir: filepath.Dir(filename),
 	}
@@ -91,9 +98,13 @@ func CreateTerragruntEvalContext(filename string, terragruntOptions *options.Ter
 		functions[k] = v
 	}
 
-	return &hcl.EvalContext{
+	ctx := &hcl.EvalContext{
 		Functions: functions,
 	}
+	if locals != nil {
+		ctx.Variables = map[string]cty.Value{"local": *locals}
+	}
+	return ctx
 }
 
 // Return the directory where the Terragrunt configuration file lives

config/config_test.go

@@ -207,6 +207,7 @@ include {
 	opts := options.TerragruntOptions{
 		TerragruntConfigPath: "../test/fixture-parent-folders/terragrunt-in-root/child/sub-child/sub-sub-child/" + DefaultTerragruntConfigPath,
 		NonInteractive:       true,
+		Logger:               util.CreateLogger(""),
 	}
 
 	terragruntConfig, err := ParseConfigString(config, &opts, nil, opts.TerragruntConfigPath)
@@ -852,6 +853,7 @@ terraform {
 		TerragruntConfigPath: "../test/fixture-parent-folders/terragrunt-in-root/child/" + DefaultTerragruntConfigPath,
 		NonInteractive:       true,
 		MaxFoldersToCheck:    5,
+		Logger:               util.CreateLogger(""),
 	}
 
 	terragruntConfig, err := ParseConfigString(config, &opts, nil, DefaultTerragruntConfigPath)