terraform

package
v0.31.5 Latest Latest
Warning

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

 Go to latest Published: Jan 21, 2021 License: Apache-2.0 Imports: 17 Imported by: 235

Documentation

Overview

Package terraform allows to interact with Terraform.

Index

Constants

View Source 
const DefaultErrorExitCode = 1

DefaultErrorExitCode is the exit code returned when terraform command fails

View Source 
const DefaultSuccessExitCode = 0

DefaultSuccessExitCode is the exit code returned when terraform command succeeds

View Source 
const TerraformPlanChangesPresentExitCode = 2

TerraformPlanChangesPresentExitCode is the exit code returned by terraform plan detailed exitcode when changes are present

Variables

View Source 
var (
	DefaultRetryableTerraformErrors = map[string]string{

		".*read: connection reset by peer.*": "Failed to reach helm charts repository.",
		".*transport is closing.*":           "Failed to reach Kubernetes API.",

		".*unable to verify signature.*":                  "Failed to retrieve plugin due to transient network error.",
		".*unable to verify checksum.*":                   "Failed to retrieve plugin due to transient network error.",
		".*no provider exists with the given name.*":      "Failed to retrieve plugin due to transient network error.",
		".*registry service is unreachable.*":             "Failed to retrieve plugin due to transient network error.",
		".*Error installing provider.*":                   "Failed to retrieve plugin due to transient network error.",
		".*Failed to query available provider packages.*": "Failed to retrieve plugin due to transient network error.",
		".*timeout while waiting for plugin to start.*":   "Failed to retrieve plugin due to transient network error.",
		".*timed out waiting for server handshake.*":      "Failed to retrieve plugin due to transient network error.",

		".*Provider produced inconsistent result after apply.*": "Provider eventual consistency error.",
	}
)
View Source 
var (
	PlanFilePathRequired = fmt.Errorf("You must set PlanFilePath on options struct to use this function.")
)
View Source 
var TerraformCommandsWithLockSupport = []string{
	"plan",
	"apply",
	"destroy",
	"init",
	"refresh",
	"taint",
	"untaint",
	"import",
}

TerraformCommandsWithLockSupport is a list of all the Terraform commands that can obtain locks on Terraform state

View Source 
var TerraformCommandsWithPlanFileSupport = []string{
	"plan",
	"apply",
	"show",
	"graph",
}

TerraformCommandsWithPlanFileSupport is a list of all the Terraform commands that support interacting with plan files.

Functions

func Apply 

func Apply(t testing.TestingT, options *Options) string

Apply runs terraform apply with the given options and return stdout/stderr. Note that this method does NOT call destroy and assumes the caller is responsible for cleaning up any resources created by running apply.

func ApplyAndIdempotent added in v0.28.5 

func ApplyAndIdempotent(t testing.TestingT, options *Options) string

ApplyAndIdempotent runs terraform apply with the given options and return stdout/stderr from the apply command. It then runs plan again and will fail the test if plan requires additional changes. Note that this method does NOT call destroy and assumes the caller is responsible for cleaning up any resources created by running apply.

func ApplyAndIdempotentE added in v0.28.5 

func ApplyAndIdempotentE(t testing.TestingT, options *Options) (string, error)

ApplyAndIdempotentE runs terraform apply with the given options and return stdout/stderr from the apply command. It then runs plan again and will fail the test if plan requires additional changes. Note that this method does NOT call destroy and assumes the caller is responsible for cleaning up any resources created by running apply.

func ApplyE 

func ApplyE(t testing.TestingT, options *Options) (string, error)

ApplyE runs terraform apply with the given options and return stdout/stderr. Note that this method does NOT call destroy and assumes the caller is responsible for cleaning up any resources created by running apply.

func Destroy 

func Destroy(t testing.TestingT, options *Options) string

Destroy runs terraform destroy with the given options and return stdout/stderr.

func DestroyE 

func DestroyE(t testing.TestingT, options *Options) (string, error)

DestroyE runs terraform destroy with the given options and return stdout/stderr.

func FormatArgs 

func FormatArgs(options *Options, args ...string) []string

