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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67cc10d1c813e81407ee1fde4952f587dfaeb97a9da6eacd921e0948ff274b37
-  data.tar.gz: 34cc711d0e383c6e4b745434d50a66fb11629d8533b9226229b1a0ab051909a3
+  metadata.gz: 897da01f6ce70cf4c6f38c95d50a49c620da02e78078c1da7a14daa2f7f15f11
+  data.tar.gz: 476f49771b6acd39233c7b36987b397556ada57fc5bf5d4eeccec42bfe414ea0
 SHA512:
-  metadata.gz: ef66d6f1e646abbe98fb68ccf46d67b672ba3b0be23ed8e94f14f6c235d78099db4973493d4743a5fc0c03dc077322cb78675c34865c915f2707748e981f392a
-  data.tar.gz: 7136d3958da6a0f4a375c41eb1a306aa4f06cddeb865ff2e1e953e1b1b26df5b464890413e7b539dbfd1931c970fcf04fcc050d9996337da17d131a3b3c0dee4
+  metadata.gz: 98e74c44146a22196085aaa288c9ac93cf94ebb17aacd9e16473de232c0e9e87f59682df2978c8902f561f2e4ae040e57398f550c7a3fc359fba80e184615fb9
+  data.tar.gz: 98f3870cf241284aa5197012e72d7132e6e5a52f9e70724b07a65231c8605a7020aaa064b9920240d4e02585df0cd05cd664c411113589e79fc288cc5b24845c

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby-terraform (0.65.0.pre.13)
+    ruby-terraform (0.65.0.pre.14)
       immutable-struct (>= 2.4)
       lino (>= 2.5)
 
@@ -22,14 +22,18 @@ GEM
     concurrent-ruby (1.1.8)
     diff-lcs (1.4.4)
     docile (1.3.5)
-    excon (0.79.0)
+    excon (0.80.1)
     faker (2.17.0)
       i18n (>= 1.6, < 2)
-    faraday (1.3.0)
+    faraday (1.4.1)
+      faraday-excon (~> 1.1)
       faraday-net_http (~> 1.0)
+      faraday-net_http_persistent (~> 1.1)
       multipart-post (>= 1.2, < 3)
-      ruby2_keywords
+      ruby2_keywords (>= 0.0.4)
+    faraday-excon (1.1.0)
     faraday-net_http (1.0.1)
+    faraday-net_http_persistent (1.1.0)
     ffi (1.15.0)
     formatador (0.2.5)
     gem-release (2.2.1)
@@ -117,7 +121,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.10.0)
     rspec-support (3.10.2)
-    rubocop (1.12.1)
+    rubocop (1.13.0)
       parallel (~> 1.10)
       parser (>= 3.0.0.0)
       rainbow (>= 2.2.2, < 4.0)
@@ -152,6 +156,7 @@ GEM
     tzinfo (2.0.4)
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.0.0)
+    yard (0.9.26)
     zeitwerk (2.4.2)
 
 PLATFORMS
@@ -174,6 +179,7 @@ DEPENDENCIES
   rubocop-rspec (~> 2.2)
   ruby-terraform!
   simplecov (~> 0.21)
+  yard (~> 0.9)
 
 BUNDLED WITH
    2.2.16

data/lib/ruby_terraform.rb

@@ -24,8 +24,80 @@ module RubyTerraform
   end
 
   module ClassMethods
