ruby-terraform 0.65.0.pre.12 → 1.0.0

data/lib/ruby_terraform/commands/show.rb

@@ -1,17 +1,39 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform show+ command which reads and outputs a Terraform
+    # state or plan file in a human-readable form. If no path is specified, the
+    # current state will be shown.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {Show} via {#execute}, the following
+    # options are supported:
+    #
+    # * +:path+: the path to a state file or plan to show.
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    # * +:no_color+: whether or not the output from the command should be in
+    #   color; defaults to +false+.
+    # * +:json+: if +true+, outputs the Terraform plan or state in a
+    #   machine-readable form; defaults to +false+.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::Show.new.execute
+    #
     class Show < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[show]
       end
 
+      # @!visibility private
       def options
         %w[
           -json
@@ -19,8 +41,9 @@ module RubyTerraform
         ] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
-        [parameters[:path] || parameters[:directory]]
+        [parameters[:path]]
       end
     end
   end

data/lib/ruby_terraform/commands/state_list.rb

@@ -1,19 +1,70 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform state list+ command which lists resources in the
+    # Terraform state.
+    #
+    # This command lists resource instances in the Terraform state. The address
+    # option can be used to filter the instances by resource or module. If no
+    # pattern is given, all resource instances are listed.
+    #
+    # The addresses must either be module addresses or absolute resource
+    # addresses, such as:
+    #
+    # * +aws_instance.example+
+    # * +module.example+
+    # * +module.example.module.child+
+    # * +module.example.aws_instance.example+
+    #
+    # An {RubyTerraform::Errors::ExecutionError} will be raised if any of the
+    # resources or modules given as filter addresses do not exist in the state.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {StateList} via {#execute}, the following
+    # options are supported:
+    #
+    # * +:address+: the module address or absolute resource address to filter
+    #   by; if both +:address+ and +:addresses+ are provided, all addresses will
+    #   be passed to Terraform.
+    # * +:addresses+: an array of module addresses or absolute resource
+    #   addresses to filter by; if both +:address+ and +:addresses+ are
+    #   provided, all addresses will be passed to Terraform.
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    # * +:state+: the path to a Terraform state file to use to look up
+    #   Terraform-managed resources; by default, Terraform will consult the
+    #   state of the currently-selected workspace.
+    # * +:id+: when provided, filters the results to include only instances
+    #   whose resource types have an attribute named "id" whose value equals the
+    #   given id string.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::StateList.new.execute
+    #
     class StateList < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[state list]
       end
 
+      # @!visibility private
+      def options
+        %w[
+          -state
+          -id
+        ] + super
+      end
+
+      # @!visibility private
       def arguments(parameters)
-        [parameters[:address]]
+        [parameters[:address], parameters[:addresses]]
       end
     end
   end

data/lib/ruby_terraform/commands/state_move.rb

@@ -1,34 +1,92 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform state mv+ command which moves an item in the state.
+    #
+    # This command will move an item matched by the address given to the
+    # destination address. This command can also move to a destination address
+    # in a completely different state file.
+    #
+    # This can be used for simple resource renaming, moving items to and from
+    # a module, moving entire modules, and more. And because this command can
+    # also move data to a completely new state, it can also be used for
+    # refactoring one configuration into multiple separately managed Terraform
+    # configurations.
+    #
+    # This command will output a backup copy of the state prior to saving any
+    # changes. The backup cannot be disabled. Due to the destructive nature
+    # of this command, backups are required.
+    #
+    # If you're moving an item to a different state file, a backup will be
+    # created for each state file.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {StateMove} via {#execute}, the following
+    # options are supported:
+    #
+    # * +:source+: the source address of the item to move; required.
+    # * +:destination+: the destination address to move the item to; required.
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    # * +:dry_run+: when +true+, prints out what would've been moved but doesn't
+    #   actually move anything; defaults to +false+.
+    # * +:backup+: the path where Terraform should write the backup for the
+    #   original state; this can't be disabled; if not set, Terraform will write
+    #   it to the same path as the state file with a +".backup"+ extension.
+    # * +:backup_out+: the path where Terraform should write the backup for the
+    #   destination state; this can't be disabled; if not set, Terraform will
+    #   write it to the same path as the destination state file with a
+    #   +".backup"+ extension; this only needs to be specified if +:state_out+
+    #   is set to a different path than +:state+.
+    # * +: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 the source state file; defaults to the configured
+    #   backend, or +"terraform.tfstate"+.
+    # * +:state_out+: the path to the destination state file to write to; if
+    #   this isn't specified, the source state file will be used; this can be a
+    #   new or existing path.
+    # * +: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::StateMove.new.execute(
+    #     source: 'packet_device.worker',
+    #     destination: 'packet_device.helper')
+    #
     class StateMove < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[state mv]
       end
 
+      # @!visibility private
       def options
         %w[
+          -dry-run
           -backup
           -backup-out
+          -lock
+          -lock-timeout
           -state
           -state-out
           -ignore-remote-version
         ] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
         [parameters[:source], parameters[:destination]]
       end
-
-      def parameter_overrides(parameters)
-        { backup: parameters[:no_backup] ? '-' : parameters[:backup] }
-      end
     end
   end
 end

data/lib/ruby_terraform/commands/state_pull.rb