FormatArgs converts the inputs to a format palatable to terraform. This includes converting the given vars to the format the Terraform CLI expects (-var key=value).

func FormatTerraformArgs added in v0.13.27 

func FormatTerraformArgs(argName string, args []string) []string

FormatTerraformArgs will format multiple args with the arg name (e.g. "-var-file", []string{"foo.tfvars", "bar.tfvars"}) returns "-var-file foo.tfvars -var-file bar.tfvars"

func FormatTerraformBackendConfigAsArgs added in v0.9.13 

func FormatTerraformBackendConfigAsArgs(vars map[string]interface{}) []string

FormatTerraformBackendConfigAsArgs formats the given variables as backend config args for Terraform (e.g. of the format -backend-config=key=value).

func FormatTerraformLockAsArgs added in v0.23.1 

func FormatTerraformLockAsArgs(lockCheck bool, lockTimeout string) []string

FormatTerraformLockAsArgs formats the lock and lock-timeout variables -lock, -lock-timeout

func FormatTerraformPlanFileAsArg added in v0.30.16 

func FormatTerraformPlanFileAsArg(commandType string, outPath string) []string

FormatTerraformPlanFileAsArg formats the out variable as a command-line arg for Terraform (e.g. of the format -out=/some/path/to/plan.out or /some/path/to/plan.out). Only plan supports passing in the plan file as -out; the other commands expect it as the first positional argument. This returns an empty string if outPath is empty string.

func FormatTerraformVarsAsArgs 

func FormatTerraformVarsAsArgs(vars map[string]interface{}) []string

FormatTerraformVarsAsArgs formats the given variables as command-line args for Terraform (e.g. of the format -var key=value).

func Get 

func Get(t testing.TestingT, options *Options) string

Get calls terraform get and return stdout/stderr.

func GetE 

func GetE(t testing.TestingT, options *Options) (string, error)

GetE calls terraform get and return stdout/stderr.

func GetExitCodeForTerraformCommand added in v0.10.4 

func GetExitCodeForTerraformCommand(t testing.TestingT, additionalOptions *Options, args ...string) int

GetExitCodeForTerraformCommand runs terraform with the given arguments and options and returns exit code

func GetExitCodeForTerraformCommandE added in v0.10.4 

func GetExitCodeForTerraformCommandE(t testing.TestingT, additionalOptions *Options, additionalArgs ...string) (int, error)

GetExitCodeForTerraformCommandE runs terraform with the given arguments and options and returns exit code

func Init 

func Init(t testing.TestingT, options *Options) string

Init calls terraform init and return stdout/stderr.

func InitAndApply 

func InitAndApply(t testing.TestingT, options *Options) string

InitAndApply runs terraform init and apply with the given options and return stdout/stderr from the apply command. Note that this method does NOT call destroy and assumes the caller is responsible for cleaning up any resources created by running apply.

func InitAndApplyAndIdempotent added in v0.28.5 

func InitAndApplyAndIdempotent(t testing.TestingT, options *Options) string

InitAndApplyAndIdempotent runs terraform init and apply with the given options and return stdout/stderr from the apply command. It then runs plan again and will fail the test if plan requires additional changes. Note that this method does NOT call destroy and assumes the caller is responsible for cleaning up any resources created by running apply.

func InitAndApplyAndIdempotentE added in v0.28.5 

func InitAndApplyAndIdempotentE(t testing.TestingT, options *Options) (string, error)

InitAndApplyAndIdempotentE runs terraform init and apply with the given options and return stdout/stderr from the apply command. It then runs plan again and will fail the test if plan requires additional changes. Note that this method does NOT call destroy and assumes the caller is responsible for cleaning up any resources created by running apply.

func InitAndApplyE 

func InitAndApplyE(t testing.TestingT, options *Options) (string, error)

InitAndApplyE runs terraform init and apply with the given options and return stdout/stderr from the apply command. Note that this method does NOT call destroy and assumes the caller is responsible for cleaning up any resources created by running apply.

func InitAndPlan added in v0.10.4 

func InitAndPlan(t testing.TestingT, options *Options) string

InitAndPlan runs terraform init and plan with the given options and returns stdout/stderr from the plan command. This will fail the test if there is an error in the command.

