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

data/lib/ruby_terraform/commands/init.rb

@@ -5,14 +5,81 @@ require_relative '../options/common'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform init+ command which initializes a new or existing
+    # Terraform working directory by creating initial files, loading any remote
+    # state, downloading modules, etc.
+    #
+    # This is the first command that should be run for any new or existing
+    # Terraform configuration per machine. This sets up all the local data
+    # necessary to run Terraform that is typically not committed to version
+    # control.
+    #
+    # This command is always safe to run multiple times. Though subsequent runs
+    # may give errors, this command will never delete your configuration or
+    # state. Even so, if you have important information, please back it up prior
+    # to running this command, just in case.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {Init} via {#execute}, the following
+    # options are supported:
+    #
+    # * +:path+: the path to initialize; defaults to the current directory.
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    # * +:backend+: whether or not to configure the backend for this
+    #   configuration; defaults to +true+.
+    # * +:backend_config+: a map of backend specific configuration parameters.
+    # * +:force_copy+: if +true+, suppresses prompts about copying state data;
+    #   this is equivalent to providing a "yes" to all confirmation prompts;
+    #   defaults to +false+.
+    # * +:from_module+: copies the contents of the given module into the target
+    #   directory before initialization.
+    # * +:get+: whether or not to download any modules for this configuration;
+    #   defaults to +true+.
+    # * +:get_plugins+: whether or not to install plugins for this
+    #   configuration; defaults to +true+ (deprecated, removed in terraform
+    #   0.15).
+    # * +: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+
+    #   (deprecated, removed in terraform 0.15).
+    # * +:lock_timeout+: the duration to retry a state lock; defaults to +"0s"+;
+    #   (deprecated, removed in terraform 0.15).
+    # * +:no_color+: whether or not the output from the command should be in
+    #   color; defaults to +false+.
+    # * +:plugin_dir+: the path to a directory containing plugin binaries; this
+    #   overrides all default search paths for plugins, and prevents the
+    #   automatic installation of plugins.
+    # * +:reconfigure+: if +true+, reconfigures the backend, ignoring any saved
+    #   configuration; defaults to +false+.
+    # * +:upgrade+: if +true+, when installing modules or plugins, ignores
+    #   previously-downloaded objects and installs the latest version allowed
+    #   within configured constraints; defaults to +false+.
+    # * +:verify_plugins+: whether or not to verify plugins for this
+    #   configuration; defaults to +true+ (deprecated, removed in terraform
+    #   0.15).
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::Init.new.execute(
+    #     from_module: 'some/module/path',
+    #     path: 'infra/module')
+    #
     class Init < Base
       include RubyTerraform::Options::Common
 
+      # @!visibility private
       def subcommands
         %w[init]
       end
 
-      def options # rubocop:disable Metrics/MethodLength
+      # rubocop:disable Metrics/MethodLength
+
+      # @!visibility private
+      # @todo Add lockfile option.
+      # @todo Make plugin_dir option plural
+      def options
         %w[
           -backend
           -backend-config
@@ -31,10 +98,14 @@ module RubyTerraform
         ] + super
       end
 
+      # rubocop:enable Metrics/MethodLength
+
+      # @!visibility private
       def arguments(parameters)
         [parameters[:path]]
       end
 
+      # @!visibility private
       def parameter_defaults(_parameters)
         { backend_config: {} }
       end

data/lib/ruby_terraform/commands/login.rb

@@ -5,13 +5,37 @@ require_relative '../options/common'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform login+ command which retrieves an authentication
+    # token for the given hostname, if it supports automatic login, and saves it
+    # in a credentials file in your home directory.
+    #
+    # If no hostname is provided, the default hostname is app.terraform.io, to
+    # log in to Terraform Cloud.
+    #
+    # If not overridden by credentials helper settings in the CLI configuration,
+    # the credentials will be written to the following local file:
+    #   ~/.terraform.d/credentials.tfrc.json
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {Login} 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::Login.new.execute
+    #
     class Login < Base
       include RubyTerraform::Options::Common
 
+      # @!visibility private
       def subcommands
         %w[login]
       end
 
+      # @!visibility private
       def arguments(parameters)
         [parameters[:hostname]]
       end

data/lib/ruby_terraform/commands/logout.rb

@@ -5,13 +5,34 @@ require_relative '../options/common'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform logout+ command which removes locally-stored
+    # credentials for specified hostname.
+    #
+    # Note: the API token is only removed from local storage, not destroyed on
+    # the remote server, so it will remain valid until manually revoked.
+    #
+    # If no hostname is provided, the default hostname is app.terraform.io.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {Logout} 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::Logout.new.execute
+    #
     class Logout < Base
       include RubyTerraform::Options::Common
 
+      # @!visibility private
       def subcommands
         %w[logout]
       end
 
+      # @!visibility private
       def arguments(parameters)
         [parameters[:hostname]]
       end

data/lib/ruby_terraform/commands/output.rb

@@ -6,17 +6,47 @@ require_relative '../options/common'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform output+ command which reads an output variable from a
+    # Terraform state file and prints the value. With no additional arguments,
+    # output will display all the outputs for the root module. If +:name+ is not
+    # specified, all outputs are printed.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {Output} via {#execute}, the following
+    # options are supported:
+    #
+    # * +:name+: The name of the output to read.
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    # * +:state+: the path to the state file to read; defaults to
+    #   +"terraform.tfstate"+.
+    # * +:no_color+: whether or not the output from the command should be in
+    #   color; defaults to +false+.
+    # * +:json+: If +true+, machine readable output will be printed in JSON
+    #   format; defaults to +false+.
+    # * +:raw+: If +true+, for value types that can be automatically converted
+    #   to a string, will print the raw string directly, rather than a
+    #   human-oriented representation of the value.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::Output.new.execute(
+    #     name: 'vpc_id')
+    #
     class Output < Base
       include RubyTerraform::Options::Common
 
+      # @!visibility private
       def stdout
         @stdout.respond_to?(:string) ? @stdout : (@stdout = StringIO.new)
       end
 
+      # @!visibility private
       def subcommands
         %w[output]
       end
 
+      # @!visibility private
       def options
         %w[
           -json
@@ -26,10 +56,12 @@ module RubyTerraform
         ] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
         [parameters[:name]]
       end
 
+      # @!visibility private
       def do_after(parameters)
         result = stdout.string
         parameters[:name] ? result.chomp : result

data/lib/ruby_terraform/commands/plan.rb

@@ -5,14 +5,76 @@ require_relative '../options/common'
 
 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:
+    #
+    # * +:plan+: the path to output the plan if it should be saved to a file.
+    # * +: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+.
+    # * +: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
 
+      # @!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 +93,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

@@ -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