feat(backup): add agent readiness probe

go
codex 2 weeks ago
parent f4b31f0b53
commit 20a9984c02

@ -542,6 +542,15 @@ func (s *Server) routeVMs(w http.ResponseWriter, r *http.Request, segments []str
}
switch segments[3] {
case "backup-readiness":
if len(segments) == 4 && r.Method == http.MethodGet {
if !requireManage(w, actor) {
return
}
result, err := s.Hypervisor.GetBackupReadiness(r.Context(), uuid)
writeResult(w, result, err)
return
}
case "backups":
if len(segments) == 4 && r.Method == http.MethodPost {
if !requireManage(w, actor) {

@ -40,6 +40,8 @@ type testHypervisor struct {
cleanupBackupLast hypervisor.CleanupBackupWorkspaceRequest
inspectionResult *hypervisor.OperationInspection
inspectionErr error
backupReadiness hypervisor.BackupReadiness
backupReadinessErr error
}
type apiFailure struct {
@ -63,6 +65,10 @@ func (h *testHypervisor) ListVMs(context.Context) ([]hypervisor.VMMetadata, erro
return []hypervisor.VMMetadata{}, nil
}
func (h *testHypervisor) GetBackupReadiness(context.Context, string) (hypervisor.BackupReadiness, error) {
return h.backupReadiness, h.backupReadinessErr
}
func (h *testHypervisor) ConfigureStorage(context.Context, hypervisor.StorageConfigurationRequest) (hypervisor.StorageConfigurationResult, error) {
h.mu.Lock()
h.configureCalls++
@ -228,6 +234,41 @@ func TestLegacyDailyTrafficRouteIsRemoved(t *testing.T) {
}
}
func TestBackupReadinessIsBoundedReadOnlyEvidence(t *testing.T) {
api := newTestAPI(t)
api.hv.backupReadiness = hypervisor.BackupReadiness{
Eligible: false, Retryable: true, Reason: "backup_rescue_active",
}
const uuid = "123e4567-e89b-42d3-a456-426614174000"
response := api.request(t, http.MethodGet,
"/v1/vms/"+uuid+"/backup-readiness", nil,
auth.Actor{UserID: 1, CanManage: true})
if response.Code != http.StatusOK {
t.Fatalf("backup readiness status=%d body=%s",
response.Code, response.Body.String())
}
var readiness hypervisor.BackupReadiness
if err := json.Unmarshal(response.Body.Bytes(), &readiness); err != nil {
t.Fatal(err)
}
if readiness != api.hv.backupReadiness {
t.Fatalf("backup readiness=%#v want=%#v",
readiness, api.hv.backupReadiness)
}
}
func TestBackupReadinessRequiresManageCapability(t *testing.T) {
api := newTestAPI(t)
const uuid = "123e4567-e89b-42d3-a456-426614174000"
response := api.request(t, http.MethodGet,
"/v1/vms/"+uuid+"/backup-readiness", nil,
auth.Actor{UserID: 1})
if response.Code != http.StatusForbidden {
t.Fatalf("backup readiness without manage=%d body=%s",
response.Code, response.Body.String())
}
}
func requireOperationResponseIdentity(t *testing.T, response *httptest.ResponseRecorder,
operationID, action, resourceID, requestFingerprint string) operationResponse {
t.Helper()

@ -25,6 +25,34 @@ func (l *Libvirt) CreateBackup(ctx context.Context, uuid string, request BackupR
return l.createPortableBackup(ctx, uuid, request)
}
// GetBackupReadiness reports only transient blockers which automatic backup
// may safely defer. It deliberately does not reserve resources or consume
// retained job evidence, and CreateBackup repeats these checks before mutation.
func (l *Libvirt) GetBackupReadiness(ctx context.Context, uuid string) (BackupReadiness, error) {
domain, err := l.domainByUUID(ctx, uuid)
if err != nil {
return BackupReadiness{}, err
}
defer domain.Free()
_, metadata, err := requireManagedDomain(domain)
if err != nil {
return BackupReadiness{}, err
}
if reason := backupTransientBlocker(metadata); reason != "" {
return BackupReadiness{Eligible: false, Retryable: true, Reason: reason}, nil
}
if err := ensureNoActiveDomainJobIfRunning(domain); err != nil {
var public interface{ PublicCode() string }
if errors.As(err, &public) && public.PublicCode() == "domain_job_active" {
return BackupReadiness{
Eligible: false, Retryable: true, Reason: "domain_job_active",
}, nil
}
return BackupReadiness{}, err
}
return BackupReadiness{Eligible: true, Retryable: false}, nil
}
func (l *Libvirt) createPortableBackup(ctx context.Context, uuid string, request BackupRequest) (_ BackupResult, resultErr error) {
client := objecttransfer.New()
defer client.CloseIdleConnections()
@ -275,10 +303,7 @@ func (l *Libvirt) validateBackupSource(ctx context.Context, uuid, backupKey stri
}
defer pool.Free()
defer volume.Free()
if metadata.RescueTemplateID != "" {
return false, PortableRestoreContract{}, NewError(ErrConflict, "backup_rescue_active", "VM backup is unavailable while rescue media is attached", nil)
}
if err := validateBackupTransitionState(metadata); err != nil {
if err := validateBackupTransientState(metadata); err != nil {
return false, PortableRestoreContract{}, err
}
for _, stored := range metadata.Snapshots {
@ -404,17 +429,34 @@ func portableQ35Machine(machine string) bool {
return machine == "q35" || strings.HasPrefix(machine, "pc-q35-")
}
func validateBackupTransitionState(metadata *domainMetadataXML) error {
func backupTransientBlocker(metadata *domainMetadataXML) string {
if metadata != nil && metadata.RescueTemplateID != "" {
return "backup_rescue_active"
}
// Reinstall and snapshot restore deliberately retain their transition kind
// and operation ID after the old root has been deleted. Those markers prove
// a completed root switch during reconciliation; only a pending old root
// means that the disk transition is still active.
if metadata != nil && metadata.PendingCleanupVolume != "" {
return "backup_disk_transition_active"
}
return ""
}
func validateBackupTransientState(metadata *domainMetadataXML) error {
switch backupTransientBlocker(metadata) {
case "backup_rescue_active":
return NewError(ErrConflict, "backup_rescue_active", "VM backup is unavailable while rescue media is attached", nil)
case "backup_disk_transition_active":
return NewError(ErrConflict, "backup_disk_transition_active", "VM backup is unavailable during a disk transition", nil)
}
return nil
}
func validateBackupTransitionState(metadata *domainMetadataXML) error {
return validateBackupTransientState(metadata)
}
func validateSingleWritableRoot(definition *libvirtxml.Domain) error {
if definition == nil || definition.Devices == nil {
return NewError(ErrConflict, "backup_disk_layout_unsupported", "VM disk layout is unavailable for portable backup", nil)

@ -13,6 +13,32 @@ import (
"libvirt.org/go/libvirtxml"
)
func TestBackupTransientBlockerUsesOneAuthoritativeMapping(t *testing.T) {
tests := []struct {
name string
metadata *domainMetadataXML
reason string
}{
{name: "ready", metadata: &domainMetadataXML{}},
{name: "rescue", metadata: &domainMetadataXML{RescueTemplateID: "rescue-image"}, reason: "backup_rescue_active"},
{name: "cleanup", metadata: &domainMetadataXML{PendingCleanupVolume: "root-old.qcow2"}, reason: "backup_disk_transition_active"},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
if got := backupTransientBlocker(test.metadata); got != test.reason {
t.Fatalf("blocker=%q want=%q", got, test.reason)
}
err := validateBackupTransientState(test.metadata)
if test.reason == "" && err != nil {
t.Fatalf("ready state rejected: %v", err)
}
if test.reason != "" && errorPublicCode(err) != test.reason {
t.Fatalf("validation code=%q want=%q", errorPublicCode(err), test.reason)
}
})
}
}
func portableRestoreDomainFixture(t *testing.T) (*Libvirt, *libvirtxml.Domain, *domainMetadataXML) {
t.Helper()
definition := validDomainDefinition()

@ -624,6 +624,12 @@ func (m *managedLibvirt) GetVMMetadata(ctx context.Context, uuid string) (VMMeta
return managedCall(m, ctx, false, func(h Hypervisor) (VMMetadata, error) { return h.GetVMMetadata(ctx, uuid) })
}
func (m *managedLibvirt) GetBackupReadiness(ctx context.Context, uuid string) (BackupReadiness, error) {
return managedCall(m, ctx, false, func(h Hypervisor) (BackupReadiness, error) {
return h.GetBackupReadiness(ctx, uuid)
})
}
func (m *managedLibvirt) CreateVM(ctx context.Context, request CreateVMRequest) (VMMetadata, error) {
return managedCall(m, ctx, true, func(h Hypervisor) (VMMetadata, error) { return h.CreateVM(ctx, request) })
}

@ -192,6 +192,15 @@ type VMState struct {
EffectConfirmed bool `json:"effect_confirmed,omitempty"`
}
// BackupReadiness is bounded, read-only evidence that a VM may enter the
// portable-backup workflow. It is advisory: CreateBackup must re-check the
// same transient blockers immediately before any mutation.
type BackupReadiness struct {
Eligible bool `json:"eligible"`
Retryable bool `json:"retryable"`
Reason string `json:"reason,omitempty"`
}
type Disk struct {
// Path is agent-local implementation data. It must never cross the API or
// be persisted in an operation result.
@ -977,6 +986,7 @@ type Hypervisor interface {
ListVMs(context.Context) ([]VMMetadata, error)
GetVMState(context.Context, string) (VMState, error)
GetVMMetadata(context.Context, string) (VMMetadata, error)
GetBackupReadiness(context.Context, string) (BackupReadiness, error)
CreateVM(context.Context, CreateVMRequest) (VMMetadata, error)
CreateBackup(context.Context, string, BackupRequest) (BackupResult, error)
CleanupBackupWorkspace(context.Context, string, CleanupBackupWorkspaceRequest) (CleanupBackupWorkspaceResult, error)
@ -1060,6 +1070,9 @@ func (Unsupported) GetVMState(context.Context, string) (VMState, error) {
func (Unsupported) GetVMMetadata(context.Context, string) (VMMetadata, error) {
return VMMetadata{}, unsupported("VM metadata")
}
func (Unsupported) GetBackupReadiness(context.Context, string) (BackupReadiness, error) {
return BackupReadiness{}, unsupported("VM backup readiness")
}
func (Unsupported) CreateVM(context.Context, CreateVMRequest) (VMMetadata, error) {
return VMMetadata{}, unsupported("VM create")
}

Loading…
Cancel
Save