ruby-terraform 0.65.0.pre.12 → 1.0.0

data/lib/ruby_terraform/commands.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require_relative 'commands/apply'
-require_relative 'commands/clean'
 require_relative 'commands/destroy'
 require_relative 'commands/force_unlock'
 require_relative 'commands/format'
@@ -18,7 +17,6 @@ require_relative 'commands/providers_lock'
 require_relative 'commands/providers_mirror'
 require_relative 'commands/providers_schema'
 require_relative 'commands/refresh'
-require_relative 'commands/remote_config'
 require_relative 'commands/show'
 require_relative 'commands/state_list'
 require_relative 'commands/state_move'

data/lib/ruby_terraform/commands/apply.rb

@@ -1,25 +1,94 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform apply+ command which creates or updates
+    # infrastructure according to terraform configuration files in the provided
+    # directory.
+    #
+    # By default, terraform will generate a new plan and present it for approval
+    # before taking any action. Alternatively, the command accepts a plan file
+    # created by a previous invocation, in which case terraform will take the
+    # actions described in that plan without any confirmation prompt.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {Apply} 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).
+    # * +:plan+: the path to a pre-computed plan to be applied.
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    # * +:auto_approve+: if +true+, skips interactive approval of the generated
+    #   plan before applying; 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.
+    # * +: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+.
+    # * +: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+.
+    # * +: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.
+    # * +: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.
+    # * +: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::Apply.new.execute(
+    #     directory: 'infra/networking',
+    #     vars: {
+    #       region: 'eu-central'
+    #     })
+    #
     class Apply < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[apply]
       end
 
-      def options # rubocop:disable Metrics/MethodLength
+      # rubocop:disable Metrics/MethodLength
+
+      # @!visibility private
+      def options
         %w[
+          -auto-approve
           -backup
           -compact-warnings
           -lock
           -lock-timeout
           -input
-          -auto-approve
           -no-color
           -parallelism
           -refresh
@@ -31,14 +100,19 @@ module RubyTerraform
         ] + super
       end
 
