train-awsssm 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c80692d5264b12a209c446350e189224beafd77f022b3b83a5be863120fa2830
-  data.tar.gz: 63d5691bf13b81f8819224d44b6b5a650deb9b9466135d5170fe4549254b7a16
+  metadata.gz: ef5a20eca471f5a767da71380b22425fd4676d3a435b0da83077cd3d14fc2c2f
+  data.tar.gz: 97f8b4e0d98b1a20f23b58df148696dceda51843da9fdacd51b274fbf3c94af1
 SHA512:
-  metadata.gz: 302e26f18826f458ff0ffdab020ee15533a269fdd5364e17b04a0e7698c49d4592fe94dcbc7b0b8a48fefa14a1daf717e449b9a84d59e6b67563bb9362b83a13
-  data.tar.gz: 5eed935063c8024ef395e0fbfd4f31143412ef926b788f2c84df748a828c41d71e0f2122be974ea18e6045e49ee4a1998a3bc0af9e2b015f75c7211d0455b719
+  metadata.gz: 19cb91506eb8d0b5db6eeb49f6e94ab071616dca46ebeeac187065958a954d8ef9c2e7a80c2e3b72de3d914f252132e25f75e6b2b43e08467fe9eddb2c230b54
+  data.tar.gz: c81a2c12459fc95e44c451cf7be89f1c1723ce9820c2790e7963b2676384a8623234f84657d4ddbce8316a03926ee73402bc5640bb5b01cd2d33dfcd3c15060e

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## Version 0.2.0
+
+- Add more parameter and status checks
+- Add InSpec support by properly handling failing commands
+- Add Windows support
+- Refactor code
+
 ## Version 0.1.1
 
 - Add support for passing in an instance-id instead of IP/DNS

data/README.md

@@ -1,8 +1,6 @@
 # train-awsssm - Train Plugin for using AWS Systems Manager Agent
 
-This plugin allows applications that rely on Train to communicate via AWS SSM with Linux instances.
-
-Windows is currently not yet supported
+This plugin allows applications that rely on Train to communicate via AWS SSM with Linux/Windows instances.
 
 ## Requirements
 
@@ -10,7 +8,7 @@ The instance in question must run on AWS and you need to have all AWS credential
 
 You need the [SSM agent to be installed](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent.html) on the machine (most current AMIs already have this integrated) and the machine needs to have the managed policy `AmazonSSMManagedInstanceCore` or a least privilege equivalent attached as IAM profile.
 
-Commands will be executed under the `root` user.
+Commands will be executed under the `root`/`Administrator` users.
 
 ## Installation
 
@@ -20,12 +18,13 @@ You can build and install this gem on your local system as well via a Rake task:
 
 ## Transport parameters
 
-| Option               | Explanation                                   | Default          |
-| -------------------- | --------------------------------------------- | ---------------- |
-| `host`               | IP, DNS name or EC2 ID of instance            | (required)       |
-| `execution_timeout`  | Maximum time until timeout                    | 60               |
-| `recheck_invocation` | Interval of rechecking AWS command invocation | 1.0              |
-| `recheck_execution`  | Interval of rechecking completion of command  | 1.0              |
+| Option               | Explanation                                       | Default          |
+| -------------------- | ------------------------------------------------- | ---------------- |
+| `host`               | IP, DNS name or EC2 ID of instance                | (required)       |
+| `mode`               | Mode for connection, only 'run-command' currently | run-command      |
+| `execution_timeout`  | Maximum time until timeout                        | 60               |
+| `recheck_invocation` | Interval of rechecking AWS command invocation     | 1.0              |
+| `recheck_execution`  | Interval of rechecking completion of command      | 1.0              |
 
 ## Limitations
 

data/lib/train-awsssm/connection.rb

@@ -6,24 +6,25 @@ require "train"
 module TrainPlugins
   module AWSSSM
     class Connection < Train::Plugins::Transport::BaseConnection
+      attr_reader :instance_id, :options
+      attr_writer :ssm, :ec2
+
       def initialize(options)
         super(options)
 
         check_options
-
-        @ssm = Aws::SSM::Client.new
       end
 
       def close
-        logger.info format("[AWS-SSM] Closed connection to %s", @options[:host])
+        logger.info format("[AWS-SSM] Closed connection to %s", options[:host])
       end
 
       def uri
-        "aws-ssm://#{@options[:host]}/"
+        "aws-ssm://#{options[:host]}/"
       end
 
       def run_command_via_connection(cmd, &data_handler)
-        logger.info format("[AWS-SSM] Sending command to %s", @options[:host])
+        logger.info format("[AWS-SSM] Sending command to %s", options[:host])
         exit_status, stdout, stderr = execute_on_channel(cmd, &data_handler)
 
         CommandResult.new(stdout, stderr, exit_status)
@@ -32,7 +33,7 @@ module TrainPlugins
       def execute_on_channel(cmd, &data_handler)
         logger.debug format("[AWS-SSM] Command: '%s'", cmd)
 
-        result = execute_command(@options[:host], cmd)
+        result = execute_command(options[:host], cmd)
 
         stdout = result.standard_output_content || ""
         stderr = result.standard_error_content || ""
