options

package
v0.77.22 Latest Latest
Warning

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

 Go to latest Published: Apr 21, 2025 License: MIT Imports: 25 Imported by: 110

Documentation

Overview

Package options provides a set of options that configure the behavior of the Terragrunt program.

Index

Constants

View Source 
const (
	DefaultMaxFoldersToCheck = 100

	// no limits on parallelism by default (limited by GOPROCS)
	DefaultParallelism = math.MaxInt32

	// TofuDefaultPath command to run tofu
	TofuDefaultPath = "tofu"

	// TerraformDefaultPath just takes terraform from the path
	TerraformDefaultPath = "terraform"

	// Default to naming it `terragrunt_rendered.json` in the terragrunt config directory.
	DefaultJSONOutName = "terragrunt_rendered.json"

	DefaultSignalsFile = "error-signals.json"

	DefaultTFDataDir = ".terraform"

	DefaultIAMAssumeRoleDuration = 3600

	DefaultLogLevel = log.InfoLevel
)
View Source 
const ContextKey ctxKey = iota
View Source 
const DefaultRetryMaxAttempts = 3
View Source 
const DefaultRetrySleepInterval = 5 * time.Second

Variables

View Source 
var (
	DefaultWrappedPath = identifyDefaultWrappedExecutable()

	TerraformCommandsWithSubcommand = []string{
		"debug",
		"force-unlock",
		"state",
	}
)
View Source 
var DefaultRetryableErrors = []string{
	"(?s).*Failed to load state.*tcp.*timeout.*",
	"(?s).*Failed to load backend.*TLS handshake timeout.*",
	"(?s).*Creating metric alarm failed.*request to update this alarm is in progress.*",
	"(?s).*Error installing provider.*TLS handshake timeout.*",
	"(?s).*Error configuring the backend.*TLS handshake timeout.*",
	"(?s).*Error installing provider.*tcp.*timeout.*",
	"(?s).*Error installing provider.*tcp.*connection reset by peer.*",
	"NoSuchBucket: The specified bucket does not exist",
	"(?s).*Error creating SSM parameter: TooManyUpdates:.*",
	"(?s).*app.terraform.io.*: 429 Too Many Requests.*",
	"(?s).*ssh_exchange_identification.*Connection closed by remote host.*",
	"(?s).*Client\\.Timeout exceeded while awaiting headers.*",
	"(?s).*Could not download module.*The requested URL returned error: 429.*",
	"(?s).*net/http: TLS.*handshake timeout.*",
}

DefaultRetryableErrors is a list of errors that are considered transient and should be retried.

It's a list of recurring transient errors encountered when calling terraform If any of these match, we'll retry the command.

View Source 
var ErrRunTerragruntCommandNotSet = errors.New("the RunTerragrunt option has not been set on this TerragruntOptions object")

ErrRunTerragruntCommandNotSet is a custom error type indicating that the command is not set.

Functions

func DefaultWorkingAndDownloadDirs added in v0.16.2 

func DefaultWorkingAndDownloadDirs(terragruntConfigPath string) (string, string, error)

DefaultWorkingAndDownloadDirs gets the default working and download directories for the given Terragrunt config path.

func GetDefaultIAMAssumeRoleSessionName added in v0.35.1 

func GetDefaultIAMAssumeRoleSessionName() string

GetDefaultIAMAssumeRoleSessionName gets the default IAM assume role session name.

Types

type EngineOptions added in v0.62.0 

type EngineOptions struct {
	Meta    map[string]any
	Source  string
	Version string
	Type    string
}

EngineOptions Options for the Terragrunt engine.

type ErrorAction added in v0.69.6 

type ErrorAction struct {
	IgnoreSignals  map[string]any
	IgnoreMessage  string
	RetryMessage   string
	RetryAttempts  int
	RetrySleepSecs int
	ShouldIgnore   bool
	ShouldRetry    bool
}

ErrorAction represents the action to take when an error occurs

type ErrorsConfig added in v0.69.6 

type ErrorsConfig struct {
	Retry  map[string]*RetryConfig
	Ignore map[string]*IgnoreConfig
}

