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

data/lib/ruby_terraform/commands/apply.rb

@@ -23,13 +23,13 @@ module RubyTerraform
     #   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.
-    # * +:chdir+: the path of a working directory to switch to before executing
-    #   the given subcommand.
     # * +: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+.

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

data/lib/ruby_terraform/commands/import.rb

@@ -5,14 +5,103 @@ require_relative '../options/common'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform import+ command which imports existing infrastructure
+    # into your terraform state.
+    #
+    # This will find and import the specified resource into your terraform
+    # state, allowing existing infrastructure to come under terraform
+    # management without having to be initially created by terraform.
+    #
+    # The +:address+ specified is the address to import the resource to. Please
+    # see the documentation online for resource addresses. The +:id+ is a
+    # resource-specific ID to identify that resource being imported. Please
+    # reference the documentation for the resource type you're importing to
+    # determine the ID syntax to use. It typically matches directly to the ID
+    # that the provider uses.
+    #
+    # The current implementation of terraform import can only import resources
+    # into the state. It does not generate configuration. A future version of
+    # terraform will also generate configuration.
+    #
+    # Because of this, prior to running terraform import it is necessary to
+    # write a resource configuration block for the resource manually, to which
+    # the imported object will be attached.
+    #
+    # This command will not modify your infrastructure, but it will make network
+    # requests to inspect parts of your infrastructure relevant to the resource
+    # being imported.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {Import} via {#execute}, the following
+    # options are supported:
+    #
+    # * +:directory+: the path to a directory of terraform configuration files
+    #   to use to configure the provider; defaults to the current directory; if
+    #   no config files are present, they must be provided via the input prompts
+    #   or env vars.
+    # * +:address+: the address to import the resource to; required.
+    # * +:id+: the resource-specific ID identifying the resource being imported;
+    #   required.
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    # * +: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.
+    # * +: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+: (legacy) 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+.
+    # * +:provider+: (deprecated) the provider configuration to use when
+    #   importing the object; by default, terraform uses the provider specified
+    #   in the configuration for the target resource, and that is the best
+    #   behavior in most cases.
+    # * +: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.
+    # * +: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.
+    # * +:ignore_remote_version+: If +true+, when using the enhanced remote
+    #   backend with Terraform Cloud, continue even if remote and local
+    #   Terraform versions differ; this may result in an unusable Terraform
+    #   Cloud workspace, and should be used with extreme caution; defaults to
+    #   +false+.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::Import.new.execute(
+    #     directory: 'infra/networking',
+    #     address: 'a.resource.address',
+    #     id: 'a-resource-id',
+    #     vars: {
+    #       region: 'eu-central'
+    #     })
+    #
     class Import < Base
       include RubyTerraform::Options::Common
 
+      # @!visibility private
       def subcommands
         %w[import]
       end
 
-      def options # rubocop:disable Metrics/MethodLength
+      # rubocop:disable Metrics/MethodLength
+
+      # @!visibility private
+      # @todo Add allow_missing_config option.
+      def options
         %w[
           -config
           -backup
@@ -30,14 +119,19 @@ module RubyTerraform
         ] + super
       end
 
+      # rubocop:enable Metrics/MethodLength
+
+      # @!visibility private
       def arguments(parameters)
         [parameters[:address], parameters[:id]]
       end
 
+      # @!visibility private
       def parameter_defaults(_parameters)
         { vars: {}, var_files: [] }
       end
 
+      # @!visibility private
       def parameter_overrides(parameters)
         { backup: parameters[:no_backup] ? '-' : parameters[:backup] }
       end