ruby-terraform 0.65.0.pre.12 → 1.0.0

data/lib/ruby_terraform/commands/graph.rb

@@ -1,24 +1,70 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 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:
+    #
+    # * +: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.
+    # * +: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
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[graph]
       end
 
+      # @!visibility private
       def options
         %w[
+          -plan
           -draw-cycles
           -type
           -module-depth
         ] + super
       end
+
+      # @!visibility private
+      def arguments(parameters)
+        [parameters[:directory]]
+      end
     end
   end
 end

data/lib/ruby_terraform/commands/import.rb

@@ -1,20 +1,110 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 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 containing terraform configuration
+    #   (deprecated in terraform 0.14, removed in terraform 0.15, use +:chdir+
+    #   instead).
+    # * +: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.
+    # * +:allow_missing_config+: whether or not to allow import when no resource
+    #   configuration block exists; 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+: (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
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[import]
       end
 
-      def options # rubocop:disable Metrics/MethodLength
+      # rubocop:disable Metrics/MethodLength
+
+      # @!visibility private
+      def options
         %w[
           -config
+          -allow-missing-config
           -backup
           -input
           -lock
@@ -30,14 +120,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

data/lib/ruby_terraform/commands/init.rb

@@ -1,18 +1,94 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 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
+    #   (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.
+    # * +: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; if both +:plugin_dir+ and
+    #   +:plugin_dirs+ are provided, all plugin directories will be passed to
+    #   Terraform.
+    # * +:plugin_dirs+: an array of paths to directories containing plugin
+    #   binaries; this overrides all default search paths for plugins, and
+    #   prevents the automatic installation of plugins; if both +:plugin_dir+
+    #   and +:plugin_dirs+ are provided, all plugin directories will be passed
+    #   to Terraform.
+    # * +: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).
+    # * +:lockfile+: sets a dependency lockfile mode; currently only "readonly"
+    #   is valid.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::Init.new.execute(
+    #     from_module: 'some/module/path',
+    #     path: 'infra/module')
+    #
     class Init < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[init]
       end
 
-      def options # rubocop:disable Metrics/MethodLength
+      # rubocop:disable Metrics/MethodLength
+
+      # @!visibility private
+      def options
         %w[
           -backend
           -backend-config
@@ -28,13 +104,18 @@ module RubyTerraform
           -reconfigure
           -upgrade
           -verify-plugins
+          -lockfile
         ] + 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

@@ -1,17 +1,41 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 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
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[login]
       end
 
+      # @!visibility private
       def arguments(parameters)
         [parameters[:hostname]]
       end

data/lib/ruby_terraform/commands/logout.rb

@@ -1,17 +1,38 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 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
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[logout]
       end
 
+      # @!visibility private
       def arguments(parameters)
         [parameters[:hostname]]
       end

data/lib/ruby_terraform/commands/output.rb

@@ -2,21 +2,51 @@
 
 require 'stringio'
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 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
+      include RubyTerraform::Options::Global
 
+      # @!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