ErrorsConfig extracted errors handling configuration.

func (*ErrorsConfig) ProcessError added in v0.69.6 

func (c *ErrorsConfig) ProcessError(opts *TerragruntOptions, err error, currentAttempt int) (*ErrorAction, error)

ProcessError evaluates an error against the configuration and returns the appropriate action

type ErrorsPattern added in v0.69.8 

type ErrorsPattern struct {
	Pattern  *regexp.Regexp `clone:"shadowcopy"`
	Negative bool
}

type IAMRoleOptions added in v0.35.1 

type IAMRoleOptions struct {
	RoleARN               string
	WebIdentityToken      string
	AssumeRoleSessionName string
	AssumeRoleDuration    int64
}

IAMRoleOptions represents options that are used by Terragrunt to assume an IAM role.

func MergeIAMRoleOptions added in v0.35.1 

func MergeIAMRoleOptions(target IAMRoleOptions, source IAMRoleOptions) IAMRoleOptions

type IgnoreConfig added in v0.69.6 

type IgnoreConfig struct {
	Signals         map[string]any
	Name            string
	Message         string
	IgnorableErrors []*ErrorsPattern
}

IgnoreConfig represents the configuration for ignoring specific errors.

type RetryConfig added in v0.69.6 

type RetryConfig struct {
	Name             string
	RetryableErrors  []*ErrorsPattern
	MaxAttempts      int
	SleepIntervalSec int
}

RetryConfig represents the configuration for retrying specific errors.

type TerraformImplementationType added in v0.52.0 

type TerraformImplementationType string
const (
	TerraformImpl TerraformImplementationType = "terraform"
	OpenTofuImpl  TerraformImplementationType = "tofu"
	UnknownImpl   TerraformImplementationType = "unknown"
)

type TerragruntOptions 