@@ -1,13 +1,35 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform state pull+ command which pulls the state from its
+    # location, upgrades the local copy, and outputs it to stdout.
+    #
+    # This command "pulls" the current state and outputs it to stdout. As part
+    # of this process, Terraform will upgrade the state format of the local copy
+    # to the current version.
+    #
+    # The primary use of this is for state stored remotely. This command will
+    # still work with local state but is less useful for this.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {StatePull} via {#execute}, the following
+    # options are supported:
+    #
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::StatePull.new.execute
+    #
     class StatePull < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[state pull]
       end

data/lib/ruby_terraform/commands/state_push.rb

@@ -1,21 +1,67 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform state push+ command which updates remote state from
+    # a local state file.
+    #
+    # This command "pushes" a local state and overwrites remote state with a
+    # local state file. The command will protect you against writing
+    # an older serial or a different state file lineage unless you pass +true+
+    # for the +:force+ option.
+    #
+    # This command works with local state (it will overwrite the local state),
+    # but is less useful for this use case.
+    #
+    # If +:path+ is +"-"+, then this command will read the state to push from
+    # stdin. Data from stdin is not streamed to the backend: it is loaded
+    # completely (until pipe close), verified, and then pushed.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {StatePush} via {#execute}, the following
+    # options are supported:
+    #
+    # * +:path+: the path to the state file to push; when passed +"-"+ will
+    #   read state from standard input.
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    # * +:force+: when +true+, writes the state even if lineages don't match or
+    #   the remote serial is higher; 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"+.
+    # * +: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::StatePush.new.execute(
+    #     path: 'some/statefile.tfstate')
+    #
     class StatePush < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[state push]
       end
 
+      # @!visibility private
       def options
-        %w[-ignore-remote-version] + super
+        %w[
+          -force
+          -lock
+          -lock-timeout
+          -ignore-remote-version
+        ] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
         [parameters[:path]]
       end

data/lib/ruby_terraform/commands/state_remove.rb

@@ -1,31 +1,79 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform state rm+ command which removes one or more items
+    # from the Terraform state, causing Terraform to "forget" those items
+    #  without first destroying them in the remote system.
+    #
+    # This command removes one or more resource instances from the Terraform
+    # state based on the addresses given. You can view and list the available
+    # instances with {StateList}.
+    #
+    # If you give the address of an entire module then all of the instances in
+    # that module and any of its child modules will be removed from the state.
+    #
+    # If you give the address of a resource that has "count" or "for_each" set,
+    # all of the instances of that resource will be removed from the state.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {StateRemove} via {#execute}, the following
+    # options are supported:
+    #
+    # * +:address+: the module address or absolute resource address of the
+    #   resource instance to remove; required unless +:addresses+ is supplied;
+    #   if both +:address+ and +:addresses+ are provided, all addresses will be
+    #   passed to Terraform.
+    # * +:addresses+: an array of module addresses or absolute resource
+    #   addresses of the resource instances to remove; required unless
+    #   +:address+ is supplied; if both +:address+ and +:addresses+ are
+    #   provided, all addresses will be passed to Terraform.
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    # * +:dry+run+: when +true+, prints out what would've been removed but
+    #   doesn't actually remove anything; defaults to +false+.
+    # * +:backup+: the path where Terraform should write the backup state.
+    # * +: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 the state file to update; defaults to the current
+    #   workspace 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::StateRemove.new.execute(
+    #     address: 'packet_device.worker')
+    #
     class StateRemove < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[state rm]
       end
 
+      # @!visibility private
       def options
         %w[
+          -dry-run
           -backup
+          -lock
+          -lock-timeout
           -state
           -ignore-remote-version
         ] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
-        [parameters[:address]]
-      end
-
-      def parameter_overrides(parameters)
-        { backup: parameters[:no_backup] ? '-' : parameters[:backup] }
+        [parameters[:address], parameters[:addresses]]
       end
     end
   end

data/lib/ruby_terraform/commands/state_replace_provider.rb

@@ -1,17 +1,53 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform state replace-provider+ command which replaces
+    # provider for resources in the Terraform state.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {StateReplaceProvider} via {#execute}, the
+    # following options are supported:
+    #
+    # * +:from+: the fully qualified name of the provider to be replaced;
+    #   required.
+    # * +:to+: the fully qualified name of the provider to replace with;
+    #   required.
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    # * +:auto_approve+: if +true+, skips interactive approval; defaults to
+    #   +false+.
+    # * +:backup+: the path where Terraform should write the backup for the
+    # 	state file; this can't be disabled; if not set, Terraform will write it
+    # 	to the same path as the state file with a ".backup" extension.
+    # * +: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 the state file to update; defaults to the current
+    #   workspace 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::StateReplaceProvider.new.execute(
+    #     from: 'hashicorp/aws',
+    #     to: 'registry.acme.corp/acme/aws')
+    #
     class StateReplaceProvider < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[state replace-provider]
       end
 
+      # @!visibility private
       def options
         %w[
           -auto-approve
@@ -23,13 +59,10 @@ module RubyTerraform
         ] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
         [parameters[:from], parameters[:to]]
       end
-
-      def parameter_overrides(parameters)
-        { backup: parameters[:no_backup] ? '-' : parameters[:backup] }
-      end
     end
   end
 end