ruby-terraform 0.65.0.pre.10 → 0.65.0.pre.15

data/lib/ruby_terraform/commands/apply.rb

@@ -5,14 +5,83 @@ require_relative '../options/common'
 
 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 directory containing terraform configuration;
+    #   required unless +:plan+ is provided.
+    # * +:plan+: the path to a pre-computed plan to be applied;
+    #   required unless +:directory+ is provided.
+    # * +: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
 
+      # @!visibility private
       def subcommands
         %w[apply]
       end
 
-      def options # rubocop:disable Metrics/MethodLength
+      # rubocop:disable Metrics/MethodLength
+
+      # @!visibility private
+      def options
         %w[
           -backup
           -compact-warnings
@@ -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

@@ -3,22 +3,27 @@
 require 'lino'
 
 require_relative '../errors'
-require_relative '../options/factory'
 
 module RubyTerraform
   module Commands
     class Base
-      def initialize(
-        binary: nil, logger: nil, stdin: nil, stdout: nil, stderr: nil
-      )
-        @binary = binary || RubyTerraform.configuration.binary
-        @logger = logger || RubyTerraform.configuration.logger
-        @stdin = stdin || RubyTerraform.configuration.stdin
-        @stdout = stdout || RubyTerraform.configuration.stdout
-        @stderr = stderr || RubyTerraform.configuration.stderr
-        initialize_command
+      # 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
+        @stdin   = opts[:stdin]   || RubyTerraform.configuration.stdin
+        @stdout  = opts[:stdout]  || RubyTerraform.configuration.stdout
+        @stderr  = opts[:stderr]  || RubyTerraform.configuration.stderr
       end
 
+      # rubocop:enable Metrics/AbcSize
+
+      # Executes the command instance.
+      #
       def execute(parameters = {})
         do_before(parameters)
         build_and_execute_command(parameters)
@@ -35,6 +40,7 @@ module RubyTerraform
 
       def build_and_execute_command(parameters)
         command = build_command(parameters)
+
         logger.debug("Running '#{command}'.")
         command.execute(
           stdin: stdin,
@@ -53,8 +59,6 @@ module RubyTerraform
 
       private
 
-      def initialize_command; end
-
       def build_command(parameters)
         parameters = resolve_parameters(parameters)
 
@@ -62,10 +66,9 @@ module RubyTerraform
           .for_command(@binary)
           .with_options_after_subcommands
           .with_option_separator('=')
-          .with_appliables(Options::Factory.from(options, parameters))
+          .with_appliables(@options.resolve(options, parameters))
           .with_subcommands(subcommands)
-          .with_arguments(arguments(parameters))
-          .build
+          .with_arguments(arguments(parameters)).build
       end
 
       def resolve_parameters(parameters)

data/lib/ruby_terraform/commands/destroy.rb

@@ -5,14 +5,75 @@ require_relative '../options/common'
 
 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 directory containing terraform configuration;
+    #   required.
+    # * +: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
 
+      # @!visibility private
       def subcommands
         %w[destroy]
       end
 
-      def options # rubocop:disable Metrics/MethodLength
+      # rubocop:disable Metrics/MethodLength
+
+      # @!visibility private
+      def options
         %w[
           -backup
           -compact-warnings
@@ -31,14 +92,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

@@ -5,17 +5,45 @@ require_relative '../options/common'
 
 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.
+    # * +: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
 
+      # @!visibility private
       def subcommands
         %w[force-unlock]
       end
 
+      # @!visibility private
       def options
         %w[-force] + super
       end
 
+      # @!visibility private
+      # @todo Add directory option.
       def arguments(parameters)
         [parameters[:lock_id]]
       end

data/lib/ruby_terraform/commands/format.rb

@@ -5,13 +5,51 @@ require_relative '../options/common'
 
 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 directory containing terraform configuration.
+    # * +: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+.
+    # * +: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
 
+      # @!visibility private
       def subcommands
         %w[fmt]
       end
 
+      # @!visibility private
+      # @todo Add no_color option.
       def options
         %w[
           -list
@@ -22,6 +60,7 @@ module RubyTerraform
         ] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
         [parameters[:directory]]
       end

data/lib/ruby_terraform/commands/get.rb

@@ -5,13 +5,43 @@ require_relative '../options/common'
 
 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 directory containing terraform configuration;
+    #   required.
+    # * +: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
 
+      # @!visibility private
       def subcommands
         %w[get]
       end
 
+      # @!visibility private
       def options
         %w[
           -no-color
@@ -19,6 +49,7 @@ module RubyTerraform
         ] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
         [parameters[:directory]]
       end

data/lib/ruby_terraform/commands/graph.rb

@@ -5,13 +5,51 @@ require_relative '../options/common'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform graph+ command which outputs the visual execution
+    # graph of terraform resources according to either the current configuration
+    # or an execution plan.
+    #
+    # The graph is outputted in DOT format. The typical program that can
+    # read this format is GraphViz, but many web services are also available to
+    # read this format.
+    #
+    # The +:type+ option can be used to control the type of graph shown.
+    # Terraform creates different graphs for different operations. See the
+    # options below for the list of types supported. The default type is
+    # +"plan"+ if a configuration is given, and +"apply"+ if a plan file is
+    # passed as an argument.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {Graph} via {#execute}, the following
+    # options are supported:
+    #
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    # * +:plan+: render the graph using the specified plan file instead of the
+    #   configuration in the current directory.
+    # * +:draw_cycles+: if +true+, highlights any cycles in the graph with
+    #   colored edges; this helps when diagnosing cycle errors; defaults to
+    #   +false+.
+    # * +:type+: the type of graph to output; can be: +"plan"+,
+    #   +"plan-destroy"+, +"apply"+, +"validate"+, +"input"+, +"refresh"+;
+    #   defaults to +"apply"+ if +:plan+ is provided, +"plan"+ otherwise.
+    # * +:module_depth+: (deprecated) in prior versions of terraform, specified
+    #   the depth of modules to show in the output.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::Graph.new.execute
+    #
     class Graph < Base
       include RubyTerraform::Options::Common
 
+      # @!visibility private
       def subcommands
         %w[graph]
       end
 
+      # @!visibility private
+      # @todo Add plan option.
       def options
         %w[
           -draw-cycles