type TerragruntOptions struct {
	// Logger is an interface for logging events.
	Logger log.Logger `clone:"shadowcopy"`
	// If you want stdout to go somewhere other than os.stdout
	Writer io.Writer
	// If you want stderr to go somewhere other than os.stderr
	ErrWriter io.Writer
	// Version of terragrunt
	TerragruntVersion *version.Version `clone:"shadowcopy"`
	// FeatureFlags is a map of feature flags to enable.
	FeatureFlags *xsync.MapOf[string, string] `clone:"shadowcopy"`
	// Options to use engine for running IaC operations.
	Engine *EngineOptions
	// Telemetry are telemetry options.
	Telemetry *telemetry.Options
	// Attributes to override in AWS provider nested within modules as part of the aws-provider-patch command.
	AwsProviderPatchOverrides map[string]string
	// A command that can be used to run Terragrunt with the given options.
	RunTerragrunt func(ctx context.Context, opts *TerragruntOptions) error
	// Version of terraform (obtained by running 'terraform version')
	TerraformVersion *version.Version `clone:"shadowcopy"`
	// ReadFiles is a map of files to the Units that read them using HCL functions in the unit.
	ReadFiles *xsync.MapOf[string, []string] `clone:"shadowcopy"`
	// Errors is a configuration for error handling.
	Errors *ErrorsConfig
	// Map to replace terraform source locations.
	SourceMap map[string]string
	// Environment variables at runtime
	Env map[string]string
	// IAM Role options that should be used when authenticating to AWS.
	IAMRoleOptions IAMRoleOptions
	// IAM Role options set from command line.
	OriginalIAMRoleOptions IAMRoleOptions
	// The Token for authentication to the Terragrunt Provider Cache server.
	ProviderCacheToken string
	// Current Terraform command being executed by Terragrunt
	TerraformCommand string
	// StackOutputFormat format how the stack output is rendered.
	StackOutputFormat         string
	TerragruntStackConfigPath string
	// Location of the original Terragrunt config file.
	OriginalTerragruntConfigPath string
	// Unlike `WorkingDir`, this path is the same for all dependencies and points to the root working directory specified in the CLI.
	RootWorkingDir string
	// Download Terraform configurations from the specified source location into a temporary folder
	Source string
	// The working directory in which to run Terraform
	WorkingDir string
	// Location of the terraform binary
	TerraformPath string
	// Download Terraform configurations specified in the Source parameter into this folder
	DownloadDir string
	// Original Terraform command being executed by Terragrunt.
	OriginalTerraformCommand string
	// Terraform implementation tool (e.g. terraform, tofu) that terragrunt is wrapping
	TerraformImplementation TerraformImplementationType
	// The file path that terragrunt should use when rendering the terragrunt.hcl config as json.
	JSONOut string
	// The path to store unpacked providers.
	ProviderCacheDir string
	// Custom log level for engine
	EngineLogLevel string
	// Path to cache directory for engine files
	EngineCachePath string
	// The command and arguments that can be used to fetch authentication configurations.
	AuthProviderCmd string
	// Folder to store JSON representation of output files.
	JSONOutputFolder string
	// Folder to store output files.
	OutputFolder string
	// The file which hclfmt should be specifically run on
	HclFile string
	// The hostname of the Terragrunt Provider Cache server.
	ProviderCacheHostname string
	// Location of the Terragrunt config file
	TerragruntConfigPath string
	// Name of the root Terragrunt configuration file, if used.
	ScaffoldRootFileName string
	// Path to a file with a list of directories that need to be excluded when running *-all commands.
	ExcludesFile string
	// Path to folder of scaffold output
	ScaffoldOutputFolder string
	// Root directory for graph command.
	GraphRoot string
	// CLI args that are intended for Terraform (i.e. all the CLI args except the --terragrunt ones)
	TerraformCliArgs cli.Args
	// Unix-style glob of directories to include when running *-all commands
	IncludeDirs []string
	// Unix-style glob of directories to exclude when running *-all commands
	ExcludeDirs []string
	// RetryableErrors is an array of regular expressions with RE2 syntax that qualify for retrying
	RetryableErrors []string
	// Files with variables to be used in modules scaffolding.
	ScaffoldVarFiles []string
	// The list of remote registries to cached by Terragrunt Provider Cache server.
	ProviderCacheRegistryNames []string
	// If set hclfmt will skip files in given directories.
	HclExclude []string
	// Variables for usage in scaffolding.
	ScaffoldVars []string
	// StrictControls is a slice of strict controls.
	StrictControls strict.Controls `clone:"shadowcopy"`
	// When used with `run-all`, restrict the modules in the stack to only those that include at least one of the files in this list.
	ModulesThatInclude []string
	// When used with `run-all`, restrict the units in the stack to only those that read at least one of the files in this list.
	UnitsReading []string
	// Experiments is a map of experiments, and their status.
	Experiments experiment.Experiments `clone:"shadowcopy"`
	// Maximum number of times to retry errors matching RetryableErrors
	RetryMaxAttempts int
	// Parallelism limits the number of commands to run concurrently during *-all commands
	Parallelism int
	// When searching the directory tree, this is the max folders to check before exiting with an error.
	MaxFoldersToCheck int
	// The port of the Terragrunt Provider Cache server.
	ProviderCachePort int
	// The duration in seconds to wait before retrying
	RetrySleepInterval time.Duration
	// Output Terragrunt logs in JSON format
	JSONLogFormat bool
	// True if terragrunt should run in debug mode
	Debug bool
	// Disable TF output formatting
	ForwardTFStdout bool
	// Fail execution if is required to create S3 bucket
	FailIfBucketCreationRequired bool
	// Controls if s3 bucket should be updated or skipped
	DisableBucketUpdate bool
	// Disables validation terraform command
	DisableCommandValidation bool
	// If True then HCL from StdIn must should be formatted.
	HclFromStdin bool
	// Show diff, by default it's disabled.
	Diff bool
	// Do not include root unit in scaffolding.
	ScaffoldNoIncludeRoot bool
	// Enable check mode, by default it's disabled.
	Check bool
	// Enables caching of includes during partial parsing operations.
	UsePartialParseConfigCache bool
	// If set to true, do not include dependencies when processing IncludeDirs
	StrictInclude bool
	// Disable listing of dependent modules in render json output
	JSONDisableDependentModules bool
	// Enables Terragrunt's provider caching.
	ProviderCache bool
	// If set to true, exclude all directories by default when running *-all commands
	ExcludeByDefault bool
	// This is an experimental feature, used to speed up dependency processing by getting the output from the state
	FetchDependencyOutputFromState bool
	// True if is required to show dependent modules and confirm action
	CheckDependentModules bool
	// True if is required not to show dependent modules and confirm action
	NoDestroyDependenciesCheck bool
	// Include fields metadata in render-json
	RenderJSONWithMetadata bool
	// Whether we should automatically retry errored Terraform commands
	AutoRetry bool
	// Flag to enable engine for running IaC operations.
	EngineEnabled bool
	// Whether we should automatically run terraform init if necessary when executing other commands
	AutoInit bool
	// Allows to skip the output of all dependencies.
	SkipOutput bool
	// Whether we should prompt the user for confirmation or always assume "yes"
	NonInteractive bool
	// If set to true, apply all external dependencies when running *-all commands
	IncludeExternalDependencies bool
	// Skip checksum check for engine package.
	EngineSkipChecksumCheck bool
	// If set to true, skip any external dependencies when running *-all commands
	IgnoreExternalDependencies bool
	// If set to true, ignore the dependency order when running *-all command.
	IgnoreDependencyOrder bool
	// If set to true, continue running *-all commands even if a dependency has errors.
	IgnoreDependencyErrors bool
	// Whether we should automatically run terraform with -auto-apply in run-all mode.
	RunAllAutoApprove bool
	// If set to true, delete the contents of the temporary folder before downloading Terraform source code into it
	SourceUpdate bool
	// HCLValidateStrict is a strict mode for HCL validation files. When it's set to false the command will only return an error if required inputs are missing from all input sources (env vars, var files, etc). When it's set to true, an error will be returned if required inputs are missing or if unused variables are passed to Terragrunt.",
	HCLValidateStrict bool
	// HCLValidateInputs checks if the terragrunt configured inputs align with the terraform defined variables.
	HCLValidateInputs bool
	// HCLValidateShowConfigPath shows the paths of the hcl invalid configs.
	HCLValidateShowConfigPath bool
	// HCLValidateJSONOutput outputs the hcl validate result as a JSON string.
	HCLValidateJSONOutput bool
	// If true, logs will be displayed in formatter key/value, by default logs are formatted in human-readable formatter.
	DisableLogFormatting bool
	// Headless is set when Terragrunt is running in headless mode.
	Headless bool
	// LogDisableErrorSummary is a flag to skip the error summary
	LogDisableErrorSummary bool
	// Disable replacing full paths in logs with short relative paths
	LogShowAbsPaths bool
	// NoStackGenerate disable stack generation.
	NoStackGenerate bool
	// NoStackValidate disable generated stack validation.
	NoStackValidate bool
	// RunAll runs the provided OpenTofu/Terraform command against a stack.
	RunAll bool
	// Graph runs the provided OpenTofu/Terraform against the graph of dependencies for the unit in the current working directory.
	Graph bool
	// BackendBootstrap automatically bootstraps backend infrastructure before attempting to use it.
	BackendBootstrap bool
	// DeleteBucket determines whether to delete entire bucket.
	DeleteBucket bool
	// ForceBackendDelete forces the backend to be deleted, even if the bucket is not versioned.
	ForceBackendDelete bool
	// ForceBackendMigrate forces the backend to be migrated, even if the bucket is not versioned.
	ForceBackendMigrate bool
}

