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

data/lib/ruby_terraform/commands/import.rb

@@ -5,14 +5,103 @@ require_relative '../options/common'
 
 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 of terraform configuration files
+    #   to use to configure the provider; defaults to the current directory; if
+    #   no config files are present, they must be provided via the input prompts
+    #   or env vars.
+    # * +: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.
+    # * +: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
 
+      # @!visibility private
       def subcommands
         %w[import]
       end
 
-      def options # rubocop:disable Metrics/MethodLength
+      # rubocop:disable Metrics/MethodLength
+
+      # @!visibility private
+      # @todo Add allow_missing_config option.
+      def options
         %w[
           -config
           -backup
@@ -30,14 +119,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

@@ -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,19 +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
 
-      def initialize_command
-        return if defined?(@stdout) && @stdout.respond_to?(:string)
-
-        @stdout = StringIO.new
+      # @!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
@@ -28,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