aws-eni 0.1.0

data/lib/aws-eni.rb

@@ -0,0 +1,278 @@
+require 'time'
+require 'aws-sdk'
+require 'aws-eni/version'
+require 'aws-eni/errors'
+require 'aws-eni/meta'
+require 'aws-eni/ifconfig'
+
+module Aws
+  module ENI
+    extend self
+
+    def environment
+      @environment ||= {}.tap do |e|
+        hwaddr = IFconfig['eth0'].hwaddr
+        Meta.open_connection do |conn|
+          e[:instance_id] = Meta.http_get(conn, 'instance-id')
+          e[:availability_zone] = Meta.http_get(conn, 'placement/availability-zone')
+          e[:region] = e[:availability_zone].sub(/(.*)[a-z]/,'\1')
+          e[:vpc_id] = Meta.http_get(conn, "network/interfaces/macs/#{hwaddr}/vpc-id")
+          e[:vpc_cidr] = Meta.http_get(conn, "network/interfaces/macs/#{hwaddr}/vpc-ipv4-cidr-block")
+        end
+        unless e[:vpc_id]
+          raise EnvironmentError, "Unable to detect VPC settings, library incompatible with EC2-Classic"
+        end
+      end.freeze
+    rescue Meta::ConnectionFailed
+      raise EnvironmentError, "Unable to load EC2 meta-data"
+    end
+
+    def owner_tag(new_owner = nil)
+      @owner_tag = new_owner.to_s if new_owner
+      @owner_tag || 'aws-eni script'
+    end
+
+    def client
+      @client ||= Aws::EC2::Client.new(region: environment[:region])
+    end
+
+    # return our internal model of this instance's network configuration on AWS
+    def list(filter = nil)
+      IFconfig.filter(filter).map(&:to_h) if environment
+    end
+
+    # sync local machine's network interface config with the EC2 meta-data
+    # pass dry_run option to check whether configuration is out of sync without
+    # modifying it
+    def configure(filter = nil, options = {})
+      IFconfig.configure(filter, options) if environment
+    end
+
+    # clear local machine's network interface config
+    def deconfigure(filter = nil)
+      IFconfig.deconfigure(filter) if environment
+    end
+
+    # create network interface
+    def create_interface(options = {})
+      timestamp = Time.now.xmlschema
+      params = {}
+      params[:subnet_id] = options[:subnet_id] || IFconfig.first.subnet_id
+      params[:private_ip_address] = options[:primary_ip] if options[:primary_ip]
+      params[:groups] = [*options[:security_groups]] if options[:security_groups]
+      params[:description] = "generated by #{owner_tag} from #{environment[:instance_id]} on #{timestamp}"
+
+      response = client.create_network_interface(params)
+      client.create_tags(resources: [response[:network_interface][:network_interface_id]], tags: [
+        { key: 'created by',   value: owner_tag },
+        { key: 'created on',   value: timestamp },
+        { key: 'created from', value: environment[:instance_id] }
+      ])
+      {
+        id:           response[:network_interface][:network_interface_id],
+        subnet_id:    response[:network_interface][:subnet_id],
+        api_response: response[:network_interface]
+      }
+    end
+
+    # attach network interface
+    def attach_interface(id, options = {})
+      interface = IFconfig[options[:device_number] || options[:name]]
+      raise InvalidParameterError, "Interface #{interface.name} is already in use" if interface.exists?
+
+      params = {}
+      params[:network_interface_id] = id
+      params[:instance_id] = environment[:instance_id]
+      params[:device_index] = interface.device_number
+
+      response = client.attach_network_interface(params)
+      attached = wait_for(10) { interface.exists? }
+      raise TimeoutError, "Timed out waiting for the interface to attach" unless attached
+      interface.configure if options[:configure]
+      interface.enable if options[:enable]
+      {
+        id:           interface.interface_id,
+        name:         interface.name,
+        configured:   options[:configure],
+        api_response: response
+      }
+    end
+
+    # detach network interface
+    def detach_interface(id, options = {})
+      interface = IFconfig.filter(id).first
+      raise InvalidParameterError, "Interface #{interface.name} does not exist" unless interface && interface.exists?
+      if options[:name] && interface.name != options[:name]
+        raise InvalidParameterError, "Interface #{interface.interface_id} not found on #{options[:name]}"
+      end
+      if options[:device_number] && interface.device_number != options[:device_number].to_i
+        raise InvalidParameterError, "Interface #{interface.interface_id} not found at index #{options[:device_number]}"
+      end
+
+      description = client.describe_network_interfaces(filters: [{
+        name: 'attachment.instance-id',
+        values: [environment[:instance_id]]
+      },{
+        name: 'network-interface-id',
+        values: [interface.interface_id]
+      }])
+      description = description[:network_interfaces].first
+      raise UnknownInterfaceError, "Interface attachment could not be located" unless description
+
+      interface.disable
+      interface.deconfigure
+      client.detach_network_interface(
+        attachment_id: description[:attachment][:attachment_id],
+        force: true
+      )
+      deleted = false
+      created_by_us = description.tag_set.any? { |tag| tag.key == 'created by' && tag.value == owner_tag }
+      unless options[:delete] == false || options[:delete].nil? && !created_by_us
+        detached = wait_for(10, 0.3) do
+          !interface.exists? && interface_status(description[:network_interface_id]) == 'available'
+        end
+        raise TimeoutError, "Timed out waiting for the interface to detach" unless detached
+        client.delete_network_interface(network_interface_id: description[:network_interface_id])
+        deleted = true
+      end
+      {
+        id:            description[:network_interface_id],
+        name:          "eth#{description[:attachment][:device_index]}",
+        device_number: description[:attachment][:device_index],
+        created_by_us: created_by_us,
+        deleted:       deleted,
+        api_response:  description
+      }
+    end
+
+    # delete unattached network interfaces
+    def clean_interfaces(filter = nil, options = {})
+      safe_mode = true unless options[:safe_mode] == false
+
+      filters = [
+        { name: 'vpc-id', values: [environment[:vpc_id]] },
+        { name: 'status', values: ['available'] }
+      ]
+      if filter
+        case filter
+        when /^eni-/
+          filters << { name: 'network-interface-id', values: [filter] }
+        when /^subnet-/
+          filters << { name: 'subnet-id', values: [filter] }
+        when /^#{environment[:region]}[a-z]$/
+          filters << { name: 'availability-zone', values: [filter] }
+        else
+          raise InvalidParameterError, "Unknown resource filter: #{filter}"
+        end
+      end
+      if safe_mode
+        filters << { name: 'tag:created by', values: [owner_tag] }
+      end
+
+      descriptions = client.describe_network_interfaces(filters: filters)
+      interfaces = descriptions[:network_interfaces].select do |interface|
+        skip = safe_mode && interface.tag_set.any? do |tag|
+          begin
+            tag.key == 'created on' && Time.now - Time.parse(tag.value) < 60
+          rescue ArgumentError
+            false
+          end
+        end
+        unless skip
+          client.delete_network_interface(network_interface_id: interface[:network_interface_id])
+          true
+        end
+      end
+      {
+        count:        interfaces.count,
+        deleted:      interfaces.map { |eni| eni[:network_interface_id] },
+        api_response: interfaces
+      }
+    end
+
+    # add new private ip using the AWS api and add it to our local ip config
+    def assign_secondary_ip(interface, options = {})
+      raise NoMethodError, "assign_secondary_ip not yet implemented"
+      {
+        private_ip:   '0.0.0.0',
+        device_name:  'eth0',
+        interface_id: 'eni-1a2b3c4d'
+      }
+    end
+
+    # remove a private ip using the AWS api and remove it from local config
+    def unassign_secondary_ip(private_ip, options = {})
+      raise NoMethodError, "unassign_secondary_ip not yet implemented"
+      {
+        private_ip:     '0.0.0.0',
+        device_name:    'eth0',
+        interface_id:   'eni-1a2b3c4d',
+        public_ip:      '0.0.0.0',
+        allocation_id:  'eipalloc-1a2b3c4d',
+        association_id: 'eipassoc-1a2b3c4d',
+        released:       true
+      }
+    end
+
+    # associate a private ip with an elastic ip through the AWS api
+    def associate_elastic_ip(private_ip, options = {})
+      raise NoMethodError, "associate_elastic_ip not yet implemented"
+      {
+        private_ip:     '0.0.0.0',
+        device_name:    'eth0',
+        interface_id:   'eni-1a2b3c4d',
+        public_ip:      '0.0.0.0',
+        allocation_id:  'eipalloc-1a2b3c4d',
+        association_id: 'eipassoc-1a2b3c4d'
+      }
+    end
+
+    # dissociate a public ip from a private ip through the AWS api and
+    # optionally release the public ip
+    def dissociate_elastic_ip(ip, options = {})
+      raise NoMethodError, "dissociate_elastic_ip not yet implemented"
+      {
+        private_ip:     '0.0.0.0',
+        device_name:    'eth0',
+        interface_id:   'eni-1a2b3c4d',
+        public_ip:      '0.0.0.0',
+        allocation_id:  'eipalloc-1a2b3c4d',
+        association_id: 'eipassoc-1a2b3c4d',
+        released:       true
+      }
+    end
+
+    # allocate a new elastic ip address
+    def allocate_elastic_ip
+      raise NoMethodError, "allocate_elastic_ip not yet implemented"
+      {
+        public_ip:     '0.0.0.0',
+        allocation_id: 'eipalloc-1a2b3c4d'
+      }
+    end
+
+    # release the specified elastic ip address
+    def release_elastic_ip(ip, options = {})
+      raise NoMethodError, "release_elastic_ip not yet implemented"
+      {
+        public_ip:     '0.0.0.0',
+        allocation_id: 'eipalloc-1a2b3c4d'
+      }
+    end
+
+    private
+
+    def interface_status(id)
+      resp = client.describe_network_interfaces(network_interface_ids: [id])
+      resp[:network_interfaces].first[:status] unless resp[:network_interfaces].empty?
+    end
+
+    def wait_for(timer = 5, interval = 0.1, &block)
+      until timer < 0 or block.call
+        timer -= interval
+        sleep interval
+      end
+      timer > 0
+    end
+  end
+end

