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

data/lib/ruby_terraform/commands/providers.rb

@@ -5,12 +5,34 @@ require_relative '../options/common'
 
 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:
+    #
+    # * +: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
 
+      # @!visibility private
       def subcommands
         %w[providers]
       end
+
+      # @todo Add directory argument
     end
   end
 end

data/lib/ruby_terraform/commands/providers_lock.rb

@@ -5,13 +5,77 @@ require_relative '../options/common'
 
 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:
+    #
+    # * +:providers+: the provider source addresses for which the lock file
+    #   should be updated.
+    # * +: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"],
+    #     providers: "tf.example.com/ourcompany/ourplatform")
+    #
     class ProvidersLock < Base
       include RubyTerraform::Options::Common
 
+      # @!visibility private
       def subcommands
         %w[providers lock]
       end
 
+      # @!visibility private
       def options
         %w[
           -fs-mirror
@@ -20,6 +84,8 @@ module RubyTerraform
         ] + super
       end
 
+      # @!visibility private
+      # @todo Flatten arguments array to allow array of providers.
       def arguments(parameters)
         [parameters[:providers]]
       end

data/lib/ruby_terraform/commands/providers_mirror.rb

@@ -5,17 +5,59 @@ require_relative '../options/common'
 
 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::PlatformsMirror.new.execute(
+    #     directory: './plugins',
+    #     platforms: ["windows_amd64", "darwin_amd64", "linux_amd64"])
+    #
     class ProvidersMirror < Base
       include RubyTerraform::Options::Common
 
+      # @!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/taint.rb

@@ -18,7 +18,8 @@ module RubyTerraform
           -backup
           -lock
           -lock-timeout
-          -state -state-out
+          -state
+          -state-out
           -ignore-remote-version
         ] + super
       end

data/lib/ruby_terraform/options.rb

@@ -1,8 +1,30 @@
 # frozen_string_literal: true
 
 require_relative 'options/name'
-require_relative 'options/types/flag'
-require_relative 'options/types/boolean'
-require_relative 'options/types/standard'
+require_relative 'options/types'
+require_relative 'options/values'
+require_relative 'options/definition'
 require_relative 'options/factory'
 require_relative 'options/common'