@@ -43,26 +44,47 @@ module TrainPlugins
 
       private
 
-      # Check if this is an IP address
-      def ip_address?(address)
-        !!(address =~ Resolv::IPv4::Regex)
+      # Return Systems Manager API client
+      #
+      # @return Aws::SSM::Client
+      def ssm
+        @ssm ||= ::Aws::SSM::Client.new
       end
 
-      # Check if this is a DNS name
-      def dns_name?(address)
-        !ip_address?(address)
+      # Return EC2 API client
+      #
+      # @return Aws::EC2::Client
+      def ec2
+        @ec2 ||= ::Aws::EC2::Client.new
       end
 
-      # Check if this is an internal/external AWS DNS entry
-      def amazon_dns?(dns)
-        dns.end_with?(".compute.amazonaws.com") || dns.end_with?(".compute.internal")
+      # Check if options are as needed
+      #
+      # @raise [ArgumentError] if any options were incorrectly configured
+      def check_options
+        unless options[:host]
+          raise ArgumentError, format("Missing required option :host for train-awsssm")
+        end
+
+        unless supported_modes.include? options[:mode]
+          raise ArgumentError, format("Wrong mode `%s`, supported: %s", options[:mode], supported_modes.join(", "))
+        end
+
+        address = options[:host]
+        @instance_id = address.start_with?("i-") ? address : resolve_instance_id(address)
+
+        raise ArgumentError, format("Instance %s is not running", instance_id) unless instance_running?
+        raise ArgumentError, format("Instance %s is not managed by SSM or agent unreachable", instance_id) unless managed_instance?
       end
 
       # Resolve EC2 instance ID associated with a primary IP or a DNS entry
-      def instance_id(address)
+      #
+      # @param [String] address Host or IP address
+      # @return [String] Instance ID, if any
+      # @raise [ArgumentError] if instance could not be resolved from address
+      def resolve_instance_id(address)
         logger.debug format("[AWS-SSM] Trying to resolve address %s", address)
 
-        ec2 = Aws::EC2::Client.new
         instances = ec2.describe_instances.reservations.collect { |r| r.instances.first }
 
         # Resolve, if DNS name and not Amazon default
@@ -81,75 +103,169 @@ module TrainPlugins
           ].include?(address)
         end&.instance_id
 
-        raise format("Could not resolve instance ID for address %s", address) if id.nil?
+        raise ArgumentError, format("Could not resolve instance ID for address %s", address) if id.nil?
 
         logger.debug format("[AWS-SSM] Resolved address %s to instance ID %s", address, id)
+
         id
+      rescue ::Aws::Errors::ServiceError => e
+        raise ArgumentError, format("Error looking up Instance ID for %s: %s", address, e.message)
+      end
+
+      # Check if this is an IP address
+      #
+      # @param [String] address Host, IP address or other input
+      # @return [Boolean] If it is an IPv4 address
+      def ip_address?(address)
+        !!(address =~ Resolv::IPv4::Regex)
+      end
+
+      # Check if this is a DNS name
+      #
+      # @param [String] address Host, IP address or other input
+      # @return [Boolean] If it is a DNS name
+      def dns_name?(address)
+        !ip_address?(address)
+      end
+
+      # Check if this is an internal/external AWS DNS entry
+      #
+      # @param [String] address Host, IP address or other input
+      # @return [Boolean] If it is an Amazon-provided DNS name
+      def amazon_dns?(dns)
+        dns_name?(dns) && (dns.end_with?(".compute.amazonaws.com") || dns.end_with?(".compute.internal"))
       end
 
       # Request a command invocation and wait until it is registered with an ID
-      def wait_for_invocation(instance_id, command_id)
-        invocation_result(instance_id, command_id)
+      #
+      # @param [String] command_id Command ID from SSM
+      def wait_for_invocation(command_id)
+        invocation_result(command_id)
 
       # Retry until the invocation was created on AWS
-      rescue Aws::SSM::Errors::InvocationDoesNotExist
-        sleep @options[:recheck_invocation]
+      rescue ::Aws::SSM::Errors::InvocationDoesNotExist
+        sleep options[:recheck_invocation]
         retry
       end
 
       # Return the result of a given command invocation
-      def invocation_result(instance_id, command_id)
-        @ssm.get_command_invocation(instance_id: instance_id, command_id: command_id)
+      #
+      # @param [String] command_id Command ID from SSM
+      # @return [Aws::SSM::Types::GetCommandInvocationResult] Invocation result
+      def invocation_result(command_id)
+        ssm.get_command_invocation(instance_id: instance_id, command_id: command_id)
       end
 
       # Return if a non-terminal command status was given
+      #
+      # @param [String] name status from invocation
+      # @return [Boolean] If execution is still in progress
       # @see https://docs.aws.amazon.com/systems-manager/latest/userguide/monitor-commands.html
       def in_progress?(name)
         %w{Pending InProgress Delayed}.include? name
       end
 
       # Return if a terminal command status was given
+      #
+      # @param [String] name status from invocation
+      # @return [Boolean] If execution is finished, aborted or timed out
       # @see https://docs.aws.amazon.com/systems-manager/latest/userguide/monitor-commands.html
       def terminal_state?(name)
         !in_progress?(name)
       end
 
       # Execute a command via SSM
+      #
+      # @param [String] address IP, Host or Instance ID
+      # @param [String] command Command to execute
+      # @return [Aws::SSM::Types::GetCommandInvocationResult] Invocation result
+      # @raise [ArgumentError] if instance is not reachable
+      # @raise [RuntimeError] if execution failed or timed out
       def execute_command(address, command)
-        instance_id = if address.start_with? "i-"
-                        address
-                      else
-                        instance_id(address)
-                      end
+        ssm_document = windows_instance? ? "AWS-RunPowerShellScript" : "AWS-RunShellScript"
 
-        cmd = @ssm.send_command(instance_ids: [instance_id], document_name: "AWS-RunShellScript", parameters: { "commands": [command] })
+        cmd = ssm.send_command(instance_ids: [instance_id], document_name: ssm_document, parameters: { "commands": [command] })
         cmd_id = cmd.command.command_id
 
-        wait_for_invocation(instance_id, cmd_id)
+        wait_for_invocation(cmd_id)
         logger.debug format("[AWS-SSM] Execution ID %s", cmd_id)
 
         start_time = Time.now
-        result = invocation_result(instance_id, cmd.command.command_id)
+        result = invocation_result(cmd.command.command_id)
 
-        until terminal_state?(result.status) || Time.now - start_time > @options[:execution_timeout]
-          result = invocation_result(instance_id, cmd.command.command_id)
-          sleep @options[:recheck_execution]
+        until terminal_state?(result.status) || Time.now - start_time > options[:execution_timeout]
+          result = invocation_result(cmd.command.command_id)
+          sleep options[:recheck_execution]
         end
 
-        if Time.now - start_time > @options[:execution_timeout]
+        if Time.now - start_time > options[:execution_timeout]
           raise format("Timeout waiting for execution")
-        elsif result.status != "Success"
+        elsif !%w{Success Failed}.include? result.status
+          # Failing commands is normal for InSpec
           raise format('Execution failed with state "%s": %s', result.status, result.standard_error_content || "unknown")
         end
 
         result
       end
 
-      # Check if options are as needed
-      def check_options
-        unless options[:host]
-          raise format("Missing required option :host for train-awsssm")
-        end
+      # Check if instance is Windows based.
+      # Could also use the `train.connection.platform` mechanics, but they are very slow.
+      #
+      # @return [Boolean] If this is a Windows instance
+      def windows_instance?
+        ec2_instance_data.platform == "windows"
+      end
+
+      # Check if instance is running.
+      #
+      # @param [String] instance_id EC2 instance ID
+      # @return [Boolean] If the instance is currently running
+      def instance_running?
+        ec2_instance_data.state.name == "running"
+      end
+
+      # Check if instance is reachable via SSM.
+      #
+      # @param [String] instance_id EC2 instance ID
+      # @return [Boolean] If the instance is reachable
+      def managed_instance?
+        instance = ssm_instance_data
+        return false unless instance
+
+        instance.ping_status == "Online"
+      end
+
+      # Get instance data from SSM
+      #
+      # @param [String] instance_id EC2 instance ID
+      # @return [Aws::SSM::Types::InstanceInformation] Available SSM instance data
+      # @raise [ArgumentError] if instance ID could not be found
+      def ssm_instance_data
+        response = ssm.describe_instance_information(filters: [{ key: "InstanceIds", values: [instance_id] }])
+
+        response.instance_information_list&.first
+      rescue ::Aws::Errors::ServiceError => e
+        raise ArgumentError, format("Error looking up SSM-managed instance %s: %s", instance_id, e.message)
+      end
+
+      # Get instance data from EC2
+      #
+      # @param [String] instance_id EC2 instance ID
+      # @return [Aws::EC2::Types::Instance] Available instance data
+      # @raise [ArgumentError] if instance ID could not be found
+      def ec2_instance_data
+        instances = ec2.describe_instances(instance_ids: [instance_id])
+
+        instances.reservations.first.instances.first
+      rescue ::Aws::Errors::ServiceError => e
+        raise ArgumentError, format("Error looking up Instance %s: %s", instance_id, e.message)
+      end
+
+      # Supported run modes.
+      #
+      # @return [Array<String>] Supported modes
+      def supported_modes
+        %w{run-command}
       end
     end
   end

data/lib/train-awsssm/transport.rb

@@ -6,6 +6,7 @@ module TrainPlugins
       name "awsssm"
 
       option :host,               required: true
+      option :mode,               default: "run-command"
 
       option :execution_timeout,  default: 60.0
       option :recheck_invocation, default: 1.0

data/lib/train-awsssm/version.rb

@@ -1,5 +1,5 @@
 module TrainPlugins
   module AWSSSM
-    VERSION = "0.1.1".freeze
+    VERSION = "0.2.0".freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: train-awsssm
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Thomas Heinen