aws_ec2_environment 0.1.0

data/lib/aws_ec2_environment.rb

@@ -0,0 +1,165 @@
+require "aws-sdk-ec2"
+require "socket"
+require "yaml"
+
+class AwsEc2Environment
+  class Error < StandardError; end
+  class BastionNotExpectedError < Error; end
+  class BastionNotFoundError < Error; end
+  class EnvironmentConfigNotFound < Error; end
+
+  require_relative "aws_ec2_environment/ssm_port_forwarding_session"
+  require_relative "aws_ec2_environment/ci_service"
+  require_relative "aws_ec2_environment/config"
+  require_relative "aws_ec2_environment/version"
+
+  attr_reader :config
+
+  def self.from_yaml_file(path, env_name)
+    config = YAML.safe_load_file(path).fetch(env_name.to_s, nil)
+
+    raise EnvironmentConfigNotFound, "#{path} does not have an environment named \"#{env_name}\"" if config.nil?
+
+    new(AwsEc2Environment::Config.new(env_name, config))
+  end
+
+  def initialize(config, logger: Logger.new($stdout))
+    @config = config
+    @logger = logger
+    @ssm_port_forwarding_sessions = []
+  end
+
+  # Lists the IDs of the EC2 instances matched by the environment instance filters
+  #
+  # If an instance does not have a public ip, its private ip will be used instead.
+  def ips
+    ips = ec2_instances.map { |instance| instance.public_ip_address || instance.private_ip_address }
+
+    log "found the following instances: #{ips.join(", ")}"
+
+    ips
+  end
+
+  # Lists the IDs of the EC2 instances matched by the environment instance filters
+  def ids
+    ids = ec2_instances.map(&:instance_id)
+
+    log "found the following instances: #{ids.join(", ")}"
+
+    ids
+  end
+
+  # Lists the hosts to use for sshing into the EC2 instances matched by the environment instance filters.
+  #
+  # If SSM should be used to connect to the instances, then porting sessions will created.
+  def hosts_for_sshing
+    return ips unless @config.use_ssm
+
+    log "using SSM to connect to instances"
+
+    reason = ssm_session_reason
+
+    ids.map { |id| "#{@config.ssm_host.gsub("\#{id}", id)}:#{start_ssh_port_forwarding_session(id, reason)}" }
+  end
+
+  def use_bastion_server?
+    !@config.bastion_filters.nil?
+  end
+
+  # Finds the public ip of the bastion instance for this environment.
+  #
+  # An error will be thrown if any of the following are true:
+  #   - no bastion filters have been provided (indicating a bastion should not be used)
+  #   - no instances are matched
+  #   - multiple instance are matched
+  #   - the matched instance does not have a public ip
+  def bastion_public_ip
+    if @config.bastion_filters.nil?
+      raise BastionNotExpectedError, "The #{@config.env_name} environment is not configured with a bastion"
+    end
+
+    instances = ec2_describe_instances(@config.bastion_filters)
+
+    if instances.length != 1
+      raise(
+        BastionNotFoundError,
+        "#{instances.length} potential bastion instances were found - " \
+        "please ensure your filters are specific enough to only return a single instance"
+      )
+    end
+
+    ip_address = instances[0].public_ip_address
+
+    if ip_address.nil?
+      raise BastionNotFoundError, "a potential bastion instance was found, but it does not have a public ip"
+    end
+
+    log "using bastion with ip #{ip_address}"
+
+    ip_address
+  end
+
+  # Builds a +ProxyCommand+ that can be used with +ssh+ to connect through the bastion instance,
+  # which can also be used with tools like +Capistrano+.
+  #
+  # Calling this command implies that a bastion server is expected to exist,
+  # so an error is thrown if one cannot be found.
+  #
+  # Usage with +Capistrano+:
+  #
+  # <code>
+  # set :ssh_options, proxy: Net::SSH::Proxy::Command.new(instances.build_ssh_bastion_proxy_command)
+  # </code>
+  def build_ssh_bastion_proxy_command
+    "ssh -o StrictHostKeyChecking=no #{@config.bastion_ssh_user}@#{bastion_public_ip} -W %h:%p"
+  end
+
+  def stop_ssh_port_forwarding_sessions
+    @ssm_port_forwarding_sessions.each(&:close)
+  end
+
+  private
+
+  def start_ssh_port_forwarding_session(instance_id, reason)
+    session = AwsEc2Environment::SsmPortForwardingSession.new(instance_id, 22, logger: @logger, reason: reason)
+
+    @ssm_port_forwarding_sessions << session
+
+    session.wait_for_local_port
+  end
+
+  def ssm_session_reason
+    service = AwsEc2Environment::CiService.detect
+
+    # if we're in a CI service, the build id should make it possible to find
+    # the details & logs of this specific run, which will have all the info
+    return "#{service[:name]}, build #{service[:build_id]}" unless service.nil?
+
+    # use the hostname if we're not on a CI service, as it's usually a good
+    # way to identify what physical machine the SSM session was created on
+    hostname = Socket.gethostname
+
+    # knowing the user can generally be a better starting point than the hostname,
+    # so include that too if possible (note, "USERNAME" is for Windows)
+    username = ENV.fetch("USER", ENV.fetch("USERNAME", "<unknown>"))
+
+    "#{username}@#{hostname}"
+  end
+
+  # @return [Aws::EC2::Client]
+  def ec2
+    @ec2 ||= Aws::EC2::Client.new(region: @config.aws_region)
+  end
+
+  def ec2_describe_instances(filters)
+    ec2.describe_instances(filters: filters).reservations.flat_map(&:instances)
+  end
+
+  def ec2_instances
+    ec2_describe_instances(@config.instance_filters)
+  end
+
+  def log(msg)
+    @logger.info "[#{@config.env_name} #{@config.aws_region}] : #{msg}"
+  end
+end

data/sig/aws_ec2_environment/ci_service.rbs

@@ -0,0 +1,7 @@
+class AwsEc2Environment
+  class CiService
+    CI_SERVICES: Array[{ name: String, detect: String | ^() -> bool, build_id_var: String }]
+
+    def self.detect: () -> { name: String, build_id: String }?
+  end
+end

data/sig/aws_ec2_environment/config.rbs

@@ -0,0 +1,24 @@
+# Holds the details about an application environment composed primarily of EC2 instances, including
+#   - what region they're in
+#   - the user to use for sshing
+#   - how to identify those instances
+#   - how to identify the bastion instance to use to connect (if any)
+#   - if SSM should be used to connect to the instances
+class AwsEc2Environment
+  class Config
+    attr_reader env_name: Symbol
+    attr_reader aws_region: String
+    attr_reader ssh_user: String
+    attr_reader instance_filters: Array[Aws::EC2::Types::filter]
+    attr_reader bastion_ssh_user: String
+    attr_reader bastion_filters: Array[Aws::EC2::Types::filter]?
+    attr_reader use_ssm: bool
+    attr_reader ssm_host: String
+
+    def initialize: (Symbol env_name, Hash[String, untyped] attrs) -> void
+
+    private
+
+    def fetch_bastion_details: (Hash[String, untyped] attrs) -> [Array[Aws::EC2::Types::filter]?, String]
+  end
+end

data/sig/aws_ec2_environment/ssm_port_forwarding_session.rbs

@@ -0,0 +1,57 @@
+class AwsEc2Environment
+  class SsmPortForwardingSession
+    class SessionIdNotFoundError < Error
+    end
+
+    class SessionTimedOutError < Error
+    end
+
+    class SessionProcessError < Error
+    end
+
+    attr_reader instance_id: String
+    attr_reader remote_port: Integer
+    attr_reader pid: String
+
+    def initialize: (
+        String instance_id,
+        Integer remote_port,
+        ?local_port: Integer | nil,
+        ?logger: Logger,
+        ?timeout: Numeric,
+        ?reason: String | nil
+      ) -> void
+
+    def close: () -> void
+
+    def wait_for_local_port: () -> Integer
+
+    private
+
+    @logger: Logger
+    @instance_id: String
+    @session_id: String
+    @remote_port: Integer
+    @local_port: Integer?
+    @timeout: Numeric
+    @reader: IO
+    @writer: IO
+    @cmd_output: String
+
+    def ssm_port_forward_cmd: (Integer | nil local_port, String | nil reason) -> String
+
+    # Checks the cmd process output until either the given +pattern+ matches or the +timeout+ is over.
+    #
+    # It returns an array with the result of the match or otherwise +nil+.
+    #
+    # This is effectively a re-implementation of the +File#expect+ method except it captures
+    # the cmd process output over time so we can include it in the case of errors
+    def expect_cmd_output: (Regexp pattern, Numeric timeout) -> (Array[String] | nil)
+
+    # Updates the tracked output of the cmd process with any new data that is available in the buffer,
+    # until the next read will block at which point this method returns.
+    def update_cmd_output: () -> void
+
+    def wait_for_session_id: () -> String
+  end
+end

data/sig/aws_ec2_environment.rbs

@@ -0,0 +1,54 @@
+class AwsEc2Environment
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  class BastionNotExpectedError < Error
+  end
+
+  class BastionNotFoundError < Error
+  end
+
+  class EnvironmentConfigNotFound < Error
+  end
+
+  attr_reader config: Config
+
+  def self.from_yaml_file: (String path, Symbol env_name) -> AwsEc2Environment
+
+  def initialize: (Config config, logger: Logger) -> void
+
+  def ips: () -> Array[String]
+
+  def ids: () -> Array[String]
+
+  def hosts_for_sshing: () -> Array[String]
+
+  def use_bastion_server?: () -> bool
+
+  def bastion_public_ip: () -> String
+
+  def build_ssh_bastion_proxy_command: () -> String
+
+  def stop_ssh_port_forwarding_sessions: () -> void
+
+  private
+
+  @config: Config
+  @logger: Logger
+  @ssm_port_forwarding_sessions: Array[SsmPortForwardingSession]
+  @ec2: Aws::EC2::Client | nil
+
+  def start_ssh_port_forwarding_session: (String instance_id) -> Integer
+
+  def ssm_session_reason: () -> String
+
+  def ec2: () -> Aws::EC2::Client
+
+  def ec2_describe_instances: (Array[Aws::EC2::Types::filter] filters) -> Array[Aws::EC2::Instance]
+
+  def ec2_instances: () -> Array[Aws::EC2::Instance]
+
+  def log: (String msg) -> bool
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: aws_ec2_environment
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Gareth Jones
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2023-08-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-ec2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-ssm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: 
+email:
+- open-source@ackama.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".editorconfig"
+- ".prettierignore"
+- ".prettierrc.json"
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/aws_ec2_environment.rb
+- lib/aws_ec2_environment/ci_service.rb
+- lib/aws_ec2_environment/config.rb
+- lib/aws_ec2_environment/ssm_port_forwarding_session.rb
+- lib/aws_ec2_environment/version.rb
+- sig/aws_ec2_environment.rbs
+- sig/aws_ec2_environment/ci_service.rbs
+- sig/aws_ec2_environment/config.rbs
+- sig/aws_ec2_environment/ssm_port_forwarding_session.rbs
+homepage: https://github.com/ackama/aws_ec2_environment
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ackama/aws_ec2_environment
+  source_code_uri: https://github.com/ackama/aws_ec2_environment
+  changelog_uri: https://github.com/ackama/aws_ec2_environment
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.26
+signing_key: 
+specification_version: 4
+summary: Interact with AWS EC2-based Ruby apps easily
+test_files: []