func InitAndPlanAndShow added in v0.30.16 

func InitAndPlanAndShow(t testing.TestingT, options *Options) string

InitAndPlanAndShow runs terraform init, then terraform plan, and then terraform show with the given options, and returns the json output of the plan file. This will fail the test if there is an error in the command.

func InitAndPlanAndShowE added in v0.30.16 

func InitAndPlanAndShowE(t testing.TestingT, options *Options) (string, error)

InitAndPlanAndShowE runs terraform init, then terraform plan, and then terraform show with the given options, and returns the json output of the plan file.

func InitAndPlanE added in v0.10.4 

func InitAndPlanE(t testing.TestingT, options *Options) (string, error)

InitAndPlanE runs terraform init and plan with the given options and returns stdout/stderr from the plan command.

func InitAndPlanWithExitCode added in v0.17.0 

func InitAndPlanWithExitCode(t testing.TestingT, options *Options) int

InitAndPlanWithExitCode runs terraform init and plan with the given options and returns exitcode for the plan command. This will fail the test if there is an error in the command.

func InitAndPlanWithExitCodeE added in v0.17.0 

func InitAndPlanWithExitCodeE(t testing.TestingT, options *Options) (int, error)

InitAndPlanWithExitCodeE runs terraform init and plan with the given options and returns exitcode for the plan command.

func InitE 

func InitE(t testing.TestingT, options *Options) (string, error)

InitE calls terraform init and return stdout/stderr.

func Output 

func Output(t testing.TestingT, options *Options, key string) string

Output calls terraform output for the given variable and return its string value representation. It only designed to work with primitive terraform types: string, number and bool. Please use OutputStruct for anything else.

func OutputAll added in v0.13.19 

func OutputAll(t testing.TestingT, options *Options) map[string]interface{}

OutputAll calls terraform output returns all values as a map. If there is error fetching the output, fails the test

func OutputAllE added in v0.13.19 

func OutputAllE(t testing.TestingT, options *Options) (map[string]interface{}, error)

OutputAllE calls terraform and returns all the outputs as a map

func OutputE 

func OutputE(t testing.TestingT, options *Options, key string) (string, error)

OutputE calls terraform output for the given variable and return its string value representation. It only designed to work with primitive terraform types: string, number and bool. Please use OutputStructE for anything else.

func OutputForKeys added in v0.13.19 

func OutputForKeys(t testing.TestingT, options *Options, keys []string) map[string]interface{}

OutputForKeys calls terraform output for the given key list and returns values as a map. If keys not found in the output, fails the test

func OutputForKeysE added in v0.13.19 

func OutputForKeysE(t testing.TestingT, options *Options, keys []string) (map[string]interface{}, error)

OutputForKeysE calls terraform output for the given key list and returns values as a map. The returned values are of type interface{} and need to be type casted as necessary. Refer to output_test.go

func OutputJson added in v0.31.1 

func OutputJson(t testing.TestingT, options *Options, key string) string

OutputJson calls terraform output for the given variable and returns the result as the json string. If key is an empty string, it will return all the output variables.

func OutputJsonE added in v0.31.1 

func OutputJsonE(t testing.TestingT, options *Options, key string) (string, error)

OutputJsonE calls terraform output for the given variable and returns the result as the json string. If key is an empty string, it will return all the output variables.

func OutputList added in v0.13.1 

func OutputList(t testing.TestingT, options *Options, key string) []string

OutputList calls terraform output for the given variable and returns its value as a list. If the output value is not a list type, then it fails the test.

func OutputListE added in v0.13.1 

func OutputListE(t testing.TestingT, options *Options, key string) ([]string, error)

OutputListE calls terraform output for the given variable and returns its value as a list. If the output value is not a list type, then it returns an error.

func OutputListOfObjects added in v0.28.2 

func OutputListOfObjects(t testing.TestingT, options *Options, key string) []map[string]interface{}

OutputListOfObjects calls terraform output for the given variable and returns its value as a list of maps/lists. If the output value is not a list of maps/lists, then it fails the test.

func OutputListOfObjectsE added in v0.28.2 

