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

data/lib/ruby_terraform/commands/output.rb

@@ -2,7 +2,7 @@
 
 require 'stringio'
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
@@ -34,7 +34,7 @@ module RubyTerraform
     #     name: 'vpc_id')
     #
     class Output < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
       # @!visibility private
       def stdout

data/lib/ruby_terraform/commands/plan.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
@@ -17,7 +17,9 @@ module RubyTerraform
     # When executing an instance of {Plan} via {#execute}, the following
     # options are supported:
     #
-    # * +:plan+: the path to output the plan if it should be saved to a file.
+    # * +: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.
     # * +:compact_warnings+: when +true+, if terraform produces any warnings
@@ -39,6 +41,7 @@ module RubyTerraform
     #   color; defaults to +false+.
     # * +:parallelism+: the number of parallel resource operations; defaults to
     #   +10+.
+    # * +:plan+: the path to output the plan if it should be saved to a file.
     # * +:refresh+: when +true+, updates state prior to checking for
     #   differences; when +false+ uses locally available state; defaults to
     #   +true+; this has no effect when +:plan+ is provided.
@@ -64,7 +67,7 @@ module RubyTerraform
     #     })
     #
     class Plan < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
       # @!visibility private
       def subcommands

data/lib/ruby_terraform/commands/providers.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
@@ -18,6 +18,9 @@ module RubyTerraform
     # When executing an instance of {Plan} 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.
     #
@@ -25,14 +28,17 @@ module RubyTerraform
     #   RubyTerraform::Commands::Providers.new.execute
     #
     class Providers < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
       # @!visibility private
       def subcommands
         %w[providers]
       end
 
-      # @todo Add directory argument
+      # @!visibility private
+      def arguments(parameters)
+        [parameters[:directory]]
+      end
     end
   end
 end

data/lib/ruby_terraform/commands/providers_lock.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
@@ -31,8 +31,12 @@ module RubyTerraform
     # When executing an instance of {ProvidersLock} via {#execute}, the
     # following options are supported:
     #
-    # * +:providers+: the provider source addresses for which the lock file
-    #   should be updated.
+    # * +:provider+: the provider source address for which the lock file
+    #   should be updated; if both +:provider+ and +:providers+ are provided,
+    #   all providers will be passed to Terraform.
+    # * +:providers+: an array of provider source addresses for which the lock
+    #   file should be updated; if both +:provider+ and +:providers+ are
+    #   provided, all providers will be passed to Terraform.
     # * +:chdir+: the path of a working directory to switch to before executing
     #   the given subcommand.
     # * +:fs_mirror+: if provided, consults the given filesystem mirror
@@ -65,10 +69,10 @@ module RubyTerraform
     #   RubyTerraform::Commands::ProvidersLock.new.execute(
     #     fs_mirror: "/usr/local/terraform/providers",
     #     platforms: ["windows_amd64", "darwin_amd64", "linux_amd64"],
-    #     providers: "tf.example.com/ourcompany/ourplatform")
+    #     provider: "tf.example.com/ourcompany/ourplatform")
     #
     class ProvidersLock < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
       # @!visibility private
       def subcommands
@@ -85,9 +89,8 @@ module RubyTerraform
       end
 
       # @!visibility private
-      # @todo Flatten arguments array to allow array of providers.
       def arguments(parameters)
-        [parameters[:providers]]
+        [parameters[:provider], parameters[:providers]]
       end
     end
   end

data/lib/ruby_terraform/commands/providers_mirror.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
@@ -40,12 +40,12 @@ module RubyTerraform
     #   are provided, all platforms will be passed to Terraform.
     #
     # @example Basic Invocation
-    #   RubyTerraform::Commands::PlatformsMirror.new.execute(
+    #   RubyTerraform::Commands::ProvidersMirror.new.execute(
     #     directory: './plugins',
     #     platforms: ["windows_amd64", "darwin_amd64", "linux_amd64"])
     #
     class ProvidersMirror < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
       # @!visibility private
       def subcommands

data/lib/ruby_terraform/commands/providers_schema.rb

@@ -1,21 +1,40 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform providers schema+ command which prints out a json
+    # representation of the schemas for all providers used in the current
+    # configuration.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {ProvidersSchema} 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::ProvidersSchema.new.execute(
+    #     directory: 'infra/networking')
+    #
     class ProvidersSchema < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[providers schema]
       end
 
+      # @!visibility private
       def options
         %w[-json] + super
       end
 
+      # @!visibility private
       def parameter_overrides(_parameters)
         # Terraform 0.15 - at this time, the -json flag is a required option.
         { json: true }

data/lib/ruby_terraform/commands/refresh.rb

@@ -1,18 +1,80 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform refresh+ command which updates the state file of your
+    # infrastructure with metadata that matches the physical resources they are
+    # tracking.
+    #
+    # This will not modify your infrastructure, but it can modify your state
+    # file to update metadata. This metadata might cause new changes to occur
+    # when you generate a plan or call apply next.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {Refresh} 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.
+    # * +: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 (legacy).
+    # * +:compact_warnings+: when +true+, if terraform produces any warnings
+    #   that are not accompanied by errors, they are shown in a more compact
+    #   form that includes only the summary messages; defaults to +false+.
+    # * +:input+: when +false+, will not ask for input for variables not
+    #   directly set; defaults to +true+.
+    # * +: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+ (legacy).
+    # * +:no_color+: whether or not the output from the command should be in
+    #   color; defaults to +false+.
+    # * +:parallelism+: the number of parallel resource operations; defaults to
+    #   +10+.
+    # * +: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"+ (legacy).
+    # * +:state_out+: the path to write state to that is different than
+    #   +:state+; this can be used to preserve the old state (legacy).
+    # * +:target+: the address of a resource to target; if both +:target+ and
+    #   +:targets+ are provided, all targets will be passed to terraform.
+    # * +:targets+: an array of resource addresses to target; if both +:target+
+    #   and +:targets+ are provided, all targets will be passed to terraform.
+    # * +:vars+: a map of variables to be passed to the terraform configuration.
+    # * +:var_file+: the path to a terraform var file; if both +:var_file+ and
+    #   +:var_files+ are provided, all var files will be passed to terraform.
+    # * +:var_files+: an array of paths to terraform var files; if both
+    #   +:var_file+ and +:var_files+ are provided, all var files will be passed
+    #   to terraform.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::Refresh.new.execute(
+    #     directory: 'infra/networking',
+    #     vars: {
+    #       region: 'eu-central'
+    #     })
+    #
     class Refresh < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[refresh]
       end
 
-      def options # rubocop:disable Metrics/MethodLength
+      # rubocop:disable Metrics/MethodLength
+
+      # @!visibility private
+      def options
         %w[
           -backup
           -compact-warnings
@@ -29,14 +91,19 @@ module RubyTerraform
         ] + super
       end
 
+      # rubocop:enable Metrics/MethodLength
+
+      # @!visibility private
       def arguments(parameters)
         [parameters[:directory]]
       end
 
+      # @!visibility private
       def parameter_defaults(_parameters)
         { vars: {}, var_files: [], targets: [] }
       end
 
+      # @!visibility private
       def parameter_overrides(parameters)
         { backup: parameters[:no_backup] ? '-' : parameters[:backup] }
       end

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