TerragruntOptions represents options that configure the behavior of the Terragrunt program

func NewTerragruntOptions added in v0.6.0 

func NewTerragruntOptions() *TerragruntOptions

NewTerragruntOptions creates a new TerragruntOptions object with reasonable defaults for real usage

func NewTerragruntOptionsForTest added in v0.6.0 

func NewTerragruntOptionsForTest(terragruntConfigPath string, options ...TerragruntOptionsFunc) (*TerragruntOptions, error)

NewTerragruntOptionsForTest creates a new TerragruntOptions object with reasonable defaults for test usage.

func NewTerragruntOptionsWithConfigPath added in v0.48.7 

func NewTerragruntOptionsWithConfigPath(terragruntConfigPath string) (*TerragruntOptions, error)

func NewTerragruntOptionsWithWriters added in v0.67.5 

func NewTerragruntOptionsWithWriters(stdout, stderr io.Writer) *TerragruntOptions

func (*TerragruntOptions) AppendReadFile added in v0.68.13 

func (opts *TerragruntOptions) AppendReadFile(file, unit string)

AppendReadFile appends to the list of files read by a given unit.

func (*TerragruntOptions) AppendTerraformCliArgs added in v0.13.0 

func (opts *TerragruntOptions) AppendTerraformCliArgs(argsToAppend ...string)

