empeira 0.1.0.pre.alpha.1

data/lib/empeira/vm/interfaces.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Empeira
+  module VM
+    # Intent is saved before netlink changes; uncertain transport outcomes are inspected on retry.
+    # rubocop:disable-next Metrics/ClassLength -- One locked transaction owns device and parent recovery.
+    class Interfaces
+      PARENT = Configuration::VMInterfaces::PARENT
+
+      def initialize(context:, record:, state:, guest:, persist:)
+        @context = context
+        @record = record
+        @state = state
+        @persist = persist
+        @guest = GuestNetwork.new(guest: guest, record: record)
+      end
+
+      def self.desired(context, hostname)
+        Configuration::VMInterfaces.resolve(context.configuration.dig('vm', 'interfaces'), hostname)
+      end
+
+      def self.validate_static!(context, hostname, state)
+        definitions = desired(context, hostname)
+        InterfaceRoutes.validate_static!(definitions, hostname: hostname, config: context.configuration,
+                                                      subnet: state&.dig('peer_network', 'subnet'))
+        definitions
+      end
+
+      def self.valid_inventory?(inventory)
+        return false unless valid_envelope?(inventory)
+
+        inventory['devices'].all? { |name, entry| valid_entry?(name, entry) }
+      end
+
+      def self.valid_envelope?(inventory)
+        inventory.is_a?(Hash) && inventory.keys.sort_by(&:to_s) == %w[devices parent token] &&
+          inventory['token'].is_a?(String) && inventory['token'].match?(/\A[a-f0-9]{32}\z/) &&
+          [true, false].include?(inventory['parent']) && inventory['devices'].is_a?(Hash)
+      end
+
+      def self.valid_entry?(name, entry)
+        return false unless entry.is_a?(Hash) && entry.key?('definition') &&
+                            (entry.keys - %w[definition previous]).empty?
+
+        [entry.fetch('definition'), *entry.values_at('previous').compact].each do |definition|
+          Configuration::VMInterfaces.device!(name, definition, 'vm.interfaces inventory')
+        end
+        true
+      rescue ConfigurationError
+        false
+      end
+
+      # rubocop:disable-next Metrics/AbcSize -- Ordered mutations retain inspectable intent on every failure.
+      def reconcile
+        @desired = self.class.validate_static!(@context, @record.fetch('hostname'), @state)
+        return false if @desired.empty? && !@record.key?('network_interfaces')
+
+        prepare_inventory
+        observe!
+        defaults = @guest.defaults
+        @changed = false
+        prepare_intents
+        prune
+        vlan? ? ensure_parent : remove_parent
+        @desired.each { |name, definition| apply(name, definition) }
+        verify!(defaults)
+        @desired.empty? ? release_inventory : @guest.verify_facter!(@desired)
+        @changed
+      end
+
+      private
+
+      def observe!
+        @guest.load_modules(vlan: vlan?) unless @desired.empty?
+        @guest.refresh
+        names = (@inventory.fetch('devices').keys + @desired.keys + (parent_needed? ? [PARENT] : [])).uniq
+        @ownership.validate!(names)
+        InterfaceRoutes.new(guest: @guest, ownership: @ownership,
+                            hostname: @record.fetch('hostname')).validate!(@desired)
+      end
+
+      def release_inventory
+        @record.delete('network_interfaces')
+        @persist.call
+      end
+
+      def prepare_inventory
+        unless @record.key?('network_interfaces')
+          @record['network_interfaces'] = { 'token' => SecureRandom.hex(16), 'parent' => false, 'devices' => {} }
+          @persist.call
+        end
+        @inventory = @record.fetch('network_interfaces')
+        @ownership = InterfaceOwnership.new(context: @context, record: @record, inventory: @inventory, guest: @guest)
+      end
+
+      def vlan?
+        @desired.values.any? { |definition| definition.key?('vlan_id') }
+      end
+
+      def parent_needed?
+        vlan? || @inventory.fetch('parent')
+      end
+
+      def prune
+        # Snapshot names because confirmed removals change this inventory.
+        @inventory.fetch('devices').keys.each do |name| # rubocop:disable Style/HashEachMethods
+          if @desired.key?(name)
+            observed = @ownership.observed_definition(name)
+            delete_link(name) if observed && observed != @desired.fetch(name)
+            next
+          end
+
+          delete_link(name)
+          @inventory.fetch('devices').delete(name)
+          @persist.call
+        end
+      end
+
+      def prepare_intents
+        @desired.each do |name, definition|
+          entry = @inventory.fetch('devices')[name]
+          next if entry && entry.fetch('definition') == definition
+
+          observed = @ownership.observed_definition(name)
+          @inventory.fetch('devices')[name] = { 'definition' => definition,
+                                                **(observed ? { 'previous' => observed } : {}) }
+          @persist.call
+        end
+      end
+
+      def ensure_parent
+        unless @inventory.fetch('parent')
+          @inventory['parent'] = true
+          @persist.call
+        end
+        create_link(PARENT, {}) unless @guest.links.key?(PARENT)
+        activate(PARENT)
+      end
+
+      def remove_parent
+        return unless @inventory.fetch('parent')
+
+        delete_link(PARENT)
+        @inventory['parent'] = false
+        @persist.call
+      end
+
+      def apply(name, definition)
+        entry = @inventory.fetch('devices').fetch(name)
+        create_link(name, definition) unless @guest.links.key?(name)
+        mark_link(name, definition)
+        configure_address(name, definition)
+        activate(name)
+        @persist.call if entry.delete('previous')
+      end
+
+      def create_link(name, definition)
+        # Linux applies IFLA_ADDRESS on creation; IFLA_IFALIAS needs a subsequent setlink.
+        arguments = ['ip', 'link', 'add', 'name', name, 'address', @ownership.address(name, definition)]
+        arguments += if definition.key?('vlan_id')
+                       ['link', PARENT, 'type', 'vlan', 'id', definition.fetch('vlan_id').to_s]
+                     else
+                       %w[type dummy]
+                     end
+        change(arguments)
+        @ownership.observed_definition(name)
+      end
+
+      def mark_link(name, definition)
+        @ownership.observed_definition(name)
+        marker = @ownership.marker(name, definition)
+        return if @guest.links.fetch(name)['ifalias'] == marker
+
+        change(['ip', 'link', 'set', 'dev', name, 'alias', marker])
+        return if @guest.links.fetch(name)['ifalias'] == marker
+
+        @ownership.conflict!(name, 'ownership alias could not be verified')
+      end
+
+      def configure_address(name, definition)
+        return unless @guest.ipv4(name).empty?
+
+        change(['ip', 'address', 'add', definition.fetch('network'), 'dev', name])
+      end
+
+      def activate(name)
+        mark_link(name, @ownership.observed_definition(name))
+        return if @guest.links.fetch(name).fetch('flags').include?('UP')
+
+        change(['ip', 'link', 'set', 'dev', name, 'up'])
+      end
+
+      def delete_link(name)
+        @guest.refresh
+        return unless @guest.links.key?(name)
+
+        @ownership.deletable!(name)
+        change(['ip', 'link', 'delete', 'dev', name])
+        @ownership.conflict!(name, 'deletion could not be verified') if @guest.links.key?(name)
+      end
+
+      def change(arguments)
+        @guest.command(arguments)
+        @changed = true
+        @guest.refresh
+      end
+
+      def verify!(defaults)
+        @guest.refresh
+        unless @guest.defaults == defaults
+          raise Error, "Host #{@record.fetch('hostname')}, vm.interfaces: default routes changed; Puppet was not run"
+        end
+
+        @desired.each { |name, definition| verify_device!(name, definition) }
+        return unless @inventory.fetch('parent')
+
+        verify_device!(PARENT, {})
+      end
+
+      def verify_device!(name, definition)
+        observed = @ownership.observed_definition(name)
+        link = @guest.links[name]
+        network = definition['network']
+        bindings = @guest.ipv4(name).map { |address| "#{address.fetch('local')}/#{address.fetch('prefixlen')}" }
+        return if observed == definition && active_link?(name, link, definition) &&
+                  bindings == (network ? [network] : [])
+
+        raise Error, "Host #{@record.fetch('hostname')}, interface #{name}, vm.interfaces: " \
+                     'guest type, address or active state verification failed; Puppet was not run'
+      end
+
+      def active_link?(name, link, definition)
+        link.fetch('flags').include?('UP') && link['ifalias'] == @ownership.marker(name, definition) &&
+          %w[UP UNKNOWN].include?(link['operstate'])
+      end
+    end
+  end
+end

data/lib/empeira/vm/management.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Empeira
+  module VM
+    # Numeric-root execution over a private VirtIO port, independent of guest login policy.
+    module Management
+      VERSION = 2
+      SLOTS = 8
+      CHANNEL = 'org.empeira.management.0'
+      DEVICE = "/dev/virtio-ports/#{CHANNEL}".freeze
+      DIRECTORY = '/etc/empeira/management'
+      UNIT = '/etc/systemd/system/empeira-management.service'
+      AGENT = '/usr/local/libexec/empeira-management-agent'
+      SHELL_RC = '/usr/local/libexec/empeira-management-shell-rc'
+      SETUP = '/usr/local/libexec/empeira-management-setup'
+      UPLOADS = '/run/empeira-management'
+
+      def self.validate!(record)
+        return if record['management_layout'] == VERSION
+
+        raise Error, 'Incompatible VM management layout; use node destroy to remove the owned VM, then recreate it'
+      end
+
+      # rubocop:disable-next Metrics/AbcSize -- Seed the service, adapter and one-time regular account together.
+      def self.files(record, system_key:)
+        validate!(record)
+        raise Error, 'VM system SSH requires a public key' if system_key.to_s.empty?
+
+        setup = File.read(resource('setup.sh')).sub('@SYSTEM_SETUP@', File.read(resource('system_account.sh')) +
+                                                                   File.read(resource('system_home.sh')))
+        { AGENT => [File.read(resource('guest_agent.py')), '0755'], UNIT => [service(record), '0644'],
+          SETUP => [setup, '0755'], SHELL_RC => [File.read(resource('shell_rc.sh')), '0644'],
+          "#{DIRECTORY}/system_authorized_keys" => ["#{system_key}\n", '0644'] }.map do |path, entry|
+          { 'path' => path, 'permissions' => entry[1], 'owner' => 'root:root', 'content' => entry[0] }
+        end
+      end
+
+      # rubocop:disable-next Metrics/MethodLength -- Keep the complete private service policy in one literal.
+      def self.service(record)
+        token = record.fetch('peer').fetch('token')
+        raise Error, 'Invalid VM instance identity' unless token.match?(/\A[0-9a-f]{32}\z/)
+
+        <<~UNIT
+          # Managed by Empeira; no SSH, PAM, NSS login or sudo dependency.
+          [Unit]
+          Description=Empeira private VirtIO management
+          After=systemd-udev-trigger.service
+          [Service]
+          Type=simple
+          User=0
+          Group=0
+          UMask=0077
+          RuntimeDirectory=empeira-management
+          RuntimeDirectoryMode=0700
+          ExecStart=/usr/local/libexec/empeira-management-python #{AGENT} #{DEVICE} #{token} #{extra_devices.join(' ')}
+          StandardOutput=null
+          Restart=on-failure
+          RestartSec=2
+          [Install]
+          WantedBy=multi-user.target
+        UNIT
+      end
+
+      def self.resource(name)
+        Pathname(__dir__).join('../../../resources/nodes/management', name)
+      end
+
+      def self.extra_devices
+        (1...SLOTS).map { |slot| "/dev/virtio-ports/org.empeira.management.#{slot}" }
+      end
+    end
+  end
+end

data/lib/empeira/vm/prerequisites.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Empeira
+  module VM
+    class Prerequisites
+      def initialize(engine:, platform:)
+        @engine = engine
+        @platform = platform
+      end
+
+      def verify!(progress: Progress.new, seeds: true)
+        progress.stage(5, 'Checking VM host prerequisites...')
+        results = @engine.required_tools(seeds: seeds).to_h do |tool|
+          [tool, @engine.find(tool) ? 'available' : 'missing']
+        end
+        progress.stage(10, 'Checking hardware acceleration and firmware...')
+        accelerator = check(results, 'Accelerator') { @engine.accelerator }
+        check(results, 'ARM64 firmware') { @engine.firmware || 'not required' }
+        return accelerator if results.values.all? { |value| value == 'available' }
+
+        raise UnavailableFeature, failure_report(results)
+      end
+
+      private
+
+      def failure_report(results)
+        report = results.map { |name, status| "  #{name.ljust(23)} #{status}" }.join("\n")
+        "VM prerequisites are not satisfied (#{@platform.os}/#{@platform.architecture}):\n\n" \
+          "#{report}\n\n#{@platform.vm_install_hint}"
+      end
+
+      def check(results, name)
+        value = yield
+        results[name] = 'available'
+        value
+      rescue Error => e
+        results[name] = e.message
+        nil
+      end
+    end
+  end
+end