+      # rubocop:enable Metrics/MethodLength
+
+      # @!visibility private
       def arguments(parameters)
         [parameters[:plan] || 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/base.rb

@@ -7,7 +7,11 @@ require_relative '../errors'
 module RubyTerraform
   module Commands
     class Base
-      def initialize(**opts) # rubocop:disable Metrics/AbcSize
+      # rubocop:disable Metrics/AbcSize
+
+      # Constructs an instance of the command.
+      #
+      def initialize(**opts)
         @binary  = opts[:binary]  || RubyTerraform.configuration.binary
         @logger  = opts[:logger]  || RubyTerraform.configuration.logger
         @options = opts[:options] || RubyTerraform.configuration.options
@@ -16,6 +20,13 @@ module RubyTerraform
         @stderr  = opts[:stderr]  || RubyTerraform.configuration.stderr
       end
 
+      # rubocop:enable Metrics/AbcSize
+
+      # Executes the command instance.
+      #
+      # @param [Hash<String, Object>] parameters The parameters used to
+      #   invoke the command. See subclass documentation for details of
+      #   supported options.
       def execute(parameters = {})
         do_before(parameters)
         build_and_execute_command(parameters)
@@ -60,7 +71,7 @@ module RubyTerraform
           .with_option_separator('=')
           .with_appliables(@options.resolve(options, parameters))
           .with_subcommands(subcommands)
-          .with_arguments(arguments(parameters)).build
+          .with_arguments(arguments(parameters).compact.flatten).build
       end
 
       def resolve_parameters(parameters)

data/lib/ruby_terraform/commands/destroy.rb

@@ -1,25 +1,87 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform destroy+ command which destroys terraform managed
+    # infrastructure.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {Destroy} 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.
+    # * +:auto_approve+: if +true+, skips interactive approval before
+    #   destroying; defaults to +false+.
+    # * +:backup+: (legacy) 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.
+    # * +: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+.
+    # * +: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+.
+    # * +:refresh+: when +true+, updates state prior to checking for
+    #   differences; when +false+ uses locally available state; defaults to
+    #   +true+.
+    # * +:state+: (legacy) 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+: (legacy) the path to write state to that is different than
+    #   +:state+; this can be used to preserve the old state.
+    # * +: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::Destroy.new.execute(
+    #     directory: 'infra/networking',
+    #     vars: {
+    #       region: 'eu-central'
+    #     })
+    #
     class Destroy < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[destroy]
       end
 
-      def options # rubocop:disable Metrics/MethodLength
+      # rubocop:disable Metrics/MethodLength
+
+      # @!visibility private
+      def options
         %w[
+          -auto-approve
           -backup
           -compact-warnings
           -lock
           -lock-timeout
           -input
-          -auto-approve
           -no-color
           -parallelism
           -refresh
@@ -31,14 +93,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/force_unlock.rb

@@ -1,23 +1,53 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform force-unlock+ command which manually unlocks the
+    # state for the defined configuration.
+    #
+    # This will not modify your infrastructure. This command removes the lock on
+    # the state for the current workspace. The behavior of this lock is
+    # dependent on the backend being used. Local state files cannot be unlocked
+    # by another process.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {ForceUnlock} via {#execute}, the following
+    # options are supported:
+    #
+    # * +:lock_id+: the lock ID output when attempting an operation that failed
+    #   due to a lock; 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+: If +true+, does not ask for input for unlock confirmation;
+    #   defaults to +false+.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::ForceUnlock.new.execute(
+    #     lock_id: '50e844a7-ebb0-fcfd-da85-5cce5bd1ec90')
+    #
     class ForceUnlock < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[force-unlock]
       end
 
+      # @!visibility private
       def options
         %w[-force] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
-        [parameters[:lock_id]]
+        [parameters[:lock_id], parameters[:directory]]
       end
     end
   end

data/lib/ruby_terraform/commands/format.rb

@@ -1,27 +1,70 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform fmt+ command which rewrites all terraform
+    # configuration files to a canonical format.
+    #
+    # Both configuration files (.tf) and variables files (.tfvars) are updated.
+    # JSON files (.tf.json or .tfvars.json) are not modified.
+    #
+    # If +:directory+ is not specified in the parameters map then the current
+    # working directory will be used. If +:directory+ is +"-"+ then content will
+    # be read from the standard input. The given content must be in the
+    # terraform language native syntax; JSON is not supported.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {Format} 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.
+    # * +:list+: If +true+, lists files whose formatting differs; defaults to
+    #   +false+; always disabled if using standard input.
+    # * +:write+: If +true+, writes to source files; defaults to +false+; always
+    #   disabled if using standard input or +:check+ is +true+.
+    # * +:diff+: If +true+, displays diffs of formatting changes; defaults to
+    #   +false+.
+    # * +:check+: If +true+, checks if the input is formatted; if any input is
+    #   not properly formatted, an {RubyTerraform::Errors::ExecutionError} will
+    #   be thrown; defaults to +false+.
+    # * +:no_color+: whether or not the output from the command should be in
+    #   color; defaults to +false+.
+    # * +:recursive+: If +true+, also processes files in subdirectories;
+    #   defaults to +false+ such that only the provided +:directory+ is
+    #   processed.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::Format.new.execute(
+    #     directory: 'infra/networking')
     class Format < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[fmt]
       end
 
+      # @!visibility private
       def options
         %w[
           -list
           -write
           -diff
           -check
+          -no-color
           -recursive
         ] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
         [parameters[:directory]]
       end

data/lib/ruby_terraform/commands/get.rb

@@ -1,17 +1,49 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform get+ command which downloads and installs modules
+    # needed for the given configuration.
+    #
+    # This recursively downloads all modules needed, such as modules imported by
+    # the root and so on. If a module is already downloaded, it will not be
+    # redownloaded or checked for updates unless +:update+ is +true+.
+    #
+    # Module installation also happens automatically by default as part of
+    # the {Init} command, so you should rarely need to run this
+    # command separately.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {Get} 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.
+    # * +:update+: if +true+, checks already-downloaded modules for available
+    #   updates and installs the newest versions available; 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::Get.new.execute(
+    #     directory: 'infra/networking')
+    #
     class Get < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[get]
       end
 
+      # @!visibility private
       def options
         %w[
           -no-color
@@ -19,6 +51,7 @@ module RubyTerraform
         ] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
         [parameters[:directory]]
       end