func OutputListOfObjectsE(t testing.TestingT, options *Options, key string) ([]map[string]interface{}, error)

OutputListOfObjectsE calls terraform output for the given variable and returns its value as a list of maps/lists. Also returns an error object if an error was generated. If the output value is not a list of maps/lists, then it fails the test.

func OutputMap added in v0.13.6 

func OutputMap(t testing.TestingT, options *Options, key string) map[string]string

OutputMap calls terraform output for the given variable and returns its value as a map. If the output value is not a map type, then it fails the test.

func OutputMapE added in v0.13.6 

func OutputMapE(t testing.TestingT, options *Options, key string) (map[string]string, error)

OutputMapE calls terraform output for the given variable and returns its value as a map. If the output value is not a map type, then it returns an error.

func OutputMapOfObjects added in v0.28.2 

func OutputMapOfObjects(t testing.TestingT, options *Options, key string) map[string]interface{}

OutputMapOfObjects calls terraform output for the given variable and returns its value as a map of lists/maps. If the output value is not a map of lists/maps, then it fails the test.

func OutputMapOfObjectsE added in v0.28.2 

func OutputMapOfObjectsE(t testing.TestingT, options *Options, key string) (map[string]interface{}, error)

OutputMapOfObjectsE calls terraform output for the given variable and returns its value as a map of lists/maps. Also returns an error object if an error was generated. If the output value is not a map of lists/maps, then it fails the test.

func OutputRequired 

func OutputRequired(t testing.TestingT, options *Options, key string) string

OutputRequired calls terraform output for the given variable and return its value. If the value is empty, fail the test.

func OutputRequiredE 

func OutputRequiredE(t testing.TestingT, options *Options, key string) (string, error)

OutputRequiredE calls terraform output for the given variable and return its value. If the value is empty, return an error.

func OutputStruct added in v0.28.8 

func OutputStruct(t testing.TestingT, options *Options, key string, v interface{})

OutputStruct calls terraform output for the given variable and stores the result in the value pointed to by v. If v is nil or not a pointer, or if the value returned by Terraform is not appropriate for a given target type, it fails the test.

func OutputStructE added in v0.28.8 

func OutputStructE(t testing.TestingT, options *Options, key string, v interface{}) error

OutputStructE calls terraform output for the given variable and stores the result in the value pointed to by v. If v is nil or not a pointer, or if the value returned by Terraform is not appropriate for a given target type, it returns an error.

func Plan added in v0.17.0 

func Plan(t testing.TestingT, options *Options) string

Plan runs terraform plan with the given options and returns stdout/stderr. This will fail the test if there is an error in the command.

func PlanE added in v0.17.0 

func PlanE(t testing.TestingT, options *Options) (string, error)

PlanE runs terraform plan with the given options and returns stdout/stderr.

func PlanExitCode added in v0.10.4 

func PlanExitCode(t testing.TestingT, options *Options) int

PlanExitCode runs terraform plan with the given options and returns the detailed exitcode. This will fail the test if there is an error in the command.

func PlanExitCodeE added in v0.10.4 

func PlanExitCodeE(t testing.TestingT, options *Options) (int, error)

PlanExitCodeE runs terraform plan with the given options and returns the detailed exitcode.

func RunTerraformCommand added in v0.9.2 

func RunTerraformCommand(t testing.TestingT, additionalOptions *Options, args ...string) string

RunTerraformCommand runs terraform with the given arguments and options and return stdout/stderr.

func RunTerraformCommandAndGetStdoutE added in v0.17.2 

func RunTerraformCommandAndGetStdoutE(t testing.TestingT, additionalOptions *Options, additionalArgs ...string) (string, error)

RunTerraformCommandAndGetStdoutE runs terraform with the given arguments and options and returns solely its stdout (but not stderr).

func RunTerraformCommandE added in v0.9.2 

func RunTerraformCommandE(t testing.TestingT, additionalOptions *Options, additionalArgs ...string) (string, error)

RunTerraformCommandE runs terraform with the given arguments and options and return stdout/stderr.

func Show added in v0.30.16 

func Show(t testing.TestingT, options *Options) string

