Documentation
¶
Overview ¶
Package microvmmanager owns idempotent readiness and explicit diagnostics for the user-local microvmd lifecycle. It supplies safe paths and process operations without weakening microvmd's absolute-path or operator-policy validation.
Index ¶
- Constants
- Variables
- func GuestEgressSummary(selection GuestEgressSelection) string
- func ReportReadinessStage(ctx context.Context, stage ReadinessStage)
- func ValidateDeleteRequest(request DeleteRequest) error
- func WithReadinessObserver(ctx context.Context, observer ReadinessObserver) context.Context
- type Artifact
- type DaemonInfo
- type DefaultOperations
- func (*DefaultOperations) DaemonInfo(ctx context.Context, paths Paths) (DaemonInfo, error)
- func (o *DefaultOperations) Doctor(ctx context.Context, paths Paths) (string, error)
- func (o *DefaultOperations) Download(ctx context.Context, release Release, root, destination string) (string, error)
- func (o *DefaultOperations) Install(ctx context.Context, manifest, root, installRoot string) (InstalledArtifacts, error)
- func (o *DefaultOperations) Preflight(ctx context.Context, _ Paths) error
- func (*DefaultOperations) Running(ctx context.Context, paths Paths) (bool, error)
- func (*DefaultOperations) Start(_ context.Context, paths Paths) error
- func (*DefaultOperations) Stop(ctx context.Context, paths Paths) error
- func (*DefaultOperations) Verify(_ context.Context, release Release, manifest string) error
- func (*DefaultOperations) WaitSocket(ctx context.Context, socket string) error
- type DeleteRequest
- type DeleteResult
- type EgressRule
- type Generation
- type GuestEgressSelection
- type HostPaths
- type InstalledArtifacts
- type Manager
- func (m *Manager) Delete(ctx context.Context, request DeleteRequest) (DeleteResult, error)
- func (m *Manager) Doctor(ctx context.Context) (string, error)
- func (m *Manager) EnsureReady(ctx context.Context, request ReadyRequest) (string, error)
- func (*Manager) HostFallbackEnabled() bool
- func (m *Manager) Status(ctx context.Context, requests ...StatusRequest) (Status, error)
- type Operations
- type Paths
- type Policy
- type ReadinessError
- type ReadinessFailure
- type ReadinessObserver
- type ReadinessStage
- type ReadyRequest
- type Release
- type ReleaseDefaults
- type Status
- type StatusRequest
Constants ¶
const ( // GuestEgressPermissive allows unrestricted guest IPv4 egress. GuestEgressPermissive = "permissive" // GuestEgressDenyAll blocks all guest network destinations. GuestEgressDenyAll = "deny-all" // GuestEgressAllowlist permits only explicitly selected destinations. GuestEgressAllowlist = "allowlist" )
const ( // Alias is the built-in local profile selected through ordinary configuration. Alias = "microvm-local" // DarwinSocketPathLimit is kept below Darwin's sockaddr_un.sun_path bound. DarwinSocketPathLimit = 104 )
Variables ¶
var ( // ErrUnsupportedPlatform marks a host on which microvm-local cannot run. ErrUnsupportedPlatform = errors.New("unsupported microVM platform") ErrKVMUnavailable = errors.New("KVM unavailable") )
Functions ¶
func GuestEgressSummary ¶
func GuestEgressSummary(selection GuestEgressSelection) string
GuestEgressSummary returns the safe operator-facing configured policy summary.
func ReportReadinessStage ¶
func ReportReadinessStage(ctx context.Context, stage ReadinessStage)
ReportReadinessStage reports one stage to an observer carried by ctx. It is exported so command-root test doubles can preserve the observer contract.
func ValidateDeleteRequest ¶
func ValidateDeleteRequest(request DeleteRequest) error
ValidateDeleteRequest checks the complete generation selector before any destructive confirmation is shown.
func WithReadinessObserver ¶
func WithReadinessObserver(ctx context.Context, observer ReadinessObserver) context.Context
WithReadinessObserver returns a context that observes EnsureReady stages.
Types ¶
type Artifact ¶
type Artifact struct {
Kind string `json:"kind"`
Reference string `json:"reference"`
Digest string `json:"digest"`
ManifestDigest string `json:"manifest_digest,omitempty"`
DiscoveryReference string `json:"discovery_reference,omitempty"`
ResolutionEvidence string `json:"resolution_evidence,omitempty"`
Platform string `json:"platform,omitempty"`
Path string `json:"path"`
Provenance string `json:"provenance"`
SigstoreBundle string `json:"sigstore_bundle"`
}
Artifact is one installer-projected verified admission artifact.
type DaemonInfo ¶
type DaemonInfo = microvmclient.DaemonInfo
DaemonInfo is the authenticated serving-daemon identity used for exact reuse.
type DefaultOperations ¶
type DefaultOperations struct {
HTTPClient *http.Client
GOOS, GOARCH string
// contains filtered or unexported fields
}
DefaultOperations implements the real local OS, release, installer, and daemon boundary.
func (*DefaultOperations) DaemonInfo ¶
func (*DefaultOperations) DaemonInfo(ctx context.Context, paths Paths) (DaemonInfo, error)
DaemonInfo queries the process serving the owner-only socket.
func (*DefaultOperations) Doctor ¶
Doctor verifies the identity of the daemon actually serving the configured socket and returns its structured, line-oriented readiness report.
func (*DefaultOperations) Download ¶
func (o *DefaultOperations) Download(ctx context.Context, release Release, root, destination string) (string, error)
Download obtains, digest-verifies, and safely extracts one release bundle.
func (*DefaultOperations) Install ¶
func (o *DefaultOperations) Install(ctx context.Context, manifest, root, installRoot string) (InstalledArtifacts, error)
Install executes the installer from the verified bundle.
func (*DefaultOperations) Preflight ¶
func (o *DefaultOperations) Preflight(ctx context.Context, _ Paths) error
Preflight checks the current user's platform, required host tools, hypervisor access, and ability to create the unprivileged user namespace used at launch.
func (*DefaultOperations) Running ¶
Running reports whether an owner-only socket accepts a local connection.
func (*DefaultOperations) Start ¶
func (*DefaultOperations) Start(_ context.Context, paths Paths) error
Start launches the installed daemon with absolute manager paths.
func (*DefaultOperations) Stop ¶
func (*DefaultOperations) Stop(ctx context.Context, paths Paths) error
Stop gracefully stops only the exact manager-owned daemon.
func (*DefaultOperations) Verify ¶
Verify rechecks that the extracted manifest still belongs to the verified bundle.
func (*DefaultOperations) WaitSocket ¶
func (*DefaultOperations) WaitSocket(ctx context.Context, socket string) error
WaitSocket waits until the daemon publishes an owner-only Unix socket.
type DeleteRequest ¶
DeleteRequest identifies one exact local-owner generation for permanent deletion.
type DeleteResult ¶
DeleteResult reports clean worktree removal or dirty retention.
type EgressRule ¶
EgressRule is one daemon-enforced guest destination allowance.
type Generation ¶
type Generation struct {
SessionID, EnvironmentID, Ref, WorktreePath, State, Error string
Generation uint32
Health microvmclient.GenerationHealth
}
Generation is one exact owner-scoped daemon generation.
type GuestEgressSelection ¶
type GuestEgressSelection struct {
Mode string
Allow []EgressRule
}
GuestEgressSelection is the host-operator projection of guest egress. It is intentionally not part of any public session API or project configuration surface.
func NewGuestEgressSelection ¶
func NewGuestEgressSelection() GuestEgressSelection
NewGuestEgressSelection returns the byte-compatible default policy selection.
func ParseGuestEgressSelection ¶
func ParseGuestEgressSelection(mode string, allow []string) (GuestEgressSelection, error)
ParseGuestEgressSelection parses settings values with the same destination grammar used by the command-line flags.
func (*GuestEgressSelection) AllowValue ¶
func (s *GuestEgressSelection) AllowValue() flag.Value
AllowValue returns a repeatable flag.Value for --microvm-guest-allow.
func (*GuestEgressSelection) ModeValue ¶
func (s *GuestEgressSelection) ModeValue() flag.Value
ModeValue returns a flag.Value for --microvm-guest-egress.
func (GuestEgressSelection) Validate ¶
func (s GuestEgressSelection) Validate() error
Validate rejects incomplete or contradictory selections.
type HostPaths ¶
type HostPaths struct {
Home, XDGConfigHome, XDGDataHome, XDGStateHome, XDGRuntimeDir string
UID int
GOOS string
}
HostPaths supplies environment-independent inputs for DefaultPaths.
type InstalledArtifacts ¶
type InstalledArtifacts struct {
Schema string `json:"schema,omitempty"`
Artifacts []Artifact `json:"artifacts"`
}
InstalledArtifacts is the existing release installer's strict projection.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager coordinates readiness and daemon lifecycle operations.
func DefaultLocal ¶
DefaultLocal builds the user-local manager without changing host state.
func New ¶
func New(paths Paths, ops Operations, lifecycle ...lifecycleClient) *Manager
New constructs a manager over explicit paths and operations.
func (*Manager) Delete ¶
func (m *Manager) Delete(ctx context.Context, request DeleteRequest) (DeleteResult, error)
Delete permanently destroys one exact generation. It never stops the daemon or removes verified installation state shared by other sessions.
func (*Manager) Doctor ¶
Doctor reports host preflight and backend health without downloading, installing, starting, or changing configuration.
func (*Manager) EnsureReady ¶
EnsureReady idempotently installs or validates the configured release and starts or reuses the exact compatible daemon. The inter-process manager lock serializes the complete transaction. Readiness is observed state: this method never edits the operator settings file.
func (*Manager) HostFallbackEnabled ¶
HostFallbackEnabled is deliberately false: manager failures never redirect a selected microVM session to host filesystem or shell execution.
type Operations ¶
type Operations interface {
Preflight(context.Context, Paths) error
Download(ctx context.Context, release Release, root, destination string) (string, error)
Verify(context.Context, Release, string) error
Install(ctx context.Context, manifest, root, installRoot string) (InstalledArtifacts, error)
Running(context.Context, Paths) (bool, error)
DaemonInfo(context.Context, Paths) (DaemonInfo, error)
Start(context.Context, Paths) error
WaitSocket(context.Context, string) error
Doctor(context.Context, Paths) (string, error)
Stop(context.Context, Paths) error
}
Operations is the OS/network/process boundary. DefaultOperations is the real implementation; tests can keep the complete manager journey offline.
type Paths ¶
type Paths struct {
StateDir, RuntimeDir, Socket, DataDir, ConfigFile, UserSettings string
DaemonBinary string
}
Paths are the absolute, user-owned manager paths.
func DefaultPaths ¶
DefaultPaths resolves XDG paths without requiring any XDG variable. The runtime directory uses a short /tmp path when any derived daemon socket would exceed Darwin's Unix-socket bound.
type Policy ¶
type Policy struct {
PolicyRevision, CertificateIdentity, OIDCIssuer string
PublicKey, PublicKeyIdentity string
RequiredAttestations map[string]string
GuestEgressMode string
GuestAllow []EgressRule
// contains filtered or unexported fields
}
Policy is the daemon-enforced local profile policy. Bootstrap writes it only to microvmd's strict config; the host alias contains only enabled+endpoint.
type ReadinessError ¶
type ReadinessError struct {
Stage ReadinessStage
Cause error
}
ReadinessError preserves the failed transaction stage for safe public classification while retaining the detailed cause for diagnostics.
func (*ReadinessError) Error ¶
func (e *ReadinessError) Error() string
func (*ReadinessError) Unwrap ¶
func (e *ReadinessError) Unwrap() error
type ReadinessFailure ¶
type ReadinessFailure struct {
Stage, Category, Cause string
}
ReadinessFailure is the bounded, path-free projection suitable for clients.
func ClassifyReadinessFailure ¶
func ClassifyReadinessFailure(err error, fallback ReadinessStage) ReadinessFailure
ClassifyReadinessFailure reduces a detailed readiness error to a closed public category and constant actionable cause. The original error remains diagnostics-only.
type ReadinessObserver ¶
type ReadinessObserver func(ReadinessStage, string)
ReadinessObserver receives only closed stage identifiers and constant display text. Release metadata, paths, credentials, and process output are never sent.
type ReadinessStage ¶
type ReadinessStage string
ReadinessStage is one bounded, secret-free phase of EnsureReady.
const ( StagePrepare ReadinessStage = "prepare" StagePreflight ReadinessStage = "preflight" StageDownload ReadinessStage = "download" StageVerify ReadinessStage = "verify" StageInstall ReadinessStage = "install" StageDaemon ReadinessStage = "daemon" StageSocket ReadinessStage = "socket" StageHealth ReadinessStage = "health" StageReady ReadinessStage = "ready" )
Readiness stages are emitted in transaction order.
type ReadyRequest ¶
ReadyRequest identifies the manager-owned release and daemon policy that ordinary use must converge before provisioning a microVM environment.
func ReadyRequestFromDefaults ¶
func ReadyRequestFromDefaults(encoded, version string, egress ...GuestEgressSelection) (ReadyRequest, error)
ReadyRequestFromDefaults validates one release-generated defaults projection and overlays an optional, already operator-selected guest-egress policy.
type Release ¶
type Release struct {
URL, SHA256 string
// contains filtered or unexported fields
}
Release identifies a bundle by an immutable, out-of-band SHA-256 digest.
type ReleaseDefaults ¶
type ReleaseDefaults struct {
Version string `json:"version"`
Platform string `json:"platform"`
URL string `json:"url"`
SHA256 string `json:"sha256"`
PolicyRevision string `json:"policy_revision"`
CertificateIdentity string `json:"certificate_identity"`
OIDCIssuer string `json:"oidc_issuer"`
}
ReleaseDefaults is the release-generated projection embedded in production composition roots.
type Status ¶
type Status struct {
Configured, Running bool
Socket string
GuestEgress string
Generations []Generation
Continuation string
}
Status reports manager state without starting or recreating anything.
type StatusRequest ¶
StatusRequest selects one bounded daemon inventory page.