You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/agent/internal/hypervisor/backend.go

698 lines
24 KiB
Go

// Package hypervisor defines the host-facing seam used by the Go agent.
//
// The request validation, UUID ownership and read-back guarantees are shared
// by the deterministic fake backend and the Linux virsh adapter. The adapter
// uses a fixed absolute executable and argv boundary while a native libvirt
// binding remains an optional future implementation.
package hypervisor
import (
"bytes"
"context"
"crypto/sha256"
"encoding/hex"
"encoding/xml"
"errors"
"fmt"
"io"
"strings"
"sync"
"time"
"g.luoli.live/root/virt/agent/internal/domainxml"
"g.luoli.live/root/virt/agent/internal/storagepolicy"
)
var (
// ErrInvalidUUID means that a caller supplied a non-canonical UUID. The
// agent does not derive resource identity from names or user input.
ErrInvalidUUID = errors.New("invalid domain UUID")
// ErrUUIDMismatch means the requested UUID and the UUID in domain XML are
// not the same. A backend must never silently redefine identity.
ErrUUIDMismatch = errors.New("domain UUID does not match request")
// ErrDomainNotFound means that a targeted read-back found no definition.
ErrDomainNotFound = errors.New("domain definition not found")
// ErrDomainConflict means an existing UUID was defined with different XML.
ErrDomainConflict = errors.New("domain definition conflicts with existing UUID")
// ErrDomainActive means an undefine request was rejected because the
// targeted domain is still active. The Agent never force-destroys a guest
// as part of deletion; callers must perform an explicit, separately
// journaled power operation first.
ErrDomainActive = errors.New("domain is active")
// ErrDeleteReadbackMismatch means an undefine command returned but the
// subsequent targeted read-back could not prove that the definition is
// absent. It is intentionally not a definitive error: the operation may
// have committed and must remain uncertain until a later observation.
ErrDeleteReadbackMismatch = errors.New("domain deletion read-back mismatch")
// ErrReadbackMismatch means the backend returned XML that cannot prove the
// requested UUID and firmware policy were retained.
ErrReadbackMismatch = errors.New("domain definition read-back mismatch")
// ErrCapabilityPolicy means a host capability snapshot cannot satisfy the
// product's mandatory EFI/q35/no-Secure-Boot policy.
ErrCapabilityPolicy = errors.New("hypervisor capability policy is not satisfied")
)
// fakeLoaderPath is the deterministic firmware descriptor used by the
// in-memory backend. A real host adapter must replace this with a path selected
// from its fresh domain-capabilities probe; keeping the fake explicit ensures
// its read-back contract exercises the same pflash/readonly policy as libvirt.
const fakeLoaderPath = "/usr/share/OVMF/OVMF_CODE_4M.fd"
// IsDefinitive reports errors that prove the requested operation was rejected
// before an ambiguous host-side commit. Transport failures and command
// cancellations intentionally return false and must remain uncertain until a
// read-back/reconcile step proves the result.
func IsDefinitive(err error) bool {
if err == nil {
return false
}
return errors.Is(err, ErrInvalidUUID) ||
errors.Is(err, ErrUUIDMismatch) ||
errors.Is(err, ErrDomainConflict) ||
errors.Is(err, ErrDomainActive) ||
errors.Is(err, ErrInvalidPowerAction) ||
errors.Is(err, ErrPowerActionRejected) ||
errors.Is(err, ErrCapabilityPolicy) ||
errors.Is(err, ErrDomainNotFound) ||
storagepolicy.IsDefinitive(err) ||
errors.Is(err, domainxml.ErrInvalidXML) ||
errors.Is(err, domainxml.ErrUnsupportedPlatform) ||
errors.Is(err, domainxml.ErrPolicyViolation)
}
// CapabilitySnapshot is the small, serializable host capability contract.
//
// SecureBootCapable describes what the host firmware/QEMU stack can do; it is
// not a request to enable Secure Boot. SecureBootDisabled is an explicit
// policy fact and must be true before a domain can be defined. Keeping these
// fields separate prevents a host that supports Secure Boot from accidentally
// turning it on when the product policy requires it to remain off.
type CapabilitySnapshot struct {
Backend string `json:"backend,omitempty"`
LibvirtVersion string `json:"libvirt_version,omitempty"`
QEMUVersion string `json:"qemu_version,omitempty"`
Architecture string `json:"architecture,omitempty"`
UEFI bool `json:"uefi"`
Q35 bool `json:"q35"`
SecureBootCapable bool `json:"secure_boot_capable"`
SecureBootDisabled bool `json:"secure_boot_disabled"`
QGA bool `json:"qga"`
Snapshots bool `json:"snapshots"`
CloudInit bool `json:"cloud_init"`
// StartupScript is a raw host/guest observation when a backend can prove
// it. The Agent-side NoCloud artifact implementation is advertised by the
// capability provider separately; this field must not be used as a proxy
// for that implementation.
StartupScript bool `json:"startup_script"`
ObservedAt time.Time `json:"observed_at"`
}
// DefaultCapabilitySnapshot is useful for an in-memory backend and documents
// the minimum host policy expected by the first Linux adapter. It does not
// claim that a real host has these features; a real Probe must replace it with
// a read-only libvirt capability result.
func DefaultCapabilitySnapshot() CapabilitySnapshot {
return CapabilitySnapshot{
Backend: "fake",
Architecture: "x86_64",
UEFI: true,
Q35: true,
SecureBootDisabled: true,
CloudInit: true,
StartupScript: true,
ObservedAt: time.Now().UTC(),
}
}
// CheckEFIQ35NoSecureBoot is the shared policy gate for create, reinstall and
// rescue definitions. It is deliberately independent from the libvirt
// binding, so a binding cannot bypass the invariant.
func CheckEFIQ35NoSecureBoot(snapshot CapabilitySnapshot) error {
missing := make([]string, 0, 3)
if !snapshot.UEFI {
missing = append(missing, "efi")
}
if !snapshot.Q35 {
missing = append(missing, "q35")
}
if !snapshot.SecureBootDisabled {
missing = append(missing, "secure-boot-disabled")
}
if len(missing) != 0 {
return fmt.Errorf("%w: missing %s", ErrCapabilityPolicy, strings.Join(missing, ", "))
}
return nil
}
// ValidatePlatformPolicy is a method-shaped alias convenient for callers that
// receive a snapshot from a Backend.
func (snapshot CapabilitySnapshot) ValidatePlatformPolicy() error {
return CheckEFIQ35NoSecureBoot(snapshot)
}
// ProbeResult preserves the observed snapshot and gives callers a single
// typed result for a read-only host probe.
type ProbeResult struct {
Capabilities CapabilitySnapshot `json:"capabilities"`
ObservedAt time.Time `json:"observed_at"`
}
// DefineRequest is the only definition input accepted by Backend. UUID is
// mandatory and must equal the direct <uuid> child in XML. XML is copied by
// implementations so callers cannot mutate a stored definition after return.
type DefineRequest struct {
UUID string
XML []byte
}
// Definition is a read-back-safe domain definition. Revision is local to a
// backend and is useful for detecting stale observations; it is not a
// libvirt generation number.
type Definition struct {
UUID string `json:"uuid"`
XML []byte `json:"-"`
Revision uint64 `json:"revision"`
DefinedAt time.Time `json:"defined_at"`
}
// DomainDeletionObservation is a read-only, identity-bound snapshot used by
// delete preflight and uncertain-operation reconciliation. It deliberately
// contains only a digest of the inactive XML; host paths, disk names and
// other definition details never cross the Agent API boundary.
type DomainDeletionObservation struct {
UUID string `json:"uuid"`
Present bool `json:"present"`
State DomainPowerState `json:"state,omitempty"`
Active bool `json:"active"`
XMLHash string `json:"xml_hash,omitempty"`
ObservedAt time.Time `json:"observed_at"`
}
// DomainDeleteResult records the narrow mutation performed by DeleteDomain.
// Removed means only the libvirt domain definition was undefined. Storage
// and network objects are explicitly reported untouched so a caller cannot
// mistake this operation for the panel's full VM cleanup workflow.
type DomainDeleteResult struct {
UUID string `json:"uuid"`
Existed bool `json:"existed"`
AlreadyAbsent bool `json:"already_absent"`
Removed bool `json:"removed"`
StateBefore DomainPowerState `json:"state_before,omitempty"`
XMLHash string `json:"xml_hash,omitempty"`
StorageRemoved bool `json:"storage_removed"`
NetworkChanged bool `json:"network_changed"`
ObservedAt time.Time `json:"observed_at"`
}
// Backend is the intentionally small host boundary. Methods are context
// aware because a panel request timeout must cancel an in-flight RPC without
// leaving an unbounded libvirt call behind.
//
// Implementations must not infer UUIDs, enumerate tenant domains, or return a
// successful DefineDomain result until a subsequent read-back can prove that
// the requested XML and UUID were retained.
type Backend interface {
Probe(context.Context) (ProbeResult, error)
Capabilities(context.Context) (CapabilitySnapshot, error)
DefineDomain(context.Context, DefineRequest) (Definition, error)
ReadDomainXML(context.Context, string) ([]byte, error)
PowerDomain(context.Context, string, PowerAction) (PowerResult, error)
// ReadDomainPowerState is a read-only host probe used by reconciliation.
// It must never invoke a lifecycle command or otherwise mutate the domain.
ReadDomainPowerState(context.Context, string) (DomainPowerState, error)
// InspectDomainForDeletion is a read-only, exact-UUID preflight. It must
// never undefine, power off, remove storage, or touch host networking.
InspectDomainForDeletion(context.Context, string) (DomainDeletionObservation, error)
// DeleteDomain only undefines one inactive domain definition. Implementations
// must perform a targeted absence read-back before returning success; any
// lost/ambiguous read-back must return an error that the API journals as
// uncertain. Disk and network cleanup are outside this seam.
DeleteDomain(context.Context, string) (DomainDeleteResult, error)
}
// LoaderPathProvider is an optional host-bound capability seam. Implementations
// must select the path from a fresh, read-only domain-capabilities observation;
// callers must not persist or accept a loader path supplied by the panel.
// Keeping this separate from Backend lets older test doubles and future native
// bindings adopt the create pipeline incrementally without weakening the
// existing lifecycle interface.
type LoaderPathProvider interface {
PreferredNonSecureLoaderPath(context.Context) (string, error)
}
// ReadbackDomain obtains and validates one explicit UUID from a Backend. It
// is the common post-define assertion used by future libvirt implementations.
func ReadbackDomain(ctx context.Context, backend Backend, uuid string) (Definition, error) {
if backend == nil {
return Definition{}, fmt.Errorf("%w: backend is nil", ErrReadbackMismatch)
}
canonical, err := CanonicalUUID(uuid)
if err != nil {
return Definition{}, err
}
xmlData, err := backend.ReadDomainXML(ctx, canonical)
if err != nil {
return Definition{}, err
}
if err := domainxml.Validate(xmlData); err != nil {
return Definition{}, fmt.Errorf("%w: firmware policy: %v", ErrReadbackMismatch, err)
}
observed, err := domainUUID(xmlData)
if err != nil {
return Definition{}, fmt.Errorf("%w: %v", ErrReadbackMismatch, err)
}
if observed != canonical {
return Definition{}, fmt.Errorf("%w: requested %s, observed %s", ErrReadbackMismatch, canonical, observed)
}
return Definition{UUID: observed, XML: cloneBytes(xmlData), DefinedAt: time.Now().UTC()}, nil
}
// FakeBackend is a deterministic, concurrency-safe backend for API tests and
// local development. It stores only normalized domain XML in memory and does
// not invoke a host command or a libvirt socket.
type FakeBackend struct {
mu sync.RWMutex
caps CapabilitySnapshot
probeErr error
domains map[string]Definition
states map[string]DomainPowerState
nextRev uint64
// mutationMu serializes define, lifecycle and undefine sequences. Reads do
// not take this lock and remain safe through mu's snapshot semantics.
mutationMu sync.Mutex
}
// NewFakeBackend creates a backend with the supplied capability snapshot.
// Callers that want the documented happy-path host can pass
// DefaultCapabilitySnapshot().
func NewFakeBackend(snapshot CapabilitySnapshot) *FakeBackend {
if snapshot.ObservedAt.IsZero() {
snapshot.ObservedAt = time.Now().UTC()
}
return &FakeBackend{
caps: snapshot,
domains: make(map[string]Definition),
states: make(map[string]DomainPowerState),
}
}
// SetProbeError configures a deterministic probe failure for tests. The
// error is retained as-is and never exposed as a secret by this package.
func (f *FakeBackend) SetProbeError(err error) {
if f == nil {
return
}
f.mu.Lock()
f.probeErr = err
f.mu.Unlock()
}
// Probe performs a read-only capability check.
func (f *FakeBackend) Probe(ctx context.Context) (ProbeResult, error) {
if err := contextErr(ctx); err != nil {
return ProbeResult{}, err
}
f.mu.RLock()
err := f.probeErr
caps := f.caps
f.mu.RUnlock()
if err != nil {
return ProbeResult{}, err
}
if err := CheckEFIQ35NoSecureBoot(caps); err != nil {
return ProbeResult{}, err
}
if err := contextErr(ctx); err != nil {
return ProbeResult{}, err
}
now := time.Now().UTC()
caps.ObservedAt = now
return ProbeResult{Capabilities: caps, ObservedAt: now}, nil
}
// Capabilities returns a copy of the latest fake capability snapshot. A
// future binding may refresh this from libvirt's capabilities XML instead.
func (f *FakeBackend) Capabilities(ctx context.Context) (CapabilitySnapshot, error) {
if err := contextErr(ctx); err != nil {
return CapabilitySnapshot{}, err
}
f.mu.RLock()
caps := f.caps
err := f.probeErr
f.mu.RUnlock()
if err != nil {
return CapabilitySnapshot{}, err
}
if err := contextErr(ctx); err != nil {
return CapabilitySnapshot{}, err
}
caps.ObservedAt = time.Now().UTC()
return caps, nil
}
// PreferredNonSecureLoaderPath mirrors the real host seam with a deterministic
// descriptor. The fake still probes first so tests exercise the same fresh
// capability/error boundary as a libvirt adapter.
func (f *FakeBackend) PreferredNonSecureLoaderPath(ctx context.Context) (string, error) {
if _, err := f.Probe(ctx); err != nil {
return "", err
}
return fakeLoaderPath, nil
}
// DefineDomain normalizes and stores one explicit definition. Re-defining an
// identical UUID/XML pair is idempotent; redefining the UUID with different
// XML is rejected rather than overwriting an unknown guest.
func (f *FakeBackend) DefineDomain(ctx context.Context, request DefineRequest) (Definition, error) {
if err := contextErr(ctx); err != nil {
return Definition{}, err
}
f.mutationMu.Lock()
defer f.mutationMu.Unlock()
// A request can wait behind another host mutation. Re-check cancellation
// before beginning a new definition sequence.
if err := contextErr(ctx); err != nil {
return Definition{}, err
}
canonical, err := CanonicalUUID(request.UUID)
if err != nil {
return Definition{}, err
}
normalized, err := domainxml.NormalizeWithLoader(request.XML, fakeLoaderPath)
if err != nil {
return Definition{}, fmt.Errorf("normalize domain XML: %w", err)
}
observed, err := domainUUID(normalized)
if err != nil {
return Definition{}, fmt.Errorf("domain XML UUID: %w", err)
}
if observed != canonical {
return Definition{}, fmt.Errorf("%w: requested %s, XML contains %s", ErrUUIDMismatch, canonical, observed)
}
if err := contextErr(ctx); err != nil {
return Definition{}, err
}
caps, err := f.Capabilities(ctx)
if err != nil {
return Definition{}, err
}
if err := CheckEFIQ35NoSecureBoot(caps); err != nil {
return Definition{}, err
}
f.mu.Lock()
defer f.mu.Unlock()
if existing, ok := f.domains[canonical]; ok {
if bytes.Equal(existing.XML, normalized) {
return cloneDefinition(existing), nil
}
return Definition{}, fmt.Errorf("%w: %s", ErrDomainConflict, canonical)
}
f.nextRev++
definition := Definition{
UUID: canonical,
XML: cloneBytes(normalized),
Revision: f.nextRev,
DefinedAt: time.Now().UTC(),
}
f.domains[canonical] = cloneDefinition(definition)
f.states[canonical] = StateShutoff
return cloneDefinition(definition), nil
}
// ReadDomainXML returns a copy of one exact UUID's inactive definition.
func (f *FakeBackend) ReadDomainXML(ctx context.Context, uuid string) ([]byte, error) {
if err := contextErr(ctx); err != nil {
return nil, err
}
canonical, err := CanonicalUUID(uuid)
if err != nil {
return nil, err
}
f.mu.RLock()
definition, ok := f.domains[canonical]
f.mu.RUnlock()
if !ok {
return nil, fmt.Errorf("%w: %s", ErrDomainNotFound, canonical)
}
if err := contextErr(ctx); err != nil {
return nil, err
}
return cloneBytes(definition.XML), nil
}
// ReadDefinition returns metadata as well as XML for tests and future
// adapters. It is deliberately not part of Backend so a libvirt binding only
// needs the minimal read-back method above.
func (f *FakeBackend) ReadDefinition(ctx context.Context, uuid string) (Definition, error) {
if err := contextErr(ctx); err != nil {
return Definition{}, err
}
canonical, err := CanonicalUUID(uuid)
if err != nil {
return Definition{}, err
}
f.mu.RLock()
definition, ok := f.domains[canonical]
f.mu.RUnlock()
if !ok {
return Definition{}, fmt.Errorf("%w: %s", ErrDomainNotFound, canonical)
}
return cloneDefinition(definition), nil
}
// InspectDomainForDeletion performs the exact-UUID, read-only preflight used
// by DeleteDomain and its reconcile path. An absent definition is a valid
// observation rather than an error: delete is idempotent at the definition
// boundary, while transport/read failures remain errors and therefore
// uncertain to the operation layer.
func (f *FakeBackend) InspectDomainForDeletion(ctx context.Context, uuid string) (DomainDeletionObservation, error) {
if err := contextErr(ctx); err != nil {
return DomainDeletionObservation{}, err
}
canonical, err := CanonicalUUID(uuid)
if err != nil {
return DomainDeletionObservation{}, err
}
f.mu.RLock()
definition, present := f.domains[canonical]
state := f.states[canonical]
f.mu.RUnlock()
if !present {
return DomainDeletionObservation{
UUID: canonical,
Present: false,
ObservedAt: time.Now().UTC(),
}, nil
}
if err := contextErr(ctx); err != nil {
return DomainDeletionObservation{}, err
}
if state == "" {
state = StateShutoff
}
observed, err := domainUUID(definition.XML)
if err != nil || observed != canonical {
return DomainDeletionObservation{}, fmt.Errorf("%w: requested %s", ErrReadbackMismatch, canonical)
}
return DomainDeletionObservation{
UUID: canonical,
Present: true,
State: state,
Active: state.IsActive(),
XMLHash: hashDomainXML(definition.XML),
ObservedAt: time.Now().UTC(),
}, nil
}
// DeleteDomain removes only one inactive definition. The operation is fenced
// by the fake's mutation lock and proves absence from a fresh read-back before
// returning success. No disk or network map exists in this backend, so those
// result fields remain explicit false values.
func (f *FakeBackend) DeleteDomain(ctx context.Context, uuid string) (DomainDeleteResult, error) {
if err := contextErr(ctx); err != nil {
return DomainDeleteResult{}, err
}
canonical, err := CanonicalUUID(uuid)
if err != nil {
return DomainDeleteResult{}, err
}
f.mutationMu.Lock()
defer f.mutationMu.Unlock()
if err := contextErr(ctx); err != nil {
return DomainDeleteResult{}, err
}
observation, err := f.InspectDomainForDeletion(ctx, canonical)
if err != nil {
return DomainDeleteResult{UUID: canonical}, err
}
if !observation.Present {
return DomainDeleteResult{
UUID: canonical,
AlreadyAbsent: true,
Removed: true,
ObservedAt: time.Now().UTC(),
}, nil
}
if observation.Active {
return DomainDeleteResult{
UUID: canonical,
Existed: true,
StateBefore: observation.State,
XMLHash: observation.XMLHash,
ObservedAt: time.Now().UTC(),
}, fmt.Errorf("%w: %s", ErrDomainActive, canonical)
}
// Remove the definition only after the read-only preflight proved the
// canonical UUID and inactive state. Keep the state map in lockstep; no
// storage or network cleanup is attempted.
f.mu.Lock()
delete(f.domains, canonical)
delete(f.states, canonical)
f.mu.Unlock()
if err := contextErr(ctx); err != nil {
return DomainDeleteResult{
UUID: canonical,
Existed: true,
StateBefore: observation.State,
XMLHash: observation.XMLHash,
ObservedAt: time.Now().UTC(),
}, err
}
after, err := f.InspectDomainForDeletion(ctx, canonical)
if err != nil {
return DomainDeleteResult{
UUID: canonical,
Existed: true,
StateBefore: observation.State,
XMLHash: observation.XMLHash,
ObservedAt: time.Now().UTC(),
}, err
}
if after.Present {
return DomainDeleteResult{
UUID: canonical,
Existed: true,
StateBefore: observation.State,
XMLHash: observation.XMLHash,
ObservedAt: time.Now().UTC(),
}, fmt.Errorf("%w: %s", ErrDeleteReadbackMismatch, canonical)
}
return DomainDeleteResult{
UUID: canonical,
Existed: true,
Removed: true,
StateBefore: observation.State,
XMLHash: observation.XMLHash,
StorageRemoved: false,
NetworkChanged: false,
ObservedAt: after.ObservedAt,
}, nil
}
func contextErr(ctx context.Context) error {
if ctx == nil {
return nil
}
select {
case <-ctx.Done():
return ctx.Err()
default:
return nil
}
}
func cloneBytes(value []byte) []byte {
return append([]byte(nil), value...)
}
func cloneDefinition(value Definition) Definition {
value.XML = cloneBytes(value.XML)
return value
}
// CanonicalUUID accepts the UUID forms libvirt receives from the panel and
// returns lower-case 8-4-4-4-12 text. Version and variant bits are purposely
// not constrained: libvirt accepts operator-supplied UUIDs outside RFC 4122
// version ranges, while the identity shape still must be unambiguous.
func CanonicalUUID(value string) (string, error) {
value = strings.ToLower(strings.TrimSpace(value))
if len(value) != 36 {
return "", fmt.Errorf("%w: expected 36 characters", ErrInvalidUUID)
}
for index, char := range value {
if index == 8 || index == 13 || index == 18 || index == 23 {
if char != '-' {
return "", fmt.Errorf("%w: separator at position %d", ErrInvalidUUID, index)
}
continue
}
if !isHex(char) {
return "", fmt.Errorf("%w: non-hex character at position %d", ErrInvalidUUID, index)
}
}
return value, nil
}
func isHex(value rune) bool {
return value >= '0' && value <= '9' || value >= 'a' && value <= 'f'
}
func hashDomainXML(data []byte) string {
digest := sha256.Sum256(data)
return hex.EncodeToString(digest[:])
}
// domainUUID extracts only the direct <uuid> child. Nested metadata fields
// are not identity and must not satisfy this check.
func domainUUID(data []byte) (string, error) {
decoder := xml.NewDecoder(bytes.NewReader(data))
depth := 0
rootSeen := false
var value string
found := false
for {
token, err := decoder.Token()
if errors.Is(err, io.EOF) {
break
}
if err != nil {
return "", fmt.Errorf("%w: malformed XML: %v", ErrUUIDMismatch, err)
}
switch element := token.(type) {
case xml.StartElement:
if !rootSeen {
rootSeen = true
if element.Name.Local != "domain" || element.Name.Space != "" {
return "", fmt.Errorf("%w: root is not <domain>", ErrUUIDMismatch)
}
} else if depth == 1 && element.Name.Space == "" && element.Name.Local == "uuid" {
if found {
return "", fmt.Errorf("%w: duplicate direct <uuid>", ErrUUIDMismatch)
}
found = true
var text string
if err := decoder.DecodeElement(&text, &element); err != nil {
return "", fmt.Errorf("%w: read <uuid>: %v", ErrUUIDMismatch, err)
}
value = strings.TrimSpace(text)
// DecodeElement consumes the matching EndElement. The outer
// depth update below must therefore not be applied to this child.
continue
}
depth++
case xml.EndElement:
depth--
}
}
if !rootSeen || depth != 0 || !found {
return "", fmt.Errorf("%w: direct <uuid> is missing", ErrUUIDMismatch)
}
canonical, err := CanonicalUUID(value)
if err != nil {
return "", fmt.Errorf("%w: %v", ErrUUIDMismatch, err)
}
return canonical, nil
}