ruby-terraform 0.65.0.pre.15 → 1.0.0.pre.1

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

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