diff --git a/agent/internal/seedmedia/resolver.go b/agent/internal/seedmedia/resolver.go new file mode 100644 index 00000000..10c058fe --- /dev/null +++ b/agent/internal/seedmedia/resolver.go @@ -0,0 +1,402 @@ +// Package seedmedia defines the first, read-only boundary for a future +// host-side NoCloud media executor. +// +// The current agent publishes an immutable NoCloud seed as a private +// directory. That directory is not an attachable CIDATA device by itself. +// This package therefore resolves and verifies only the artifact identity and +// returns a deliberately non-attachable plan. It does not create an ISO, +// open a libvirt connection, define a domain, change power, configure a +// network, or delete anything. A later CIDATA builder can consume this +// boundary after it has its own atomic publication and read-back contract. +package seedmedia + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" + "strings" + + "g.luoli.live/root/virt/agent/internal/domaincreateplan" + "g.luoli.live/root/virt/agent/internal/hypervisor" + "g.luoli.live/root/virt/agent/internal/startup" +) + +const ( + codePrefix = "seed_media_" + + // MediaKindNoCloudDirectory identifies the current artifact form. It is + // intentionally not "cidata": a directory has not yet crossed the media + // builder boundary and must not be passed to a libvirt disk source. + MediaKindNoCloudDirectory = "nocloud-directory" + + // StateVerifiedDirectory is the only successful state this package can + // return. It proves immutable seed content, not an attachable device. + StateVerifiedDirectory = "verified-directory" + + // CommitBoundaryVerified is a read-only checkpoint for an operation + // journal. It is not a create/attach success marker. + CommitBoundaryVerified = "seed_media_verified" +) + +var ( + // ErrInvalidRequest is returned for malformed identities or expectations. + // No host mutation is attempted, so it is definitive. + ErrInvalidRequest = errors.New("invalid seed media request") + // ErrArtifactRejected means the immutable artifact is missing, malformed, + // or does not match the expected journal identity. The caller must not + // retry the same artifact identity as if it were a transient transport + // failure. + ErrArtifactRejected = errors.New("seed artifact rejected") + // ErrUnavailable means the configured artifact storage could not be read. + // Reconciliation may retry after host repair; the result remains uncertain. + ErrUnavailable = errors.New("seed artifact storage unavailable") + // ErrCanceled means the caller canceled the read-only verification. It is + // non-definitive even though this package does not perform a mutation. + ErrCanceled = errors.New("seed media resolution canceled") +) + +// Error is the stable, non-sensitive error projection used by a future +// operation adapter. Message never contains a host path, raw seed bytes, or +// tenant-provided script text; Cause is retained only for local diagnostics. +type Error struct { + CodeValue string `json:"code"` + Message string `json:"message"` + Definitive bool `json:"definitive"` + Cause error `json:"-"` +} + +func (e *Error) Error() string { + if e == nil { + return codePrefix + "failed" + } + if e.Message == "" { + return e.CodeValue + } + return e.CodeValue + ": " + e.Message +} + +func (e *Error) Unwrap() error { + if e == nil { + return nil + } + return e.Cause +} + +func newError(code, message string, definitive bool, cause error) error { + return &Error{CodeValue: code, Message: message, Definitive: definitive, Cause: cause} +} + +// Code returns the stable error code intended for an operation journal. +func Code(err error) string { + var typed *Error + if errors.As(err, &typed) && typed != nil && typed.CodeValue != "" { + return typed.CodeValue + } + return codePrefix + "failed" +} + +// IsDefinitive reports whether the resolver proved that the request/artifact +// is rejected. Filesystem availability and cancellation are not definitive. +func IsDefinitive(err error) bool { + var typed *Error + return errors.As(err, &typed) && typed != nil && typed.Definitive +} + +// Request is the typed identity expected from the create journal. It carries +// digest metadata only; it never accepts a caller-selected host path, ISO +// filename, command, or raw seed bytes. +type Request struct { + ArtifactID string `json:"artifact_id"` + SeedManifest domaincreateplan.SeedManifest `json:"seed_manifest"` + StartupScriptPresent bool `json:"first_boot_present"` + StartupScriptSHA256 string `json:"first_boot_digest"` +} + +// SeedMediaResolver is intentionally a one-method consumer-side interface. +// Implementations may verify a local directory or a future agent-owned +// artifact store, but callers cannot ask it to define, attach, start, delete, +// or configure a VM. +type SeedMediaResolver interface { + Resolve(context.Context, Request) (Plan, error) +} + +// SeedArtifactVerifier is the narrow read-only seam used by Resolver. The +// artifact ID, rather than a path, is the only lookup key exposed at this +// boundary. Tests can provide a fake without invoking a filesystem or an +// external process. +type SeedArtifactVerifier interface { + Verify(context.Context, string) (startup.SeedVerificationDetails, error) +} + +// Resolver verifies an immutable artifact through a supplied verifier. It +// has no host path and can be used with a fake in unit tests. +type Resolver struct { + verifier SeedArtifactVerifier +} + +var _ SeedMediaResolver = (*Resolver)(nil) + +// New constructs a resolver over a read-only artifact verifier. The verifier +// is injected so this package remains independent of libvirt, shell commands, +// networking, and destructive storage operations. +func New(verifier SeedArtifactVerifier) (*Resolver, error) { + if verifier == nil { + return nil, fmt.Errorf("%w: artifact verifier is nil", ErrInvalidRequest) + } + return &Resolver{verifier: verifier}, nil +} + +// DirectoryResolver is a resolver backed by the agent-owned startup seed +// directory. Its root is private and never appears in Plan or Error.Message. +type DirectoryResolver struct { + *Resolver +} + +var _ SeedMediaResolver = (*DirectoryResolver)(nil) + +// NewDirectoryResolver binds the resolver to an agent-configured absolute +// root. It validates only the configuration shape here; existence, mode, and +// symlink checks are performed on every read by startup.VerifySeedDirectoryDetails. +func NewDirectoryResolver(root string) (*DirectoryResolver, error) { + clean, err := validateRoot(root) + if err != nil { + return nil, err + } + resolver, err := New(directoryVerifier{root: clean}) + if err != nil { + return nil, err + } + return &DirectoryResolver{Resolver: resolver}, nil +} + +// Plan is the only successful result currently available. MediaReady and +// Attachable are deliberately false: the current artifact is a verified +// directory, not a CIDATA ISO or another libvirt disk source. The plan is +// safe to journal or log because it contains no host path or seed content. +type Plan struct { + CommitBoundary string `json:"commit_boundary"` + ArtifactID string `json:"artifact_id"` + SeedManifest domaincreateplan.SeedManifest `json:"seed_manifest"` + StartupScriptPresent bool `json:"first_boot_present"` + StartupScriptSHA256 string `json:"first_boot_digest"` + MediaKind string `json:"media_kind"` + State string `json:"state"` + MediaReady bool `json:"media_ready"` + Attachable bool `json:"attachable"` + IdentitySHA256 string `json:"identity_sha256"` +} + +// Resolve performs identity validation and a read-only artifact verification. +// It never creates a media file or calls an executor. The returned plan must +// not be interpreted as permission to attach a directory to libvirt. +func (r *Resolver) Resolve(ctx context.Context, request Request) (Plan, error) { + if ctx == nil { + ctx = context.Background() + } + if err := ctx.Err(); err != nil { + return Plan{}, canceledError(err) + } + if r == nil || r.verifier == nil { + return Plan{}, newError(codePrefix+"invalid_resolver", "seed artifact verifier is unavailable", true, ErrInvalidRequest) + } + + artifactID, err := canonicalArtifactID(request.ArtifactID) + if err != nil { + return Plan{}, newError(codePrefix+"invalid_artifact_id", "seed artifact identity is invalid", true, fmt.Errorf("%w: %v", ErrInvalidRequest, err)) + } + if err := validateExpected(request); err != nil { + return Plan{}, newError(codePrefix+"invalid_expectation", "seed artifact expectation is invalid", true, fmt.Errorf("%w: %v", ErrInvalidRequest, err)) + } + + observed, err := r.verifier.Verify(ctx, artifactID) + if err != nil { + return Plan{}, classifyVerificationError(ctx, err) + } + if err := ctx.Err(); err != nil { + return Plan{}, canceledError(err) + } + observedManifest, err := projectManifest(observed.Manifest) + if err != nil { + return Plan{}, newError(codePrefix+"artifact_rejected", "seed artifact metadata is invalid", true, fmt.Errorf("%w: %v", ErrArtifactRejected, err)) + } + if observedManifest != request.SeedManifest || + observed.StartupScriptIncluded != request.StartupScriptPresent || + observed.StartupScriptSHA256 != request.StartupScriptSHA256 { + return Plan{}, newError(codePrefix+"identity_mismatch", "seed artifact does not match the expected identity", true, ErrArtifactRejected) + } + + identity := identityDigest(identityInput{ + ArtifactID: artifactID, + Manifest: request.SeedManifest, + ScriptPresent: request.StartupScriptPresent, + ScriptSHA256: request.StartupScriptSHA256, + }) + return Plan{ + CommitBoundary: CommitBoundaryVerified, + ArtifactID: artifactID, + SeedManifest: request.SeedManifest, + StartupScriptPresent: request.StartupScriptPresent, + StartupScriptSHA256: request.StartupScriptSHA256, + MediaKind: MediaKindNoCloudDirectory, + State: StateVerifiedDirectory, + MediaReady: false, + Attachable: false, + IdentitySHA256: identity, + }, nil +} + +type directoryVerifier struct { + root string +} + +var _ SeedArtifactVerifier = directoryVerifier{} + +func (v directoryVerifier) Verify(ctx context.Context, artifactID string) (startup.SeedVerificationDetails, error) { + if ctx == nil { + ctx = context.Background() + } + if err := ctx.Err(); err != nil { + return startup.SeedVerificationDetails{}, err + } + canonical, err := canonicalArtifactID(artifactID) + if err != nil { + return startup.SeedVerificationDetails{}, err + } + target := filepath.Join(v.root, canonical) + if filepath.Dir(target) != v.root || filepath.Base(target) != canonical { + return startup.SeedVerificationDetails{}, fmt.Errorf("%w: artifact identity escaped configured root", startup.ErrArtifactPath) + } + details, err := startup.VerifySeedDirectoryDetails(target) + if err != nil { + return startup.SeedVerificationDetails{}, err + } + if err := ctx.Err(); err != nil { + return startup.SeedVerificationDetails{}, err + } + return details, nil +} + +func canonicalArtifactID(value string) (string, error) { + canonical, err := hypervisor.CanonicalUUID(value) + if err != nil { + return "", err + } + if canonical != value { + return "", fmt.Errorf("%w: UUID must already be canonical", hypervisor.ErrInvalidUUID) + } + return canonical, nil +} + +func validateRoot(root string) (string, error) { + if root == "" || strings.TrimSpace(root) != root || strings.IndexByte(root, 0) >= 0 { + return "", fmt.Errorf("%w: artifact root is invalid", ErrInvalidRequest) + } + clean := filepath.Clean(root) + if !filepath.IsAbs(root) || clean != root || clean == string(filepath.Separator) { + return "", fmt.Errorf("%w: artifact root is invalid", ErrInvalidRequest) + } + return clean, nil +} + +func validateExpected(request Request) error { + manifest := request.SeedManifest + if manifest.Version != startup.SeedManifestVersion { + return fmt.Errorf("unsupported seed manifest version") + } + if !validDigest(manifest.User) || !validDigest(manifest.Meta) || !validDigest(manifest.Network) { + return fmt.Errorf("seed manifest digest is invalid") + } + if !validScriptDigest(request.StartupScriptSHA256) { + return fmt.Errorf("startup-script digest is invalid") + } + emptyDigest := digestBytes(nil) + if request.StartupScriptPresent == (request.StartupScriptSHA256 == emptyDigest) { + return fmt.Errorf("startup-script presence and digest disagree") + } + return nil +} + +func validDigest(value domaincreateplan.FileDigest) bool { + if value.Bytes < 0 || value.Bytes > startup.MaxFileBytes || len(value.SHA256) != sha256.Size*2 { + return false + } + decoded, err := hex.DecodeString(value.SHA256) + return err == nil && len(decoded) == sha256.Size && strings.ToLower(value.SHA256) == value.SHA256 +} + +func validScriptDigest(value string) bool { + if len(value) != sha256.Size*2 || strings.ToLower(value) != value { + return false + } + _, err := hex.DecodeString(value) + return err == nil +} + +func projectManifest(manifest startup.SeedManifest) (domaincreateplan.SeedManifest, error) { + if manifest.Version != startup.SeedManifestVersion || len(manifest.Files) != 3 { + return domaincreateplan.SeedManifest{}, fmt.Errorf("manifest shape is invalid") + } + user, userOK := manifest.Files[startup.UserDataFilename] + meta, metaOK := manifest.Files[startup.MetaDataFilename] + network, networkOK := manifest.Files[startup.NetworkConfigFilename] + if !userOK || !metaOK || !networkOK { + return domaincreateplan.SeedManifest{}, fmt.Errorf("manifest is missing a fixed NoCloud file") + } + for _, digest := range []startup.SeedFileDigest{user, meta, network} { + if digest.Bytes < 0 || digest.Bytes > startup.MaxFileBytes || len(digest.SHA256) != sha256.Size*2 || strings.ToLower(digest.SHA256) != digest.SHA256 { + return domaincreateplan.SeedManifest{}, fmt.Errorf("manifest digest is invalid") + } + if _, err := hex.DecodeString(digest.SHA256); err != nil { + return domaincreateplan.SeedManifest{}, fmt.Errorf("manifest digest is invalid") + } + } + return domaincreateplan.SeedManifest{ + Version: manifest.Version, + User: domaincreateplan.FileDigest{Bytes: user.Bytes, SHA256: user.SHA256}, + Meta: domaincreateplan.FileDigest{Bytes: meta.Bytes, SHA256: meta.SHA256}, + Network: domaincreateplan.FileDigest{Bytes: network.Bytes, SHA256: network.SHA256}, + }, nil +} + +func classifyVerificationError(ctx context.Context, err error) error { + if canceled := ctx.Err(); canceled != nil { + return canceledError(canceled) + } + if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) { + return canceledError(err) + } + if errors.Is(err, startup.ErrInvalidArtifact) { + return newError(codePrefix+"artifact_rejected", "seed artifact is missing or does not verify", true, fmt.Errorf("%w: %v", ErrArtifactRejected, err)) + } + if errors.Is(err, startup.ErrArtifactPath) || errors.Is(err, fs.ErrPermission) || os.IsPermission(err) { + return newError(codePrefix+"artifact_unavailable", "seed artifact storage is unavailable", false, fmt.Errorf("%w: %v", ErrUnavailable, err)) + } + return newError(codePrefix+"transport_unavailable", "seed artifact read did not complete", false, fmt.Errorf("%w: %v", ErrUnavailable, err)) +} + +func canceledError(cause error) error { + return newError(codePrefix+"canceled", "seed media resolution was canceled", false, fmt.Errorf("%w: %v", ErrCanceled, cause)) +} + +type identityInput struct { + ArtifactID string `json:"artifact_id"` + Manifest domaincreateplan.SeedManifest `json:"seed_manifest"` + ScriptPresent bool `json:"first_boot_present"` + ScriptSHA256 string `json:"first_boot_digest"` +} + +func identityDigest(value identityInput) string { + encoded, _ := json.Marshal(value) + return digestBytes(encoded) +} + +func digestBytes(value []byte) string { + sum := sha256.Sum256(value) + return hex.EncodeToString(sum[:]) +} diff --git a/agent/internal/seedmedia/resolver_test.go b/agent/internal/seedmedia/resolver_test.go new file mode 100644 index 00000000..425fcc60 --- /dev/null +++ b/agent/internal/seedmedia/resolver_test.go @@ -0,0 +1,221 @@ +package seedmedia + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + "os" + "path/filepath" + "strings" + "testing" + + "g.luoli.live/root/virt/agent/internal/domaincreateplan" + "g.luoli.live/root/virt/agent/internal/startup" +) + +const ( + resolverArtifactID = "00000000-0000-4000-8000-000000002101" + resolverInstanceID = "instance-seedmedia-1" +) + +type fakeVerifier struct { + details startup.SeedVerificationDetails + err error + seen []string +} + +func (f *fakeVerifier) Verify(ctx context.Context, artifactID string) (startup.SeedVerificationDetails, error) { + f.seen = append(f.seen, artifactID) + if err := ctx.Err(); err != nil { + return startup.SeedVerificationDetails{}, err + } + if f.err != nil { + return startup.SeedVerificationDetails{}, f.err + } + return f.details, nil +} + +func validResolverFixture(t *testing.T) (Request, startup.SeedVerificationDetails) { + t.Helper() + files, err := startup.BuildCreateSeed( + resolverInstanceID, + "vm-seedmedia-1", + `{"version":2,"ethernets":{}}`, + "#!/bin/sh\necho first boot\n", + ) + if err != nil { + t.Fatal(err) + } + manifest := manifestFromSeedFiles(files) + return Request{ + ArtifactID: resolverArtifactID, + SeedManifest: manifest, + StartupScriptPresent: true, + StartupScriptSHA256: digestString([]byte("#!/bin/sh\necho first boot\n")), + }, startup.SeedVerificationDetails{ + Manifest: startupManifest(manifest), + StartupScriptIncluded: true, + StartupScriptSHA256: digestString([]byte("#!/bin/sh\necho first boot\n")), + } +} + +func manifestFromSeedFiles(files startup.SeedFiles) domaincreateplan.SeedManifest { + digest := func(data []byte) domaincreateplan.FileDigest { + return domaincreateplan.FileDigest{Bytes: len(data), SHA256: digestString(data)} + } + return domaincreateplan.SeedManifest{ + Version: startup.SeedManifestVersion, + User: digest(files.UserData), + Meta: digest(files.MetaData), + Network: digest(files.NetworkConfig), + } +} + +func startupManifest(manifest domaincreateplan.SeedManifest) startup.SeedManifest { + return startup.SeedManifest{ + Version: manifest.Version, + Files: map[string]startup.SeedFileDigest{ + startup.UserDataFilename: {Bytes: manifest.User.Bytes, SHA256: manifest.User.SHA256}, + startup.MetaDataFilename: {Bytes: manifest.Meta.Bytes, SHA256: manifest.Meta.SHA256}, + startup.NetworkConfigFilename: {Bytes: manifest.Network.Bytes, SHA256: manifest.Network.SHA256}, + }, + } +} + +func digestString(data []byte) string { + sum := sha256.Sum256(data) + return hex.EncodeToString(sum[:]) +} + +func TestResolverVerifiesIdentityWithoutAttachPermission(t *testing.T) { + request, details := validResolverFixture(t) + fake := &fakeVerifier{details: details} + resolver, err := New(fake) + if err != nil { + t.Fatal(err) + } + plan, err := resolver.Resolve(context.Background(), request) + if err != nil { + t.Fatalf("Resolve() error = %v", err) + } + if fake.seen[0] != resolverArtifactID { + t.Fatalf("verifier artifact ID = %q", fake.seen[0]) + } + if plan.CommitBoundary != CommitBoundaryVerified || plan.MediaKind != MediaKindNoCloudDirectory || + plan.State != StateVerifiedDirectory || plan.MediaReady || plan.Attachable { + t.Fatalf("unexpected non-attachable plan: %+v", plan) + } + if plan.ArtifactID != resolverArtifactID || len(plan.IdentitySHA256) != sha256.Size*2 { + t.Fatalf("plan identity = %+v", plan) + } + encoded, err := json.Marshal(plan) + if err != nil { + t.Fatal(err) + } + for _, forbidden := range []string{"first boot", "/var/lib", "seedmedia"} { + if strings.Contains(string(encoded), forbidden) { + t.Fatalf("plan JSON leaked %q: %s", forbidden, encoded) + } + } +} + +func TestResolverRejectsIdentityMismatchDefinitively(t *testing.T) { + request, details := validResolverFixture(t) + request.StartupScriptSHA256 = digestString([]byte("different")) + resolver, err := New(&fakeVerifier{details: details}) + if err != nil { + t.Fatal(err) + } + _, err = resolver.Resolve(context.Background(), request) + if err == nil || Code(err) != codePrefix+"identity_mismatch" || !IsDefinitive(err) || + !errors.Is(err, ErrArtifactRejected) { + t.Fatalf("mismatch error = %v code=%q definitive=%v", err, Code(err), IsDefinitive(err)) + } +} + +func TestResolverClassifiesUnavailableAndCanceled(t *testing.T) { + request, details := validResolverFixture(t) + resolver, err := New(&fakeVerifier{details: details, err: fmt.Errorf("%w: unavailable", startup.ErrArtifactPath)}) + if err != nil { + t.Fatal(err) + } + _, err = resolver.Resolve(context.Background(), request) + if err == nil || Code(err) != codePrefix+"artifact_unavailable" || IsDefinitive(err) { + t.Fatalf("unavailable error = %v code=%q definitive=%v", err, Code(err), IsDefinitive(err)) + } + canceled, cancel := context.WithCancel(context.Background()) + cancel() + _, err = resolver.Resolve(canceled, request) + if err == nil || Code(err) != codePrefix+"canceled" || IsDefinitive(err) || !errors.Is(err, ErrCanceled) { + t.Fatalf("canceled error = %v code=%q definitive=%v", err, Code(err), IsDefinitive(err)) + } +} + +func TestDirectoryResolverReadsOnlyPublishedSeed(t *testing.T) { + root := t.TempDir() + files, err := startup.BuildCreateSeed( + resolverInstanceID, + "vm-seedmedia-1", + `{"version":2,"ethernets":{}}`, + "#!/bin/sh\necho first boot\n", + ) + if err != nil { + t.Fatal(err) + } + target := filepath.Join(root, resolverArtifactID) + _, err = startup.WriteSeedDirectory(target, files) + if err != nil { + t.Fatal(err) + } + request := Request{ + ArtifactID: resolverArtifactID, + SeedManifest: manifestFromSeedFiles(files), + StartupScriptPresent: true, + StartupScriptSHA256: artifactScriptDigest(files), + } + resolver, err := NewDirectoryResolver(root) + if err != nil { + t.Fatal(err) + } + plan, err := resolver.Resolve(context.Background(), request) + if err != nil { + t.Fatalf("DirectoryResolver.Resolve() error = %v", err) + } + if plan.ArtifactID != resolverArtifactID || plan.MediaReady || plan.Attachable { + t.Fatalf("directory plan crossed attach boundary: %+v", plan) + } +} + +func artifactScriptDigest(files startup.SeedFiles) string { + return digestString([]byte("#!/bin/sh\necho first boot\n")) +} + +func TestNewDirectoryResolverRejectsUnsafeRoot(t *testing.T) { + for _, root := range []string{"", "relative", "/", " /tmp/agent"} { + if _, err := NewDirectoryResolver(root); err == nil { + t.Fatalf("NewDirectoryResolver accepted unsafe root %q", root) + } + } +} + +func TestResolverDoesNotExposeDirectoryFromPlan(t *testing.T) { + root := filepath.Join(t.TempDir(), "agent-artifacts") + if err := os.Mkdir(root, 0o700); err != nil { + t.Fatal(err) + } + request, details := validResolverFixture(t) + resolver, err := New(&fakeVerifier{details: details}) + if err != nil { + t.Fatal(err) + } + plan, err := resolver.Resolve(context.Background(), request) + if err != nil { + t.Fatal(err) + } + if strings.Contains(fmt.Sprintf("%v", plan), root) { + t.Fatalf("plan unexpectedly contains an artifact root: %v", plan) + } +} diff --git a/docs/GO_AGENT_API_V1.md b/docs/GO_AGENT_API_V1.md index 15208016..0462438a 100644 --- a/docs/GO_AGENT_API_V1.md +++ b/docs/GO_AGENT_API_V1.md @@ -195,7 +195,8 @@ journal,并可在 readiness 仍降级时通过同一 operation ID 的 reconcil 为 LF,只在 create 时封存到 `CIDATA` NoCloud seed;脚本在 guest 内用原子 `started` marker 防止失败或中断后的自动重跑。 -宿主机侧 seed artifact 先以目录形式落盘,再由后续受控存储层决定是否制作 +宿主机侧 seed artifact 先以目录形式落盘;`internal/seedmedia` 目前只做 +immutable 身份核验并明确返回“不可 attach”的目录状态,再由后续受控存储层决定是否制作 CIDATA ISO。Go Agent 不调用 `mkisofs`/`genisoimage`,也不把请求中的文件名 拼入 shell/argv;`agent/internal/startup.WriteSeedDirectory` 只写固定的 `user-data`、`meta-data`、`network-config` 和 `manifest.json`。目录权限为 diff --git a/docs/GO_AGENT_OPERATION_MATRIX.md b/docs/GO_AGENT_OPERATION_MATRIX.md index 4766a1a7..31013cec 100644 --- a/docs/GO_AGENT_OPERATION_MATRIX.md +++ b/docs/GO_AGENT_OPERATION_MATRIX.md @@ -14,6 +14,7 @@ | 原始域 XML 定义(`domain_define`) | 已禁用 | HTTP 白名单已移除;待 typed executor 提供 ownership marker、卷/seed identity、原子 inactive define、精确 read-back 和 fenced cleanup 后再设计新 operation | | 电源 start/shutdown/destroy/reboot/suspend/resume | 已实现首版 | 固定 argv、动作后状态回读;未知结果只读 reconcile,reboot 不以 running 单态确认 | | NoCloud seed 与云镜像首次启动脚本 | 已实现 artifact 首版 | 目录 manifest/hash、CIDATA 消费链、guest 一次性 marker 验收 | +| Seed media identity resolver(内部) | 已实现只读首版 | 只按 artifact UUID 校验 immutable 目录、manifest 和一次性脚本摘要;结果明确标记为 `nocloud-directory`/不可 attach,不生成 ISO、不调用 libvirt、不改盘或网络 | | 完整 VM 创建/磁盘/镜像绑定 | 未实现(define 已有 file-backed 路径 allowlist gate) | 存储池/卷 CAS、磁盘 owner、定义与清理证据;`VIRT_CLOUD_AGENT_STORAGE_ROOTS` 的全祖先 owner/TOCTOU 验收 | | 重装、救援、退出救援 | 未实现 | pre/post commit boundary、旧卷/新卷清理清单、QGA/电源回读 | | 快照创建/恢复/删除 | 未实现 | libvirt job 状态、卷身份、冻结/解冻和取消后的恢复证据 |