AppendTerraformCliArgs appends the given argsToAppend after the current TerraformCliArgs.

func (*TerragruntOptions) Clone added in v0.6.0 

func (opts *TerragruntOptions) Clone() *TerragruntOptions

Clone performs a deep copy of `opts` with shadow copies of: interfaces, and funcs. Fields with "clone" tags can override this behavior.

func (*TerragruntOptions) CloneReadFiles added in v0.68.13 

func (opts *TerragruntOptions) CloneReadFiles(readFiles *xsync.MapOf[string, []string])

CloneReadFiles creates a copy of the ReadFiles map.

func (*TerragruntOptions) CloneWithConfigPath added in v0.73.0 

func (opts *TerragruntOptions) CloneWithConfigPath(configPath string) (*TerragruntOptions, error)

CloneWithConfigPath creates a copy of this TerragruntOptions, but with different values for the given variables. This is useful for creating a TerragruntOptions that behaves the same way, but is used for a Terraform module in a different folder.

func (*TerragruntOptions) DataDir added in v0.20.1 

func (opts *TerragruntOptions) DataDir() string

DataDir returns the Terraform data directory prepended with the working directory path, or just the Terraform data directory if it is an absolute path.

func (*TerragruntOptions) DidReadFile added in v0.68.13 

func (opts *TerragruntOptions) DidReadFile(file, unit string) bool

DidReadFile checks if a given file was read by a given unit.

func (*TerragruntOptions) InsertTerraformCliArgs added in v0.13.0 

func (opts *TerragruntOptions) InsertTerraformCliArgs(argsToInsert ...string)

InsertTerraformCliArgs inserts the given argsToInsert after the terraform command argument, but before the remaining args.

func (*TerragruntOptions) OptionsFromContext added in v0.48.7 

func (opts *TerragruntOptions) OptionsFromContext(ctx context.Context) *TerragruntOptions

OptionsFromContext tries to retrieve options from context, otherwise, returns its own instance.

func (*TerragruntOptions) RunWithErrorHandling added in v0.69.6 

func (opts *TerragruntOptions) RunWithErrorHandling(ctx context.Context, operation func() error) error

RunWithErrorHandling runs the given operation and handles any errors according to the configuration.

func (*TerragruntOptions) TerraformDataDir added in v0.23.24 

func (opts *TerragruntOptions) TerraformDataDir() string

TerraformDataDir returns Terraform data directory (.terraform by default, overridden by $TF_DATA_DIR envvar)

type TerragruntOptionsFunc added in v0.59.3 

type TerragruntOptionsFunc func(*TerragruntOptions)

TerragruntOptionsFunc is a functional option type used to pass options in certain integration tests

func WithIAMRoleARN added in v0.59.3 

func WithIAMRoleARN(arn string) TerragruntOptionsFunc

WithIAMRoleARN adds the provided role ARN to IamRoleOptions

func WithIAMWebIdentityToken added in v0.59.3 

func WithIAMWebIdentityToken(token string) TerragruntOptionsFunc

WithIAMWebIdentityToken adds the provided WebIdentity token to IamRoleOptions

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.