data/lib/aws-eni/errors.rb

@@ -0,0 +1,13 @@
+
+module Aws
+  module ENI
+    class Error < RuntimeError; end
+    class TimeoutError < Error; end
+    class MissingParameterError < Error; end
+    class InvalidParameterError < Error; end
+    class UnknownInterfaceError < Error; end
+    class EnvironmentError < Error; end
+    class CommandError < Error; end
+    class PermissionError < CommandError; end
+  end
+end

data/lib/aws-eni/ifconfig.rb

@@ -0,0 +1,309 @@
+require 'ipaddr'
+require 'open3'
+require 'aws-eni/errors'
+
+module Aws
+  module ENI
+    class IFconfig
+
+      class << self
+        include Enumerable
+
+        attr_accessor :verbose
+
+        # Array-like accessor to automatically instantiate our class
+        def [](index)
+          index = $1.to_i if index.to_s =~ /^(?:eth)?([0-9]+)$/
+          index ||= next_available_index
+          @instance_cache ||= []
+          @instance_cache[index] ||= new("eth#{index}", false)
+        end
+
+        # Purge and deconfigure non-existent interfaces from the cache
+        def clean
+          # exists? will automatically call deconfigure if necessary
+          @instance_cache.map!{ |dev| dev if dev.exists? }
+        end
+
+        # Return array of available ethernet interfaces
+        def existing
+          Dir.entries("/sys/class/net/").grep(/^eth[0-9]+$/){ |name| self[name] }
+        end
+
+        # Return the next unused device index
+        def next_available_index
+          for index in 0..32 do
+            break index unless self[index].exists?
+          end
+        end
+
+        # Iterate over available ethernet interfaces (required for Enumerable)
+        def each(&block)
+          existing.each(&block)
+        end
+
+        # Return array of enabled interfaces
+        def enabled
+          select(&:enabled?)
+        end
+
+        # Configure all available interfaces identified by an optional selector
+        def configure(selector = nil, options = {})
+          filter(selector).reduce(0) do |count, dev|
+            count + dev.configure(options[:dry_run])
+          end
+        end
+
+        # Remove configuration on available interfaces identified by an optional
+        # selector
+        def deconfigure(selector = nil)
+          filter(selector).each(&:deconfigure)
+          true
+        end
+
+        # Return an array of available interfaces identified by name, id,
+        # hwaddr, or subnet id.
+        def filter(match = nil)
+          return existing unless match
+          select{ |dev| dev.is?(match) }.tap do |result|
+            raise UnknownInterfaceError, "No interface found matching \"#{match}\"" if result.empty?
+          end
+        end
+
+        # Execute a command
+        def exec(command, options = {})
+          output = nil
+          verbose = self.verbose || options[:verbose]
+          raise_errors = options[:raise_errors]
+          puts "ip #{command}" if verbose
+
+          Open3.popen3("/sbin/ip #{command}") do |i,o,e,t|
+            unless t.value.success?
+              error_msg = e.read
+              if error_msg =~ /operation not permitted/i
+                raise PermissionError, "Operation not permitted"
+              end
+              warn "Warning: #{error_msg}" if verbose
+              raise CommandError, error_msg if raise_errors
+            end
+            output = o.read
+          end
+          output
+        end
+      end
+
+      attr_reader :name, :device_number, :route_table
+
+      def initialize(name, auto_config = true)
+        unless name =~ /^eth([0-9]+)$/
+          raise UnknownInterfaceError, "Invalid interface: #{name}"
+        end
+        @name = name
+        @device_number = $1.to_i
+        @route_table = @device_number + 10000
+        configure if auto_config
+      end
+
+      # Get our interface's MAC address
+      def hwaddr
+        begin
+          exists? && IO.read("/sys/class/net/#{name}/address").strip
+        rescue Errno::ENOENT
+        end.tap do |address|
+          raise UnknownInterfaceError, "Unknown interface: #{name}" unless address
+        end
+      end
+
+      # Verify device exists on our system
+      def exists?
+        File.directory?("/sys/class/net/#{name}").tap do |exists|
+          deconfigure unless exists || @clean
+        end
+      end
+
+      # Validate and return basic interface metadata
+      def info
+        hwaddr = self.hwaddr
+        unless @meta_cache && hwaddr == @meta_cache[:hwaddr]
+          dev_path = "network/interfaces/macs/#{hwaddr}"
+          Meta.open_connection do |conn|
+            raise Meta::BadResponse unless Meta.http_get(conn, "#{dev_path}/")
+            @meta_cache = {
+              hwaddr: hwaddr,
+              interface_id: Meta.http_get(conn, "#{dev_path}/interface-id"),
+              subnet_id:    Meta.http_get(conn, "#{dev_path}/subnet-id"),
+              subnet_cidr:  Meta.http_get(conn, "#{dev_path}/subnet-ipv4-cidr-block")
+            }.freeze
+          end
+        end
+        @meta_cache
+      end
+
+      def interface_id
+        info[:interface_id]
+      end
+
+      def subnet_id
+        info[:subnet_id]
+      end
+
+      def subnet_cidr
+        info[:subnet_cidr]
+      end
+
+      # Return an array of configured ip addresses (primary + secondary)
+      def local_ips
+        list = exec("addr show dev #{name} primary") +
+               exec("addr show dev #{name} secondary")
+        list.lines.grep(/inet ([0-9\.]+)\/.* #{name}/i){ $1 }
+      end
+
+      def public_ips
+        ip_assoc = {}
+        dev_path = "network/interfaces/macs/#{hwaddr}"
+        Meta.open_connection do |conn|
+          # return an array of configured ip addresses (primary + secondary)
+          Meta.http_get(conn, "#{dev_path}/ipv4-associations/").to_s.each_line do |public_ip|
+            public_ip.strip!
+            local_ip = Meta.http_get(conn, "#{dev_path}/ipv4-associations/#{public_ip}")
+            ip_assoc[local_ip] = public_ip
+          end
+        end
+        ip_assoc
+      end
+
+      # Enable our interface
+      def enable
+        exec("link set dev #{name} up")
+      end
+
+      # Disable our interface
+      def disable
+        exec("link set dev #{name} down")
+      end
+
+      # Check whether our interface is enabled
+      def enabled?
+        exists? && exec("link show up").include?(name)
+      end
+
+      # Initialize a new interface config
+      def configure(dry_run = false)
+        changes = 0
+        info = self.info
+        prefix = info[:subnet_cidr].split('/').last.to_i
+        gateway = IPAddr.new(info[:subnet_cidr]).succ.to_s
+
+        meta_ips = Meta.get("network/interfaces/macs/#{info[:hwaddr]}/local-ipv4s").lines.map(&:strip)
+        local_primary, *local_aliases = local_ips
+        meta_primary, *meta_aliases = meta_ips
+
+        # ensure primary ip address is correct
+        if name != 'eth0' && local_primary != meta_primary
+          unless dry_run
+            deconfigure
+            exec("addr add #{meta_primary}/#{prefix} brd + dev #{name}")
+            exec("route add default via #{gateway} dev #{name} table #{route_table}")
+            exec("route flush cache")
+          end
+          changes += 1
+        end
+
+        # add missing secondary ips
+        (meta_aliases - local_aliases).each do |ip|
+          exec("addr add #{ip}/#{prefix} brd + dev #{name}") unless dry_run
+          changes += 1
+        end
+
+        # remove extra secondary ips
+        (local_aliases - meta_aliases).each do |ip|
+          exec("addr del #{ip}/#{prefix} dev #{name}") unless dry_run
+          changes += 1
+        end
+
+        unless name == 'eth0'
+          rules_to_add = meta_ips || []
+          exec("rule list").lines.grep(/^([0-9]+):.*\s([0-9\.]+)\s+lookup #{route_table}/) do
+            unless rules_to_add.delete($2)
+              exec("rule delete pref #{$1}") unless dry_run
+              changes += 1
+            end
+          end
+          rules_to_add.each do |ip|
+            exec("rule add from #{ip} lookup #{route_table}") unless dry_run
+            changes += 1
+          end
+        end
+
+        @clean = nil
+        changes
+      end
+
+      # Remove configuration for an interface
+      def deconfigure
+        # assume eth0 primary ip is managed by dhcp
+        if name == 'eth0'
+          exec("addr flush dev eth0 secondary")
+        else
+          exec("rule list").lines.grep(/^([0-9]+):.*lookup #{route_table}/) do
+            exec("rule delete pref #{$1}")
+          end
+          exec("addr flush dev #{name}")
+          exec("route flush table #{route_table}")
+          exec("route flush cache")
+        end
+        @clean = true
+      end
+
+      # Add a secondary ip to this interface
+      def add_alias(ip)
+        prefix = info[:subnet_cidr].split('/').last.to_i
+        exec("addr add #{ip}/#{prefix} brd + dev #{name}")
+
+        unless name == 'eth0' || exec("rule list") =~ /from #{ip} lookup #{route_table}/
+          exec("rule add from #{ip} lookup #{route_table}")
+        end
+      end
+
+      # Remove a secondary ip from this interface
+      def remove_alias
+        prefix = info[:subnet_cidr].split('/').last.to_i
+        exec("addr del #{ip}/#{prefix} dev #{name}")
+
+        if name != 'eth0' && exec("rule list") =~ /([0-9]+):\s+from #{ip} lookup #{route_table}/
+          exec("rule delete pref #{$1}")
+        end
+      end
+
+      # Identify this interface by one of its attributes
+      def is?(match)
+        if match == name
+          true
+        else
+          info = self.info
+          match == info[:interface_id] || match == info[:hwaddr] || match == info[:subnet_id]
+        end
+      end
+
+      # Return an array representation of our interface config, including public
+      # ip associations and enabled status
+      def to_h
+        info.merge({
+          name:          name,
+          device_number: device_number,
+          route_table:   route_table,
+          local_ips:     local_ips,
+          public_ips:    public_ips,
+          enabled:       enabled?
+        })
+      end
+
+      private
+
+      # Alias for static method
+      def exec(command, options = {})
+        self.class.exec(command, options)
+      end
+    end
+  end
+end