feat: Adding Strict Package (#3424)

* WIP - feat: Adding strict package

* feat: Adding strict package

* feat: Removing default on/off control. It just complicates things.

* feat: Documenting Strict Mode

* fix: Addressing markdownlint errors

* fix: Addressing lints

* fix: Blindly do what Levko says to do

* fix: Incorporate review feedback

* fix: Fixing docs for redesigned implementation

* fix: Fixing bug in implementation.

* fix: Cleaning up strict implementation

* fix: Markdown linting

* fix: Revert change to README

* fix: Adding integration tests

cli/commands/flags.go

@@ -6,6 +6,7 @@ import (
 
  "github.com/gruntwork-io/go-commons/collections"
  "github.com/gruntwork-io/terragrunt/internal/errors"
+ "github.com/gruntwork-io/terragrunt/internal/strict"
  "github.com/gruntwork-io/terragrunt/options"
  "github.com/gruntwork-io/terragrunt/pkg/cli"
  "github.com/gruntwork-io/terragrunt/pkg/log"
@@ -143,6 +144,14 @@ const (
  TerragruntForwardTFStdoutFlagName = "terragrunt-forward-tf-stdout"
  TerragruntForwardTFStdoutEnvName = "TERRAGRUNT_FORWARD_TF_STDOUT"
 
+ // Strict Mode related flags/envs
+
+ TerragruntStrictModeFlagName = "strict-mode"
+ TerragruntStrictModeEnvName = "TERRAGRUNT_STRICT_MODE"
+
+ TerragruntStrictControlFlagName = "strict-control"
+ TerragruntStrictControlEnvName = "TERRAGRUNT_STRICT_CONTROL"
+
  // Terragrunt Provider Cache related flags/envs
 
  TerragruntProviderCacheFlagName = "terragrunt-provider-cache"
@@ -456,6 +465,22 @@ func NewGlobalFlags(opts *options.TerragruntOptions) cli.Flags {
  Destination: &opts.DisableCommandValidation,
  Usage: "When this flag is set, Terragrunt will not validate the terraform command.",
  },
+ // Strict Mode flags
+ &cli.BoolFlag{
+ Name: TerragruntStrictModeFlagName,
+ EnvVar: TerragruntStrictModeEnvName,
+ Destination: &opts.StrictMode,
+ Usage: "Enables strict mode for Terragrunt. For more information, see https://terragrunt.gruntwork.io/docs/reference/strict-mode .",
+ },
+ &cli.SliceFlag[string]{
+ Name: TerragruntStrictControlFlagName,
+ EnvVar: TerragruntStrictControlEnvName,
+ Destination: &opts.StrictControls,
+ Usage: "Enables specific strict controls. For a list of available controls, see https://terragrunt.gruntwork.io/docs/reference/strict-mode .",
+ Action: func(ctx *cli.Context, val []string) error {
+ return strict.StrictControls.ValidateControlNames(val)
+ },
+ },
  // Terragrunt Provider Cache flags
  &cli.BoolFlag{
  Name: TerragruntProviderCacheFlagName,

cli/deprecated_commands.go

@@ -6,6 +6,7 @@ import (
  "strings"
 
  runall "github.com/gruntwork-io/terragrunt/cli/commands/run-all"
+ "github.com/gruntwork-io/terragrunt/internal/strict"
  "github.com/gruntwork-io/terragrunt/options"
  "github.com/gruntwork-io/terragrunt/pkg/cli"
  "github.com/gruntwork-io/terragrunt/terraform"
@@ -47,13 +48,26 @@ func replaceDeprecatedCommandFunc(terragruntCommandName, terraformCommandName st
  deprecatedCommandName := ctx.Command.Name
  newCommandFriendly := fmt.Sprintf("terragrunt %s %s", terragruntCommandName, strings.Join(args, " "))
 
- opts.Logger.Warnf(
- "'%s' is deprecated. Running '%s' instead. Please update your workflows to use '%s', as '%s' may be removed in the future!\n",
- deprecatedCommandName,
- newCommandFriendly,
- newCommandFriendly,
- deprecatedCommandName,
- )
+ control, ok := strict.GetStrictControl(deprecatedCommandName)
+ if ok {
+ warning, err := control.Evaluate(opts)
+ if err != nil {
+ return err //nolint:wrapcheck
+ }
+
+ opts.Logger.Warn(warning)
+
+ } else { //nolint:wsl,whitespace
+ // This else clause should never be hit, as all the commands above are accounted for.
+ // This might be missed accidentally in the future, so we'll keep it for safety.
+ opts.Logger.Warnf(
+ "'%s' is deprecated. Running '%s' instead. Please update your workflows to use '%s', as '%s' may be removed in the future!\n", //nolint:lll
+ deprecatedCommandName,
+ newCommandFriendly,
+ newCommandFriendly,
+ deprecatedCommandName,
+ )
+ }
 
  err := command.Run(ctx, args)
 

docs/_docs/04_reference/strict-mode.md

@@ -0,0 +1,116 @@
+---
+layout: collection-browser-doc
+title: Strict Mode
+category: reference
+categories_url: reference
+excerpt: >-
+ Opt-in to strict mode to avoid deprecated features and ensure your code is future-proof.
+tags: ["CLI"]
+order: 404
+nav_title: Documentation
+nav_title_link: /docs/
+---
+
+Terragrunt supports operating in a mode referred to as "Strict Mode".
+
+Strict Mode is a set of controls that can be enabled to ensure that your Terragrunt usage is future-proof
+by making deprecated features throw errors instead of warnings. This can be useful when you want to ensure
+that your Terragrunt code is up-to-date with the latest conventions to avoid breaking changes in
+future versions of Terragrunt.
+
+Whenever possible, Terragrunt will initially provide you with a warning when you use a deprecated feature, without throwing an error.
+However, in Strict Mode, these warnings will be converted to errors, which will cause the Terragrunt command to fail.
+
+## Controlling Strict Mode
+
+The simplest way to enable strict mode is to set the `TERRAGRUNT_STRICT_MODE` environment variable to `true`.
+
+This will enable strict mode for all Terragrunt commands, for all strict mode controls.
+
+```bash
+$ terragrunt plan-all
+15:26:08.585 WARN The `plan-all` command is deprecated and will be removed in a future version. Use `terragrunt run-all plan` instead.
+```
+
+```bash
+$ TERRAGRUNT_STRICT_MODE='true' tg plan-all
+15:26:23.685 ERROR The `plan-all` command is no longer supported. Use `terragrunt run-all plan` instead.
+```
+
+Instead of setting this environment variable, you can also enable strict mode for specific controls by setting the `TERRAGRUNT_STRICT_CONTROL`
+environment variable to a value that's specific to a particular strict control.
+This can allow you to gradually increase your confidence in the future compatibility of your Terragrunt usage.
+
+```bash
+$ TERRAGRUNT_STRICT_CONTROL='apply-all' terragrunt plan-all
+15:26:08.585 WARN The `plan-all` command is deprecated and will be removed in a future version. Use `terragrunt run-all plan` instead.
+```
+
+```bash
+$ TERRAGRUNT_STRICT_CONTROL='plan-all' terragrunt plan-all
+15:26:23.685 ERROR The `plan-all` command is no longer supported. Use `terragrunt run-all plan` instead.
+```
+
+You can also enable multiple strict controls at once with a comma delimited list.
+
+```bash
+$ TERRAGRUNT_STRICT_CONTROL='plan-all,apply-all' bash -c 'terragrunt plan-all; terragrunt apply-all'
+15:26:46.521 ERROR The `plan-all` command is no longer supported. Use `terragrunt run-all plan` instead.
+15:26:46.521 ERROR Unable to determine underlying exit code, so Terragrunt will exit with error code 1
+15:26:46.564 ERROR The `apply-all` command is no longer supported. Use `terragrunt run-all apply` instead.
+15:26:46.564 ERROR Unable to determine underlying exit code, so Terragrunt will exit with error code 1
+```
+
+## Strict Mode Controls
+
+The following strict mode controls are available:
+
+- [spin-up](#spin-up)
+- [tear-down](#tear-down)
+- [plan-all](#plan-all)
+- [apply-all](#apply-all)
+- [destroy-all](#destroy-all)
+- [output-all](#output-all)
+- [validate-all](#validate-all)
+
+### spin-up
+
+Throw an error when using the `spin-up` command.
+
+**Reason**: The `spin-up` command is deprecated and will be removed in a future version. Use `terragrunt run-all apply` instead.
+
+### tear-down
+
+Throw an error when using the `tear-down` command.
+
+**Reason**: The `tear-down` command is deprecated and will be removed in a future version. Use `terragrunt run-all destroy` instead.
+
+### plan-all
+
+Throw an error when using the `plan-all` command.
+
+**Reason**: The `plan-all` command is deprecated and will be removed in a future version. Use `terragrunt run-all plan` instead.
+
+### apply-all
+
+Throw an error when using the `apply-all` command.
+
+**Reason**: The `apply-all` command is deprecated and will be removed in a future version. Use `terragrunt run-all apply` instead.
+
+### destroy-all
+
+Throw an error when using the `destroy-all` command.
+
+**Reason**: The `destroy-all` command is deprecated and will be removed in a future version. Use `terragrunt run-all destroy` instead.
+
+### output-all
+
+Throw an error when using the `output-all` command.
+
+**Reason**: The `output-all` command is deprecated and will be removed in a future version. Use `terragrunt run-all output` instead.
+
+### validate-all
+
+Throw an error when using the `validate-all` command.
+
+**Reason**: The `validate-all` command is deprecated and will be removed in a future version. Use `terragrunt run-all validate` instead.

internal/strict/strict.go

@@ -0,0 +1,121 @@
+// Package strict provides utilities used by Terragrunt to support a "strict" mode.
+// By default strict mode is disabled, but when enabled, any breaking changes
+// to Terragrunt behavior that is not backwards compatible will result in an error.
+//
+// Note that any behavior outlined here should be documented in /docs/_docs/04_reference/strict-mode.md
+//
+// That is how users will know what to expect when they enable strict mode, and how to customize it.
+package strict
+
+import (
+ "errors"
+ "strings"
+
+ "github.com/gruntwork-io/terragrunt/options"
+)
+
+// Control represents a control that can be enabled or disabled in strict mode.
+// When the control is enabled, Terragrunt will behave in a way that is not backwards compatible.
+type Control struct {
+ // Error is the error that will be returned when the control is enabled.
+ Error error
+ // Warning is a warning that will be logged when the control is not enabled.
+ Warning string
+}
+
+const (
+ // SpinUp is the control that prevents the deprecated `spin-up` command from being used.
+ SpinUp = "spin-up"
+ // TearDown is the control that prevents the deprecated `tear-down` command from being used.
+ TearDown = "tear-down"
+ // PlanAll is the control that prevents the deprecated `plan-all` command from being used.
+ PlanAll = "plan-all"
+ // ApplyAll is the control that prevents the deprecated `apply-all` command from being used.
+ ApplyAll = "apply-all"
+ // DestroyAll is the control that prevents the deprecated `destroy-all` command from being used.
+ DestroyAll = "destroy-all"
+ // OutputAll is the control that prevents the deprecated `output-all` command from being used.
+ OutputAll = "output-all"
+ // ValidateAll is the control that prevents the deprecated `validate-all` command from being used.
+ ValidateAll = "validate-all"
+)
+
+// GetStrictControl returns the strict control with the given name.
+func GetStrictControl(name string) (Control, bool) {
+ control, ok := StrictControls[name]
+
+ return control, ok
+}
+
+// Evaluate returns a warning if the control is not enabled, and an error if the control is enabled.
+func (control Control) Evaluate(opts *options.TerragruntOptions) (string, error) {
+ if opts.StrictMode {
+ return "", control.Error
+ }
+
+ for _, controlName := range opts.StrictControls {
+ strictControl, ok := StrictControls[controlName]
+ if !ok {
+ // This should never happen, but if it does, it's a bug in Terragrunt.
+ // The slice of StrictControls should be validated before they're used.
+ return "", errors.New("Invalid strict control: " + controlName)
+ }
+
+ if strictControl == control {
+ return "", control.Error
+ }
+ }
+
+ return control.Warning, nil
+}
+
+type Controls map[string]Control
+
+//nolint:lll,gochecknoglobals,stylecheck
+var StrictControls = Controls{
+ SpinUp: {
+ Error: errors.New("The `spin-up` command is no longer supported. Use `terragrunt run-all apply` instead."),
+ Warning: "The `spin-up` command is deprecated and will be removed in a future version. Use `terragrunt run-all apply` instead.",
+ },
+ TearDown: {
+ Error: errors.New("The `tear-down` command is no longer supported. Use `terragrunt run-all destroy` instead."),
+ Warning: "The `tear-down` command is deprecated and will be removed in a future version. Use `terragrunt run-all destroy` instead.",
+ },
+ PlanAll: {
+ Error: errors.New("The `plan-all` command is no longer supported. Use `terragrunt run-all plan` instead."),
+ Warning: "The `plan-all` command is deprecated and will be removed in a future version. Use `terragrunt run-all plan` instead.",
+ },
+ ApplyAll: {
+ Error: errors.New("The `apply-all` command is no longer supported. Use `terragrunt run-all apply` instead."),
+ Warning: "The `apply-all` command is deprecated and will be removed in a future version. Use `terragrunt run-all apply` instead.",
+ },
+ DestroyAll: {
+ Error: errors.New("The `destroy-all` command is no longer supported. Use `terragrunt run-all destroy` instead."),
+ Warning: "The `destroy-all` command is deprecated and will be removed in a future version. Use `terragrunt run-all destroy` instead.",
+ },
+ OutputAll: {
+ Error: errors.New("The `output-all` command is no longer supported. Use `terragrunt run-all output` instead."),
+ Warning: "The `output-all` command is deprecated and will be removed in a future version. Use `terragrunt run-all output` instead.",
+ },
+ ValidateAll: {
+ Error: errors.New("The `validate-all` command is no longer supported. Use `terragrunt run-all validate` instead."),
+ Warning: "The `validate-all` command is deprecated and will be removed in a future version. Use `terragrunt run-all validate` instead.",
+ },
+}
+
+func (controls Controls) ValidateControlNames(strictControlNames []string) error {
+ invalidControls := []string{}
+
+ for _, controlName := range strictControlNames {
+ _, ok := controls[controlName]
+ if !ok {
+ invalidControls = append(invalidControls, controlName)
+ }
+ }
+
+ if len(invalidControls) > 0 {
+ return errors.New("Invalid strict controls: " + strings.Join(invalidControls, ", "))
+ }
+
+ return nil
+}