ruby-terraform 0.65.0.pre.12 → 1.0.0

data/lib/ruby_terraform/commands/plan.rb

@@ -1,18 +1,83 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform plan+ command which generates a speculative execution
+    # plan, showing what actions Terraform would take to apply the current
+    # configuration. This command will not actually perform the planned actions.
+    #
+    # You can optionally save the plan to a file, which you can then pass to
+    # the {Apply} command to perform exactly the actions described in the plan.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # 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.
+    # * +: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+.
+    # * +:destroy+: when +true+, a plan will be generated to destroy all
+    #   resources managed by the given configuration and state; defaults to
+    #   +false+.
+    # * +:detailed_exitcode+: whether or not to return detailed exit codes when
+    #   the command exits; this will change the meaning of exit codes to:
+    #   0 - Succeeded, diff is empty (no changes); 1 - Errored; 2 - Succeeded,
+    #   there is a diff; 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_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+.
+    # * +: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.
+    # * +: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"+.
+    # * +: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::Plan.new.execute(
+    #     directory: 'infra/networking',
+    #     vars: {
+    #       region: 'eu-central'
+    #     })
+    #
     class Plan < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[plan]
       end
 
-      def options # rubocop:disable Metrics/MethodLength
+      # rubocop:disable Metrics/MethodLength
+
+      # @!visibility private
+      def options
         %w[
           -compact-warnings
           -destroy
@@ -31,10 +96,14 @@ 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

data/lib/ruby_terraform/commands/providers.rb

@@ -1,16 +1,44 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform providers+ command which prints out a tree of modules
+    # in the referenced configuration annotated with their provider
+    # requirements.
+    #
+    # This provides an overview of all of the provider requirements across all
+    # referenced modules, as an aid to understanding why particular provider
+    # plugins are needed and why particular versions are selected.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # 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.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::Providers.new.execute
+    #
     class Providers < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[providers]
       end
+
+      # @!visibility private
+      def arguments(parameters)
+        [parameters[:directory]]
+      end
     end
   end
 end

data/lib/ruby_terraform/commands/providers_lock.rb

@@ -1,17 +1,85 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform providers lock+ command which writes out dependency
+    # locks for the configured providers.
+    #
+    # Normally the dependency lock file (.terraform.lock.hcl) is updated
+    # automatically by "terraform init", but the information available to the
+    # normal provider installer can be constrained when you're installing
+    # providers from filesystem or network mirrors, and so the generated lock
+    # file can end up incomplete.
+    #
+    # The "providers lock" subcommand addresses that by updating the lock file
+    # based on the official packages available in the origin registry, ignoring
+    # the currently-configured installation strategy.
+    #
+    # After this command succeeds, the lock file will contain suitable checksums
+    # to allow installation of the providers needed by the current configuration
+    # on all of the selected platforms.
+    #
+    # By default this command updates the lock file for every provider declared
+    # in the configuration. You can override that behavior by providing one or
+    # more provider source addresses on the command line.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {ProvidersLock} via {#execute}, the
+    # following options are supported:
+    #
+    # * +: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
+    #   directory instead of the origin registry for each of the given
+    #   providers; this would be necessary to generate lock file entries for
+    #   a provider that is available only via a mirror, and not published in an
+    #   upstream registry; in this case, the set of valid checksums will be
+    #   limited only to what Terraform can learn from the data in the mirror
+    #   directory.
+    # * +:net_mirror+: if provided, consults the given network mirror (given as
+    #   a base URL) instead of the origin registry for each of the given
+    #   providers; this would be necessary to generate lock file entries for a
+    #   provider that is available only via a mirror, and not published in an
+    #   upstream registry; in this case, the set of valid checksums will be
+    #   limited only to what Terraform can learn from the data in the mirror
+    #   indices.
+    # * +:platform+: the target platform to request package checksums for; by
+    #   default Terraform will request package checksums suitable only for the
+    #   platform where you run this command; target names consist of an
+    #   operating system and a CPU architecture; for example, "linux_amd64"
+    #   selects the Linux operating system running on an AMD64 or x86_64 CPU;
+    #   each provider is available only for a limited set of target platforms;
+    #   if both +:platform+ and +:platforms+ are provided, all platforms will be
+    #   passed to Terraform.
+    # * +:platforms+: an array of target platforms to request package checksums
+    #   for; see +:platform+ for more details; if both +:platform+ and
+    #   +:platforms+ are provided, all platforms will be passed to Terraform.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::ProvidersLock.new.execute(
+    #     fs_mirror: "/usr/local/terraform/providers",
+    #     platforms: ["windows_amd64", "darwin_amd64", "linux_amd64"],
+    #     provider: "tf.example.com/ourcompany/ourplatform")
+    #
     class ProvidersLock < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[providers lock]
       end
 
+      # @!visibility private
       def options
         %w[
           -fs-mirror
@@ -20,8 +88,9 @@ module RubyTerraform
         ] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
-        [parameters[:providers]]
+        [parameters[:provider], parameters[:providers]]
       end
     end
   end

data/lib/ruby_terraform/commands/providers_mirror.rb

@@ -1,21 +1,63 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform providers mirror+ command which saves local copies of
+    # all required provider plugins.
+    #
+    # Populates a local directory with copies of the provider plugins needed for
+    # the current configuration, so that the directory can be used either
+    # directly as a filesystem mirror or as the basis for a network mirror and
+    # thus obtain those providers without access to their origin registries in
+    # future.
+    #
+    # The mirror directory will contain JSON index files that can be published
+    # along with the mirrored packages on a static HTTP file server to produce a
+    # network mirror. Those index files will be ignored if the directory is used
+    # instead as a local filesystem mirror.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {ProvidersMirror} via {#execute}, the
+    # following options are supported:
+    #
+    # * +:directory+: the directory to populate with the mirrored provider
+    #   plugins.
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    # * +:platform+: the target platform to build a mirror for; by default
+    #   Terraform will obtain plugin packages suitable for the platform where
+    #   you run this command; target names consist of an operating system and a
+    #   CPU architecture; for example, "linux_amd64" selects the Linux operating
+    #   system running on an AMD64 or x86_64 CPU; each provider is available
+    #   only for a limited set of target platforms; if both +:platform+ and
+    #   +:platforms+ are provided, all platforms will be passed to Terraform.
+    # * +:platforms+: an array of target platforms to build a mirror for for;
+    #   see +:platform+ for more details; if both +:platform+ and +:platforms+
+    #   are provided, all platforms will be passed to Terraform.
+    #
+    # @example Basic Invocation
+    #   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
         %w[providers mirror]
       end
 
+      # @!visibility private
       def options
         %w[-platform] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
         [parameters[:directory]]
       end

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