Show calls terraform show in json mode with the given options and returns stdout from the command. If PlanFilePath is set on the options, this will show the plan file. Otherwise, this will show the current state of the terraform module at options.TerraformDir. This will fail the test if there is an error in the command.

func ShowE added in v0.30.16 

func ShowE(t testing.TestingT, options *Options) (string, error)

ShowE calls terraform show in json mode with the given options and returns stdout from the command. If PlanFilePath is set on the options, this will show the plan file. Otherwise, this will show the current state of the terraform module at options.TerraformDir.

func TgApplyAll added in v0.15.12 

func TgApplyAll(t testing.TestingT, options *Options) string

TgApplyAll runs terragrunt apply with the given options and return stdout/stderr. Note that this method does NOT call destroy and assumes the caller is responsible for cleaning up any resources created by running apply.

func TgApplyAllE added in v0.15.12 

func TgApplyAllE(t testing.TestingT, options *Options) (string, error)

TgApplyAllE runs terragrunt apply-all with the given options and return stdout/stderr. Note that this method does NOT call destroy and assumes the caller is responsible for cleaning up any resources created by running apply.

func TgDestroyAll added in v0.15.12 

func TgDestroyAll(t testing.TestingT, options *Options) string

TgDestroyAll runs terragrunt destroy with the given options and return stdout.

func TgDestroyAllE added in v0.15.12 

func TgDestroyAllE(t testing.TestingT, options *Options) (string, error)

TgDestroyAllE runs terragrunt destroy with the given options and return stdout.

func TgPlanAllExitCode added in v0.15.12 

func TgPlanAllExitCode(t testing.TestingT, options *Options) int

TgPlanAllExitCode runs terragrunt plan-all with the given options and returns the detailed exitcode. This will fail the test if there is an error in the command.

func TgPlanAllExitCodeE added in v0.15.12 

func TgPlanAllExitCodeE(t testing.TestingT, options *Options) (int, error)

TgPlanAllExitCodeE runs terragrunt plan-all with the given options and returns the detailed exitcode.

func WorkspaceSelectOrNew added in v0.12.2 

func WorkspaceSelectOrNew(t testing.TestingT, options *Options, name string) string

WorkspaceSelectOrNew runs terraform workspace with the given options and the workspace name and returns a name of the current workspace. It tries to select a workspace with the given name, or it creates a new one if it doesn't exist.

func WorkspaceSelectOrNewE added in v0.12.2 

func WorkspaceSelectOrNewE(t testing.TestingT, options *Options, name string) (string, error)

WorkspaceSelectOrNewE runs terraform workspace with the given options and the workspace name and returns a name of the current workspace. It tries to select a workspace with the given name, or it creates a new one if it doesn't exist.

Types

type EmptyOutput 

type EmptyOutput string

EmptyOutput is an error that occurs when an output is empty.

func (EmptyOutput) Error 

func (outputName EmptyOutput) Error() string

type Options 

type Options struct {
	TerraformBinary string // Name of the binary that will be used
	TerraformDir    string // The path to the folder where the Terraform code is defined.

	// The vars to pass to Terraform commands using the -var option. Note that terraform does not support passing `null`
	// as a variable value through the command line. That is, if you use `map[string]interface{}{"foo": nil}` as `Vars`,
	// this will translate to the string literal `"null"` being assigned to the variable `foo`. However, nulls in
	// lists and maps/objects are supported. E.g., the following var will be set as expected (`{ bar = null }`:
	// map[string]interface{}{
	//     "foo": map[string]interface{}{"bar": nil},
	// }
	Vars map[string]interface{}

	VarFiles                 []string               // The var file paths to pass to Terraform commands using -var-file option.
	Targets                  []string               // The target resources to pass to the terraform command with -target
	Lock                     bool                   // The lock option to pass to the terraform command with -lock
	LockTimeout              string                 // The lock timeout option to pass to the terraform command with -lock-timeout
	EnvVars                  map[string]string      // Environment variables to set when running Terraform
	BackendConfig            map[string]interface{} // The vars to pass to the terraform init command for extra configuration for the backend
	RetryableTerraformErrors map[string]string      // If Terraform apply fails with one of these (transient) errors, retry. The keys are a regexp to match against the error and the message is what to display to a user if that error is matched.
	MaxRetries               int                    // Maximum number of times to retry errors matching RetryableTerraformErrors
	TimeBetweenRetries       time.Duration          // The amount of time to wait between retries
	Upgrade                  bool                   // Whether the -upgrade flag of the terraform init command should be set to true or not
	NoColor                  bool                   // Whether the -no-color flag will be set for any Terraform command or not
	SshAgent                 *ssh.SshAgent          // Overrides local SSH agent with the given in-process agent
	NoStderr                 bool                   // Disable stderr redirection
	OutputMaxLineSize        int                    // The max size of one line in stdout and stderr (in bytes)
	Logger                   *logger.Logger         // Set a non-default logger that should be used. See the logger package for more info.
	Parallelism              int                    // Set the parallelism setting for Terraform
	PlanFilePath             string                 // The path to output a plan file to (for the plan command) or read one from (for the apply command)
}

Options for running Terraform commands

func GetCommonOptions added in v0.10.4 

func GetCommonOptions(options *Options, args ...string) (*Options, []string)

GetCommonOptions extracts commons terraform options

func WithDefaultRetryableErrors added in v0.30.15 

func WithDefaultRetryableErrors(t *testing.T, originalOptions *Options) *Options

WithDefaultRetryableErrors makes a copy of the Options object and returns an updated object with sensible defaults for retryable errors. The included retryable errors are typical errors that most terraform modules encounter during testing, and are known to self resolve upon retrying. This will fail the test if there are any errors in the cloning process.

func (*Options) Clone added in v0.30.15 

func (options *Options) Clone() (*Options, error)

Clone makes a deep copy of most fields on the Options object and returns it.

NOTE: options.SshAgent and options.Logger CANNOT be deep copied (e.g., the SshAgent struct contains channels and listeners that can't be meaningfully copied), so the original values are retained.

type OutputKeyNotFound added in v0.15.12 

type OutputKeyNotFound string

OutputKeyNotFound occurs when terraform output does not contain a value for the key specified in the function call

func (OutputKeyNotFound) Error added in v0.15.12 

func (err OutputKeyNotFound) Error() string

type OutputValueNotList added in v0.15.12 

type OutputValueNotList struct {
	Value interface{}
}

OutputValueNotList occurs when casting a found output value to a list of interfaces fails

func (OutputValueNotList) Error added in v0.15.12 

func (err OutputValueNotList) Error() string

type OutputValueNotMap added in v0.15.12 

type OutputValueNotMap struct {
	Value interface{}
}

OutputValueNotMap occures when casting a found output value to a map fails

func (OutputValueNotMap) Error added in v0.15.12 

func (err OutputValueNotMap) Error() string

type ResourceCount added in v0.17.1 

type ResourceCount struct {
	Add     int
	Change  int
	Destroy int
}

ResourceCount represents counts of resources affected by terraform apply/plan/destroy command.

func GetResourceCount added in v0.17.1 

func GetResourceCount(t testing.TestingT, cmdout string) *ResourceCount

GetResourceCount parses stdout/stderr of apply/plan/destroy commands and returns number of affected resources. This will fail the test if given stdout/stderr isn't a valid output of apply/plan/destroy.

func GetResourceCountE added in v0.17.1 

func GetResourceCountE(t testing.TestingT, cmdout string) (*ResourceCount, error)

GetResourceCountE parses stdout/stderr of apply/plan/destroy commands and returns number of affected resources.

type TgInvalidBinary added in v0.15.12 

type TgInvalidBinary string

TgInvalidBinary occurs when a terragrunt function is called and the TerraformBinary is set to a value other than terragrunt

func (TgInvalidBinary) Error added in v0.15.12 

func (err TgInvalidBinary) Error() string

type UnexpectedOutputType added in v0.15.13 

type UnexpectedOutputType struct {
	Key          string
	ExpectedType string
	ActualType   string
}

UnexpectedOutputType is an error that occurs when the output is not of the type we expect

func (UnexpectedOutputType) Error added in v0.15.13 

func (err UnexpectedOutputType) Error() string

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.