From e67fc0fe9ba9cc88a990acdde8d3436bc40c9739 Mon Sep 17 00:00:00 2001 From: Paul Hinze Date: Wed, 20 Jan 2016 12:50:33 -0600 Subject: [PATCH] command: Change module-depth default to -1 This means that terraform commands like `plan`, `apply`, `show`, and `graph` will expand all modules by default. While modules-as-black-boxes is still very true in the conceptual design of modules, feedback on this behavior has consistently suggested that users would prefer to see more verbose output by default. The `-module-depth` flag and env var are retained to allow output to be optionally limited / summarized by these commands. --- command/graph.go | 2 +- command/meta.go | 9 ++++++-- command/meta_test.go | 4 ++-- command/plan.go | 2 +- command/show.go | 2 +- contrib/zsh-completion/_terraform | 6 ++--- .../source/docs/commands/graph.html.markdown | 2 +- .../source/docs/commands/plan.html.markdown | 2 +- .../source/docs/commands/show.html.markdown | 2 +- .../environment-variables.html.md | 4 ++-- .../source/docs/modules/usage.html.markdown | 12 +++++----- .../intro/getting-started/modules.html.md | 22 +++++++++++++------ 12 files changed, 40 insertions(+), 29 deletions(-) diff --git a/command/graph.go b/command/graph.go index 5719a8900e..6c7bfae044 100644 --- a/command/graph.go +++ b/command/graph.go @@ -99,7 +99,7 @@ Options: This helps when diagnosing cycle errors. -module-depth=n The maximum depth to expand modules. By default this is - zero, which will not expand modules at all. + -1, which will expand resources within all modules. -verbose Generate a verbose, "worst-case" graph, with all nodes for potential operations in place. diff --git a/command/meta.go b/command/meta.go index 3a12de02f7..bd4855964c 100644 --- a/command/meta.go +++ b/command/meta.go @@ -407,12 +407,17 @@ func (m *Meta) uiHook() *UiHook { } const ( - // The name of the environment variable that can be used to set module depth. + // ModuleDepthDefault is the default value for + // module depth, which can be overridden by flag + // or env var + ModuleDepthDefault = -1 + + // ModuleDepthEnvVar is the name of the environment variable that can be used to set module depth. ModuleDepthEnvVar = "TF_MODULE_DEPTH" ) func (m *Meta) addModuleDepthFlag(flags *flag.FlagSet, moduleDepth *int) { - flags.IntVar(moduleDepth, "module-depth", 0, "module-depth") + flags.IntVar(moduleDepth, "module-depth", ModuleDepthDefault, "module-depth") if envVar := os.Getenv(ModuleDepthEnvVar); envVar != "" { if md, err := strconv.Atoi(envVar); err == nil { *moduleDepth = md diff --git a/command/meta_test.go b/command/meta_test.go index b3022c64a1..781c664dc3 100644 --- a/command/meta_test.go +++ b/command/meta_test.go @@ -244,12 +244,12 @@ func TestMeta_addModuleDepthFlag(t *testing.T) { "invalid envvar is ignored": { EnvVar: "-#", Args: []string{}, - Expected: 0, + Expected: ModuleDepthDefault, }, "empty envvar is okay too": { EnvVar: "", Args: []string{}, - Expected: 0, + Expected: ModuleDepthDefault, }, } diff --git a/command/plan.go b/command/plan.go index 8c5fda5cc9..f0902e450c 100644 --- a/command/plan.go +++ b/command/plan.go @@ -181,7 +181,7 @@ Options: -module-depth=n Specifies the depth of modules to show in the output. This does not affect the plan itself, only the output - shown. By default, this is zero. -1 will expand all. + shown. By default, this is -1, which will expand all. -no-color If specified, output won't contain any color. diff --git a/command/show.go b/command/show.go index 624ee659db..8a32c4a8d5 100644 --- a/command/show.go +++ b/command/show.go @@ -118,7 +118,7 @@ Usage: terraform show [options] [path] Options: -module-depth=n Specifies the depth of modules to show in the output. - By default this is zero. -1 will expand all. + By default this is -1, which will expand all. -no-color If specified, output won't contain any color. diff --git a/contrib/zsh-completion/_terraform b/contrib/zsh-completion/_terraform index 1252bb9619..9f11933d8d 100644 --- a/contrib/zsh-completion/_terraform +++ b/contrib/zsh-completion/_terraform @@ -49,7 +49,7 @@ __get() { __graph() { _arguments \ - '-module-depth=[(n) The maximum depth to expand modules. By default this is zero, which will not expand modules at all.]' + '-module-depth=[(n) The maximum depth to expand modules. By default this is -1, which will expand all modules.]' } __init() { @@ -71,7 +71,7 @@ __plan() { '-backup=[(path) Path to backup the existing state file before modifying. Defaults to the "-state-out" path with" .backup" extension. Set to "-" to disable backup.]' \ '-destroy[If set, a plan will be generated to destroy all resources managed by the given configuration and state.]' \ '-input=[(true) Ask for input for variables if not directly set.]' \ - '-module-depth=[(n) Specifies the depth of modules to show in the output. This does not affect the plan itself, only the output shown. By default, this is zero. -1 will expand all.]' \ + '-module-depth=[(n) Specifies the depth of modules to show in the output. This does not affect the plan itself, only the output shown. By default, this is -1, which will expand all.]' \ '-no-color[If specified, output will not contain any color.]' \ '-out=[(path) Write a plan file to the given path. This can be used as input to the "apply" command.]' \ '-refresh=[(true) Update state prior to checking for differences.]' \ @@ -121,7 +121,7 @@ __remote() { __show() { _arguments \ - '-module-depth=[(n) The maximum depth to expand modules. By default this is zero, which will not expand modules at all.]' \ + '-module-depth=[(n) The maximum depth to expand modules. By default this is -1, which will expand all modules.]' \ '-no-color[If specified, output will not contain any color.]' } diff --git a/website/source/docs/commands/graph.html.markdown b/website/source/docs/commands/graph.html.markdown index d24005fcb9..611738ec02 100644 --- a/website/source/docs/commands/graph.html.markdown +++ b/website/source/docs/commands/graph.html.markdown @@ -31,7 +31,7 @@ Options: This helps when diagnosing cycle errors. * `-module-depth=n` - The maximum depth to expand modules. By default this is - zero, which will not expand modules at all. + -1, which will expand all modules. * `-verbose` - Generate a verbose, "worst-case" graph, with all nodes for potential operations in place. diff --git a/website/source/docs/commands/plan.html.markdown b/website/source/docs/commands/plan.html.markdown index e4a48ab5ba..cf6a780171 100644 --- a/website/source/docs/commands/plan.html.markdown +++ b/website/source/docs/commands/plan.html.markdown @@ -39,7 +39,7 @@ The command-line flags are all optional. The list of available flags are: * `-module-depth=n` - Specifies the depth of modules to show in the output. This does not affect the plan itself, only the output shown. By default, - this is zero. -1 will expand all. + this is -1, which will expand all. * `-no-color` - Disables output with coloring. diff --git a/website/source/docs/commands/show.html.markdown b/website/source/docs/commands/show.html.markdown index 703c3b09c8..8b88ccf29a 100644 --- a/website/source/docs/commands/show.html.markdown +++ b/website/source/docs/commands/show.html.markdown @@ -23,7 +23,7 @@ file. If no path is specified, the current state will be shown. The command-line flags are all optional. The list of available flags are: * `-module-depth=n` - Specifies the depth of modules to show in the output. - By default this is zero. -1 will expand all. + By default this is -1, which will expand all. * `-no-color` - Disables output with coloring diff --git a/website/source/docs/configuration/environment-variables.html.md b/website/source/docs/configuration/environment-variables.html.md index 1bb1f955a1..3c6eb89907 100644 --- a/website/source/docs/configuration/environment-variables.html.md +++ b/website/source/docs/configuration/environment-variables.html.md @@ -44,10 +44,10 @@ export TF_INPUT=0 ## TF_MODULE_DEPTH -When given a value, causes terraform commands to behave as if the `-module=depth=VALUE` flag was specified. Modules are treated like a black box and terraform commands do not show what resources within the module will be created. By setting this to -1, for example, you enable commands such as [plan](/docs/commands/plan.html) and [graph](/docs/commands/graph.html) to display more detailed information. +When given a value, causes terraform commands to behave as if the `-module=depth=VALUE` flag was specified. By setting this to 0, for example, you enable commands such as [plan](/docs/commands/plan.html) and [graph](/docs/commands/graph.html) to display more compressed information. ``` -export TF_MODULE_DEPTH=-1 +export TF_MODULE_DEPTH=0 ``` For more information regarding modules, check out the section on [Using Modules](/docs/modules/usage.html). diff --git a/website/source/docs/modules/usage.html.markdown b/website/source/docs/modules/usage.html.markdown index 31921623a9..cc331012ce 100644 --- a/website/source/docs/modules/usage.html.markdown +++ b/website/source/docs/modules/usage.html.markdown @@ -104,28 +104,26 @@ resource to the module, so the module will be built first. With modules, commands such as the [plan command](/docs/commands/plan.html) and -[graph command](/docs/commands/graph.html) will show the module as a single -unit by default. You can use the `-module-depth` parameter to expand this -graph further. +[graph command](/docs/commands/graph.html) will expand modules by default. You +can use the `-module-depth` parameter to limit the graph. For example, with a configuration similar to what we've built above, here is what the graph output looks like by default:
-![Terraform Module Graph](docs/module_graph.png) +![Terraform Expanded Module Graph](docs/module_graph_expand.png)
-But if we set `-module-depth=-1`, the graph will look like this: +But if we set `-module-depth=0`, the graph will look like this:
-![Terraform Expanded Module Graph](docs/module_graph_expand.png) +![Terraform Module Graph](docs/module_graph.png)
Other commands work similarly with modules. Note that the `-module-depth` flag is purely a formatting flag; it doesn't affect what modules are created or not. - ## Tainting resources within a module The [taint command](/docs/commands/taint.html) can be used to _taint_ diff --git a/website/source/intro/getting-started/modules.html.md b/website/source/intro/getting-started/modules.html.md index d25ef54ccb..18452f7793 100644 --- a/website/source/intro/getting-started/modules.html.md +++ b/website/source/intro/getting-started/modules.html.md @@ -50,7 +50,7 @@ module "consul" { key_name = "AWS SSH KEY NAME" key_path = "PATH TO ABOVE PRIVATE KEY" - region = "AWS REGION" + region = "us-east-1" servers = "3" } ``` @@ -94,14 +94,22 @@ With the modules downloaded, we can now plan and apply it. If you run ``` $ terraform plan ... -+ module.consul - 4 resource(s) ++ module.consul.aws_instance.server.0 +... ++ module.consul.aws_instance.server.1 +... ++ module.consul.aws_instance.server.2 +... ++ module.consul.aws_security_group.consul +... +Plan: 4 to add, 0 to change, 0 to destroy. ``` -As you can see, the module is treated like a black box. In the plan, Terraform -shows the module managed as a whole. It does not show what resources within -the module will be created. If you care, you can see that by specifying -a `-module-depth=-1` flag. +Conceptually, the module is treated like a black box. In the plan, however +Terraform shows each resource the module manages so you can see each detail +about what the plan will do. If you'd like compressed plan output, you can +specify the `-module-depth=` flag to get Terraform to output summaries by +module. Next, run `terraform apply` to create the module. Note that as we warned above, the resources this module creates are outside of the AWS free tier, so this