+    # Invokes 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.
+    #
+    # @param parameters The parameters used to invoke the command
+    # @option parameters [String] :directory The directory containing terraform
+    #   configuration; required unless +:plan+ is provided.
+    # @option parameters [String] :plan The path to a pre-computed plan to be
+    #   applied; required unless +:directory+ is provided.
+    # @option parameters [Boolean] :auto_approve (false) If +true+, skips
+    #   interactive approval of the generated plan before applying.
+    # @option parameters [String] :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.
+    # @option parameters [String] :chdir The path of a working directory to
+    #   switch to before executing the given subcommand.
+    # @option parameters [Boolean] :compact_warnings (false) 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.
+    # @option parameters [Boolean] :input (true) When +false+, will not ask for
+    #   input for variables not directly set.
+    # @option parameters [Boolean] :lock (true) When +true+, locks the state
+    #   file when locking is supported; when +false+, does not lock the state
+    #   file.
+    # @option parameters [String] :lock_timeout ("0s") The duration to retry a
+    #   state lock.
+    # @option parameters [Boolean] :no_backup (false) When +true+, no backup
+    #   file will be written.
+    # @option parameters [Boolean] :no_color (false) Whether or not the output
+    #   from the command should be in color.
+    # @option parameters [Integer] :parallelism (10) The number of parallel
+    #   resource operations.
+    # @option parameters [Boolean] :refresh (true) When +true+, updates state
+    #   prior to checking for differences; when +false+ uses locally available
+    #   state; this has no effect when +:plan+ is provided.
+    # @option parameters [String] :state ("terraform.tfstate") The path to the
+    #   state file from which to read state and in which to store state (unless
+    #   +:state_out+ is specified).
+    # @option parameters [String] :state_out The path to write state to that is
+    #   different than +:state+; this can be used to preserve the old state.
+    # @option parameters [String] :target The address of a resource to target;
+    #   if both +:target+ and +:targets+ are provided, all targets will be
+    #   passed to terraform.
+    # @option parameters [Array<String>] :targets An array of resource addresses
+    #   to target; if both +:target+ and +:targets+ are provided, all targets
+    #   will be passed to terraform.
+    # @option parameters [Hash<String, Object>] :vars A map of variables to be
+    #   passed to the terraform configuration.
+    # @option parameters [String] :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.
+    # @option parameters [Array<String>] :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.apply(
+    #     directory: 'infra/networking',
+    #     vars: {
+    #       region: 'eu-central'
+    #     })
+    #
+    def apply(parameters = {})
+      exec(RubyTerraform::Commands::Apply, parameters)
+    end
+
     {
-      apply: RubyTerraform::Commands::Apply,
       clean: RubyTerraform::Commands::Clean,
       destroy: RubyTerraform::Commands::Destroy,
       format: RubyTerraform::Commands::Format,

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.
+    # * +: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+.
+    # * +: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

@@ -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,10 @@ module RubyTerraform
         @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)

data/lib/ruby_terraform/options/common.rb

@@ -3,6 +3,7 @@
 module RubyTerraform
   module Options
     module Common
+      # @!visibility private
       def options
         %w[-chdir]
       end

data/lib/ruby_terraform/options/definition.rb

@@ -18,7 +18,8 @@ module RubyTerraform
       :separator,
       :repeatable?
     )
-      def initialize(opts) # rubocop:disable Metrics/MethodLength
+      # rubocop:disable Metrics/MethodLength
+      def initialize(opts)
         raise 'Missing name.' unless opts[:name]
 
         super(
@@ -35,6 +36,7 @@ module RubyTerraform
               .merge(opts[:override_keys] || {})
         )
       end
+      # rubocop:enable Metrics/MethodLength
 
       def matches?(name)
         @name == Name.new(name)

data/lib/ruby_terraform/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyTerraform
-  VERSION = '0.65.0.pre.13'
+  VERSION = '0.65.0.pre.14'
 end

data/ruby_terraform.gemspec

@@ -56,4 +56,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rubocop-rake', '~> 0.5'
   spec.add_development_dependency 'rubocop-rspec', '~> 2.2'
   spec.add_development_dependency 'simplecov', '~> 0.21'
+  spec.add_development_dependency 'yard', '~> 0.9'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-terraform
 version: !ruby/object:Gem::Version
-  version: 0.65.0.pre.13
+  version: 0.65.0.pre.14
 platform: ruby
 authors:
 - Toby Clemson
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-04-14 00:00:00.000000000 Z
+date: 2021-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: immutable-struct
@@ -248,6 +248,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: Wraps the Terraform CLI so that Terraform can be invoked from a Ruby
   script or Rakefile.
 email: