train-awsssm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 87fb6b7111f611cc31aea97504e8617c055a696bd5f60b64a4a684454436d83a
+  data.tar.gz: d9756ffccc53b4e438b7f5e8acc5b11d2c477d20360531bf2829e7a3e472b3e4
+SHA512:
+  metadata.gz: d080f63b75929c5e8b66874d0eb0320a3eb8e455866823de24f613712ec22e50337631fd104ae15530c506df8b12bbec4b58fa4b20aafed728fb20da67ed4fa9
+  data.tar.gz: '028d2b8807d11ec343186344ee781736d17a34353fac07cc07be36fda94b6384f7a11f0de6bcd771daec7c676e6cf52b98564039e655ef9090fca889d1f8da33'

data/Gemfile

@@ -0,0 +1,10 @@
+source "https://rubygems.org"
+
+gemspec
+
+group :development do
+  gem "pry"
+  gem "bundler"
+  gem "rake"
+  gem "chefstyle"
+end

data/README.md

@@ -0,0 +1,47 @@
+# train-awsssm - Train Plugin for using AWS Systems Manager Agent
+
+This plugin allows applications that rely on Train to communicate via AWS SSM.
+
+## Requirements
+
+The instance in question must run on AWS and you need to have all AWS credentials
+set up for the shell which executes the command. Please check the [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)
+for appropriate configuration files and environment variables.
+
+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 `ssm-user` user.
+
+## Installation
+
+You will have to build this gem yourself to install it as it is not yet on
+Rubygems.Org. For this there is a rake task which makes this a one-liner:
+
+```bash
+rake install:local
+```
+
+## Transport parameters
+
+| Option               | Explanation                                   | Default          |
+| -------------------- | --------------------------------------------- | ---------------- |
+| `host`               | IP or DNS name 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              |
+
+## Example use
+
+```ruby
+require "train-awsssm"
+train  = Train.create("awsssm", {
+            host:     '172.16.3.12',
+            logger:   Logger.new($stdout, level: :info)
+         })
+conn   = train.connection
+result = conn.run_command("apt upgrade -y")
+conn.close
+```

data/lib/train-awsssm.rb

@@ -0,0 +1,7 @@
+libdir = File.dirname(__FILE__)
+$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
+
+require "train-awsssm/version"
+
+require "train-awsssm/transport"
+require "train-awsssm/connection"

data/lib/train-awsssm/connection.rb

@@ -0,0 +1,143 @@
+require "aws-sdk-ec2"
+require "aws-sdk-ssm"
+require "resolv"
+require "train"
+
+module TrainPlugins
+  module AWSSSM
+    class Connection < Train::Plugins::Transport::BaseConnection
+      def initialize(options)
+        super(options)
+
+        @ssm = Aws::SSM::Client.new
+      end
+
+      def close
+        logger.info format("[AWS-SSM] Closed connection to %s", @options[:host])
+      end
+
+      def uri
+        "aws-ssm://#{@options[:host]}/"
+      end
+
+      def run_command_via_connection(cmd, &data_handler)
+        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)
+      end
+
+      def execute_on_channel(cmd, &data_handler)
+        logger.debug format("[AWS-SSM] Command: '%s'", cmd)
+
+        result = execute_command(@options[:host], cmd)
+
+        stdout = result.standard_output_content || ""
+        stderr = result.standard_error_content || ""
+        exit_status = result.response_code
+
+        [exit_status, stdout, stderr]
+      end
+
+      private
+
+      # Check if this is an IP address
+      def ip_address?(address)
+        !!(address =~ Resolv::IPv4::Regex)
+      end
+
+      # Check if this is a DNS name
+      def dns_name?(address)
+        !ip_address?(address)
+      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")
+      end
+
+      # Resolve EC2 instance ID associated with a primary IP or a DNS entry
+      def 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
+        if dns_name?(address) && !amazon_dns?(address)
+          address = Resolv.getaddress(address)
+          logger.debug format("[AWS-SSM] Resolved non-internal AWS address to %s", address)
+        end
+
+        # Check the primary IPs and hostnames for a match
+        id = instances.detect do |i|
+          [
+            i.private_ip_address,
+            i.public_ip_address,
+            i.private_dns_name,
+            i.public_dns_name,
+          ].include?(address)
+        end&.instance_id
+
+        raise 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
+      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)
+
+      # Retry until the invocation was created on AWS
+      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)
+      end
+
+      # Return if a non-terminal command status was given
+      # @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
+      # @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
+      def execute_command(address, command)
+        instance_id = instance_id(address)
+
+        cmd = @ssm.send_command(instance_ids: [instance_id], document_name: "AWS-RunShellScript", parameters: { "commands": [command] })
+        cmd_id = cmd.command.command_id
+
+        wait_for_invocation(instance_id, 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)
+
+        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]
+        end
+
+        if Time.now - start_time > @options[:execution_timeout]
+          raise format("Timeout waiting for execution")
+        elsif result.status != "Success"
+          raise format('Execution failed with state "%s": %s', result.status, result.standard_error_content || "unknown")
+        end
+
+        result
+      end
+    end
+  end
+end

data/lib/train-awsssm/transport.rb

@@ -0,0 +1,19 @@
+require "train-awsssm/connection"
+
+module TrainPlugins
+  module AWSSSM
+    class Transport < Train.plugin(1)
+      name "awsssm"
+
+      option :host,               required: true
+
+      option :execution_timeout,  default: 60.0
+      option :recheck_invocation, default: 1.0
+      option :recheck_execution,  default: 1.0
+
+      def connection(_instance_opts = nil)
+        @connection ||= TrainPlugins::AWSSSM::Connection.new(@options)
+      end
+    end
+  end
+end

data/lib/train-awsssm/version.rb

@@ -0,0 +1,5 @@
+module TrainPlugins
+  module AWSSSM
+    VERSION = "0.1.0".freeze
+  end
+end

data/train-awsssm.gemspec

@@ -0,0 +1,27 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "train-awsssm/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "train-awsssm"
+  spec.version       = TrainPlugins::AWSSSM::VERSION
+  spec.authors       = ["Thomas Heinen"]
+  spec.email         = ["theinen@tecracer.de"]
+  spec.summary       = "Train Transport for AWS Systems Manager Agents"
+  spec.description   = "Train plugin to use the AWS Systems Manager Agent to execute commands on machines without SSH/WinRM "
+  spec.homepage      = "https://github.com/tecracer_theinen/train-awsssm"
+  spec.license       = "Apache-2.0"
+
+  spec.files = %w{
+    README.md train-awsssm.gemspec Gemfile
+  } + Dir.glob(
+    "lib/**/*", File::FNM_DOTMATCH
+  ).reject { |f| File.directory?(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "train", "~> 2.0"
+  spec.add_dependency "aws-sdk-ec2", "~> 1.129"
+  spec.add_dependency "aws-sdk-ssm", "~> 1.69"
+
+  spec.add_development_dependency "bump", "~> 0.8"
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: train-awsssm
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Thomas Heinen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-01-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: train
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-ec2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.129'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.129'
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-ssm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.69'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.69'
+- !ruby/object:Gem::Dependency
+  name: bump
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: 'Train plugin to use the AWS Systems Manager Agent to execute commands
+  on machines without SSH/WinRM '
+email:
+- theinen@tecracer.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- lib/train-awsssm.rb
+- lib/train-awsssm/connection.rb
+- lib/train-awsssm/transport.rb
+- lib/train-awsssm/version.rb
+- train-awsssm.gemspec
+homepage: https://github.com/tecracer_theinen/train-awsssm
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Train Transport for AWS Systems Manager Agents
+test_files: []