data/lib/empeira/vm/qemu.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Empeira
+  module VM
+    # Host capability detection belongs to the VM engine, not the public node provider.
+    class Qemu < Interface
+      EXECUTABLES = { amd64: 'qemu-system-x86_64', arm64: 'qemu-system-aarch64' }.freeze
+
+      def initialize(context:, runner:, executable_path: ENV.fetch('PATH', ''))
+        super(name: 'qemu', context: context, runner: runner)
+        @executable_path = executable_path
+      end
+
+      def executable
+        name = EXECUTABLES.fetch(context.platform.architecture)
+        find(name) || raise(UnavailableFeature, "#{name} is required for VM nodes; install QEMU")
+      end
+
+      def image_tool
+        find('qemu-img') || raise(UnavailableFeature, 'qemu-img is required for VM disks; install QEMU')
+      end
+
+      def accelerator
+        desired = desired_accelerator
+        Platform::Kvm.new(platform: context.platform).verify! if desired == 'kvm'
+        result = runner.run(executable, arguments: ['-accel', 'help'], timeout: 10)
+        return desired if result.success? && result.stdout.lines.any? { |line| line.strip == desired }
+
+        raise UnavailableFeature, "QEMU does not advertise #{desired.upcase} acceleration; no automatic TCG fallback"
+      end
+
+      def available?
+        executable && image_tool && accelerator
+        true
+      rescue UnavailableFeature
+        false
+      end
+
+      private
+
+      def desired_accelerator
+        case context.platform.os
+        when :linux, :wsl then 'kvm'
+        when :macos then 'hvf'
+        else raise UnsupportedPlatform, 'QEMU VM nodes require Linux or macOS'
+        end
+      end
+
+      public
+
+      def required_tools(seeds: true)
+        [EXECUTABLES.fetch(context.platform.architecture), 'qemu-img', 'ssh',
+         *(seeds ? %w[xorriso ssh-keygen] : [])]
+      end
+
+      def preflight!(progress: Progress.new, seeds: true)
+        Prerequisites.new(engine: self, platform: context.platform).verify!(progress: progress, seeds: seeds)
+      end
+
+      def firmware
+        return unless context.platform.architecture == :arm64
+
+        firmware_candidates.find { |path| path.file? && path.readable? } ||
+          raise(UnavailableFeature, 'AArch64 UEFI firmware is required with QEMU')
+      end
+
+      def firmware_candidates
+        root = Pathname(executable).realpath.dirname.parent.join('share')
+        [root.join('qemu/edk2-aarch64-code.fd'), root.join('qemu/QEMU_EFI.fd'),
+         root.join('qemu-efi-aarch64/QEMU_EFI.fd')]
+      end
+
+      def find(name)
+        @executable_path.split(File::PATH_SEPARATOR).filter_map do |directory|
+          path = Pathname(directory).join(name)
+          path.to_s if path.file? && path.executable?
+        end.first
+      end
+    end
+  end
+end