+
+module RubyTerraform
+  module Options
+    def self.name(name)
+      Name.new(name)
+    end
+
+    def self.definition(opts)
+      Definition.new(opts)
+    end
+
+    def self.types
+      Types
+    end
+
+    def self.values
+      Values
+    end
+  end
+end
+
+require_relative 'options/definitions'

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

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'immutable-struct'
+
+require_relative 'name'
+require_relative 'types'
+require_relative 'values'
+
+module RubyTerraform
+  module Options
+    # rubocop:disable Metrics/ClassLength
+    class Definition < ImmutableStruct.new(
+      :name,
+      :option_type,
+      :value_type,
+      :override_keys,
+      :extra_keys,
+      :separator,
+      :repeatable?
+    )
+      # rubocop:disable Metrics/MethodLength
+      def initialize(opts)
+        raise 'Missing name.' unless opts[:name]
+
+        super(
+          name: Name.new(opts[:name]),
+          option_type: Types.resolve(opts[:option_type]) || Types::Standard,
+          value_type: Values.resolve(opts[:value_type]) || Values::String,
+          repeatable: opts[:repeatable] || false,
+          separator: opts[:separator],
+          extra_keys:
+            { singular: [], plural: [] }
+              .merge(opts[:extra_keys] || {}),
+          override_keys:
+            { singular: nil, plural: nil }
+              .merge(opts[:override_keys] || {})
+        )
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      def matches?(name)
+        @name == Name.new(name)
+      end
+
+      def build(parameters)
+        build_singular_options(parameters) + build_plural_options(parameters)
+      end
+
+      private
+
+      def resolved_singular_key
+        if override_keys[:singular] == false
+          nil
+        else
+          override_keys[:singular] || name.as_singular_key
+        end
+      end
+
+      def all_singular_keys
+        ([resolved_singular_key] + extra_keys[:singular]).compact
+      end
+
+      def resolved_plural_key
+        if override_keys[:plural] == false
+          nil
+        else
+          override_keys[:plural] || name.as_plural_key
+        end
+      end
+
+      def all_plural_keys
+        ([resolved_plural_key] + extra_keys[:plural]).compact
+      end
+
+      def too_many_values?(values)
+        !repeatable? && values.length > 1
+      end
+
+      def values(parameters, keys)
+        keys.map { |k| parameters[k] }.compact
+      end
+
+      def needs_plural?(value)
+        repeatable? && !value.nil?
+      end
+
+      def only_singular?(value)
+        !needs_plural?(value)
+      end
+
+      def key_valued?(value)
+        value.respond_to?(:keys)
+      end
+
+      def multi_valued?(value)
+        value.respond_to?(:each)
+      end
+
+      def build_option(value)
+        option_type.new(name, value, separator: separator)
+      end
+
+      def build_value(value)
+        value_type.new(value)
+      end
+
+      def build_key_value(key, value)
+        Values::KeyValue.new(key, build_value(value))
+      end
+
+      def build_singular(value)
+        build_single_option(value)
+      end
+
+      def build_singulars(values)
+        values.map { |p| build_singular(p) }.flatten
+      end
+
+      def build_singular_options(parameters)
+        keys = all_singular_keys
+        values = values(parameters, keys)
+
+        if too_many_values?(values)
+          raise "Multiple values provided for '#{name}' " \
+                "(with keys #{keys}) and option not repeatable."
+        end
+
+        build_singulars(values)
+      end
+
+      def build_plural(value)
+        if only_singular?(value)
+          build_no_options
+        elsif key_valued?(value)
+          build_key_value_options(value)
+        elsif multi_valued?(value)
+          build_multiple_options(value)
+        else
+          build_single_option(value)
+        end
+      end
+
+      def build_plurals(values)
+        values.map { |p| build_plural(p) }.flatten
+      end
+
+      def build_plural_options(parameters)
+        keys = all_plural_keys
+        values = values(parameters, keys)
+
+        build_plurals(values)
+      end
+
+      def build_key_value_options(value)
+        value.map { |k, v| build_option(build_key_value(k, v)) }
+      end
+
+      def build_multiple_options(value)
+        value.map { |v| build_option(build_value(v)) }
+      end
+
+      def build_single_option(value)
+        [build_option(build_value(value))]
+      end
+
+      def build_no_options
+        []
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/ruby_terraform/options/definitions.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module RubyTerraform
+  module Options
+    DEFINITIONS =
+      [
+        # complex repeatable options with space separator
+        %w[-var].map do |o|
+          definition(
+            name: o, option_type: :standard, value_type: :complex,
+            repeatable: true, separator: ' '
+          )
+        end,
+
+        # complex repeatable options with default separator
+        %w[-backend-config].map do |o|
+          definition(
+            name: o, option_type: :standard, value_type: :complex,
+            repeatable: true,
+            override_keys: { singular: false, plural: :backend_config }
+          )
+        end,
+
+        # string repeatable options
+        %w[-var-file -target -platform].map do |o|
+          definition(
+            name: o, option_type: :standard, value_type: :string,
+            repeatable: true
+          )
+        end,
+
+        # boolean options
+        %w[
+          -auto-approve
+          -backend
+          -get
+          -get-plugins
+          -input
+          -list
+          -lock
+          -refresh
+          -upgrade
+          -verify-plugins
+          -write
+        ].map do |o|
+          definition(name: o, option_type: :standard, value_type: :boolean)
+        end,
+
+        # flag options
+        %w[
+          -allow-missing
+          -allow-missing-config
+          -check
+          -compact-warnings
+          -destroy
+          -detailed-exitcode
+          -diff
+          -draw-cycles
+          -force
+          -force-copy
+          -ignore-remote-version
+          -json
+          -no-color
+          -raw
+          -reconfigure
+          -recursive
+          -update
+        ].map do |o|
+          definition(name: o, option_type: :flag, value_type: :boolean)
+        end,
+
+        # string options
+        %w[
+          -backup
+          -backup-out
+          -chdir
+          -from-module
+          -fs-mirror
+          -lock-timeout
+          -module-depth
+          -net-mirror
+          -parallelism
+          -plugin-dir
+          -provider
+          -state
+          -state-out
+          -type
+        ].map do |o|
+          definition(name: o, option_type: :standard, value_type: :string)
+        end,
+
+        # string options with extra keys
+        definition(
+          name: '-config', option_type: :standard, value_type: :string,
+          extra_keys: { singular: %i[directory] }
+        ),
+        definition(
+          name: '-out', option_type: :standard, value_type: :string,
+          extra_keys: { singular: %i[plan] }
+        )
+      ].flatten.freeze
+  end
+end