ruby-terraform 0.65.0.pre.12 → 1.0.0

data/lib/ruby_terraform/commands/state_show.rb

@@ -1,21 +1,45 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform state show+ command which shows the attributes of a
+    # resource in the Terraform state.
+    #
+    # This command shows the attributes of a single resource in the Terraform
+    # state. The +:address+ argument must be used to specify a single resource.
+    # You can view the list of available resources with {StateList}.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {StateShow} via {#execute}, the following
+    # options are supported:
+    #
+    # * +:address+: the module address or absolute resource address of the
+    #   resource instance to show; required.
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::StateShow.new.execute(
+    #     address: 'packet_device.worker')
+    #
     class StateShow < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[state show]
       end
 
+      # @!visibility private
       def options
         %w[-state] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
         [parameters[:address]]
       end

data/lib/ruby_terraform/commands/taint.rb

@@ -1,17 +1,76 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform taint+ command which marks a resource instance as not
+    # fully functional.
+    #
+    # Terraform uses the term "tainted" to describe a resource instance which
+    # may not be fully functional, either because its creation partially failed
+    # or because you've manually marked it as such using this command.
+    #
+    # This will not modify your infrastructure directly, but subsequent
+    # Terraform plans will include actions to destroy the remote object and
+    # create a new object to replace it.
+    #
+    # You can remove the "taint" state from a resource instance using the
+    # {Untaint} command.
+    #
+    # The address is in the usual resource address syntax, such as:
+    #
+    # * +aws_instance.foo+
+    # * <tt>aws_instance.bar[1]</tt>
+    # * +module.foo.module.bar.aws_instance.baz+
+    #
+    # Use your shell's quoting or escaping syntax to ensure that the address
+    # will reach Terraform correctly, without any special interpretation.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {Taint} via {#execute}, the following
+    # options are supported:
+    #
+    # * +:address+: the module address or absolute resource address of the
+    #   resource instance to taint; required.
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    # * +:allow_missing+: if +true+, the command will succeed (i.e., will not
+    #   throw an {RubyTerraform::Errors::ExecutionError}) even if the resource
+    #   is missing; defaults to +false+.
+    # * +:backup+: the path to backup the existing state file before modifying;
+    #   defaults to the +:state_out+ path with +".backup"+ extension; set
+    #   +:no_backup+ to +true+ to skip backups entirely.
+    # * +:lock+: when +true+, locks the state file when locking is supported;
+    #   when +false+, does not lock the state file; defaults to +true+.
+    # * +:lock_timeout+: the duration to retry a state lock; defaults to +"0s"+.
+    # * +:no_backup+: when +true+, no backup file will be written; defaults to
+    #   +false+.
+    # * +:state+: the path to the state file from which to read state and in
+    #   which to store state (unless +:state_out+ is specified); defaults to
+    #   +"terraform.tfstate"+.
+    # * +:state_out+: the path to write state to that is different than
+    #   +:state+; this can be used to preserve the old state.
+    # * +:ignore_remote_version+: whether or not to continue even if remote and
+    #   local Terraform versions are incompatible; this may result in an
+    #   unusable workspace, and should be used with extreme caution; defaults to
+    #   +false+.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::Taint.new.execute(
+    #     address: 'aws_security_group.allow_all')
+    #
     class Taint < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[taint]
       end
 
+      # @!visibility private
       def options
         %w[
           -allow-missing
@@ -24,10 +83,12 @@ module RubyTerraform
         ] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
         [parameters[:address]]
       end
 
+      # @!visibility private
       def parameter_overrides(parameters)
         { backup: parameters[:no_backup] ? '-' : parameters[:backup] }
       end

data/lib/ruby_terraform/commands/untaint.rb

@@ -1,17 +1,68 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform untaint+ command which removes the 'tainted' state
+    # from a resource instance.
+    #
+    # Terraform uses the term "tainted" to describe a resource instance
+    # which may not be fully functional, either because its creation partially
+    # failed or because you've manually marked it as such using the {Taint}
+    # command.
+    #
+    # This command removes that state from a resource instance, causing
+    # Terraform to see it as fully-functional and not in need of replacement.
+    #
+    # This will not modify your infrastructure directly. It only avoids
+    # Terraform planning to replace a tainted instance in a future operation.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {Untaint} via {#execute}, the following
+    # options are supported:
+    #
+    # * +:name+: the name of the resource instance to untaint; required.
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    # * +:allow_missing+: if +true+, the command will succeed (i.e., will not
+    #   throw an {RubyTerraform::Errors::ExecutionError}) even if the resource
+    #   is missing; defaults to +false+.
+    # * +:backup+: the path to backup the existing state file before modifying;
+    #   defaults to the +:state_out+ path with +".backup"+ extension; set
+    #   +:no_backup+ to +true+ to skip backups entirely.
+    # * +:lock+: when +true+, locks the state file when locking is supported;
+    #   when +false+, does not lock the state file; defaults to +true+.
+    # * +:lock_timeout+: the duration to retry a state lock; defaults to +"0s"+.
+    # * +:no_backup+: when +true+, no backup file will be written; defaults to
+    #   +false+.
+    # * +:no_color+: whether or not the output from the command should be in
+    #   color; defaults to +false+.
+    # * +:state+: the path to the state file from which to read state and in
+    #   which to store state (unless +:state_out+ is specified); defaults to
+    #   +"terraform.tfstate"+.
+    # * +:state_out+: the path to write state to that is different than
+    #   +:state+; this can be used to preserve the old state.
+    # * +:ignore_remote_version+: whether or not to continue even if remote and
+    #   local Terraform versions are incompatible; this may result in an
+    #   unusable workspace, and should be used with extreme caution; defaults to
+    #   +false+.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::Untaint.new.execute(
+    #     name: 'aws_security_group.allow_all')
+    #
     class Untaint < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[untaint]
       end
 
+      # @!visibility private
       def options
         %w[
           -allow-missing
@@ -25,10 +76,12 @@ module RubyTerraform
         ] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
         [parameters[:name]]
       end
 
+      # @!visibility private
       def parameter_overrides(parameters)
         { backup: parameters[:no_backup] ? '-' : parameters[:backup] }
       end

data/lib/ruby_terraform/commands/validate.rb

@@ -1,17 +1,65 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform validate+ command which checks whether a
+    # configuration is valid.
+    #
+    # Validates the configuration files in a directory, referring only to the
+    # configuration and not accessing any remote services such as remote state,
+    # provider APIs, etc.
+    #
+    # Validate runs checks that verify whether a configuration is syntactically
+    # valid and internally consistent, regardless of any provided variables or
+    # existing state. It is thus primarily useful for general verification of
+    # reusable modules, including correctness of attribute names and value
+    # types.
+    #
+    # It is safe to run this command automatically, for example as a post-save
+    # check in a text editor or as a test step for a re-usable module in a CI
+    # system.
+    #
+    # Validation requires an initialized working directory with any referenced
+    # plugins and modules installed. To initialize a working directory for
+    # validation without accessing any configured remote backend, use the {Init}
+    # command passing +:backend+ as +false+.
+    #
+    # To verify configuration in the context of a particular run (a particular
+    # target workspace, input variable values, etc), use the {Plan} command
+    # instead, which includes an implied validation check.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {Validate} via {#execute}, the following
+    # options are supported:
+    #
+    # * +:directory+: the path to a directory containing terraform configuration
+    #   (deprecated in terraform 0.14, removed in terraform 0.15, use +:chdir+
+    #   instead).
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    # * +:json+: whether or not to produce output in a machine-readable JSON
+    #   format, suitable for use in text editor integrations and other automated
+    #   systems; always disables color; defaults to +false+.
+    # * +:no_color+: whether or not the output from the command should be in
+    #   color; defaults to +false+.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::Validate.new.execute(
+    #     directory: 'infra/networking')
+    #
     class Validate < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[validate]
       end
 
+      # @!visibility private
       def options
         %w[
           -json
@@ -19,13 +67,10 @@ module RubyTerraform
         ] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
         [parameters[:directory]]
       end
-
-      def parameter_defaults(_parameters)
-        { vars: {}, var_files: [] }
-      end
     end
   end
 end

data/lib/ruby_terraform/commands/workspace_delete.rb

@@ -1,17 +1,42 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform workspace delete+ command which deletes a workspace.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {WorkspaceDelete} via {#execute}, the
+    # following options are supported:
+    #
+    # * +:name+: the name of the workspace to delete; required.
+    # * +:directory+: the path to a directory containing terraform configuration
+    #   (deprecated in terraform 0.14, removed in terraform 0.15, use +:chdir+
+    #   instead).
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    # * +:force+: whether or not to remove a non-empty workspace; defaults to
+    #   +false+.
+    # * +:lock+: when +true+, locks the state file when locking is supported;
+    #   when +false+, does not lock the state file; defaults to +true+.
+    # * +:lock_timeout+: the duration to retry a state lock; defaults to +"0s"+.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::WorkspaceDelete.new.execute(
+    #     name: 'example')
+    #
     class WorkspaceDelete < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[workspace delete]
       end
 
+      # @!visibility private
       def options
         %w[
           -force
@@ -20,12 +45,9 @@ module RubyTerraform
         ] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
-        [parameters[:workspace], parameters[:directory]]
-      end
-
-      def parameter_defaults(_parameters)
-        { directory: nil }
+        [parameters[:name], parameters[:directory]]
       end
     end
   end

data/lib/ruby_terraform/commands/workspace_list.rb

@@ -1,24 +1,39 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform workspace list+ command which lists workspaces.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {WorkspaceList} via {#execute}, the
+    # following options are supported:
+    #
+    # * +:directory+: the path to a directory containing terraform configuration
+    #   (deprecated in terraform 0.14, removed in terraform 0.15, use +:chdir+
+    #   instead).
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::WorkspaceList.new.execute(
+    #     directory: 'infra/networking')
+    #
     class WorkspaceList < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[workspace list]
       end
 
+      # @!visibility private
       def arguments(parameters)
         [parameters[:directory]]
       end
-
-      def parameter_defaults(_parameters)
-        { directory: nil }
-      end
     end
   end
 end

data/lib/ruby_terraform/commands/workspace_new.rb

@@ -1,17 +1,41 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform workspace new+ command which creates a new workspace.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {WorkspaceNew} via {#execute}, the
+    # following options are supported:
+    #
+    # * +:name+: the name of the workspace to create; required.
+    # * +:directory+: the path to a directory containing terraform configuration
+    #   (deprecated in terraform 0.14, removed in terraform 0.15, use +:chdir+
+    #   instead).
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    # * +:lock+: when +true+, locks the state file when locking is supported;
+    #   when +false+, does not lock the state file; defaults to +true+.
+    # * +:lock_timeout+: the duration to retry a state lock; defaults to +"0s"+.
+    # * +:state+: the path to a state file to copy into the new workspace.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::WorkspaceNew.new.execute(
+    #     name: 'example')
+    #
     class WorkspaceNew < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[workspace new]
       end
 
+      # @!visibility private
       def options
         %w[
           -lock
@@ -20,12 +44,9 @@ module RubyTerraform
         ] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
-        [parameters[:workspace], parameters[:directory]]
-      end
-
-      def parameter_defaults(_parameters)
-        { directory: nil }
+        [parameters[:name], parameters[:directory]]
       end
     end
   end