Documentation
¶
Overview ¶
Package upgrades implements durable off-guest agent-upgrade admission: an exclusive per-VM reservation, idempotent start, safe cancellation, explicit rollback admission and the recording/audit evidence trail. It admits and records only; artifact verification, guest dispatch and the updater transport are separate mandatory slices and never implicit here.
Index ¶
- Constants
- Variables
- type AdmitRequest
- type Service
- func (s *Service) ActiveAttempt(ctx context.Context, vmUID string) (storage.AgentUpgradeAttempt, error)
- func (s *Service) Admit(ctx context.Context, req AdmitRequest) (storage.AgentUpgradeAttempt, bool, error)
- func (s *Service) Cancel(ctx context.Context, attemptID string) (storage.AgentUpgradeAttempt, error)
- func (s *Service) Durability() storage.Durability
- func (s *Service) Get(ctx context.Context, attemptID string) (storage.AgentUpgradeAttempt, error)
- func (s *Service) Ready(ctx context.Context) error
- func (s *Service) Rollback(ctx context.Context, attemptID string) (storage.AgentUpgradeAttempt, error)
Constants ¶
const OperationAgentUpgradeStart = "agent-upgrade.start.v1"
OperationAgentUpgradeStart is the durable grant/attempt operation name.
Variables ¶
var ( // must never downgrade a persistent outage to an in-memory reservation. ErrUnavailable = errors.New("agent upgrade admission unavailable") // ErrDenied is returned when policy or authorization refuses the request. ErrDenied = errors.New("agent upgrade admission denied") // ErrInvalid is returned for structurally invalid requests. ErrInvalid = errors.New("invalid agent upgrade request") // ErrNotFound is returned for unknown attempts. ErrNotFound = errors.New("upgrade attempt not found") // ErrConflict is returned for conflicting reservations, idempotency keys // or illegal state transitions. ErrConflict = errors.New("upgrade attempt conflicts with existing state") )
Functions ¶
This section is empty.
Types ¶
type AdmitRequest ¶
type AdmitRequest struct {
Namespace string
WorkspaceName string
WorkspaceUID string
VMUID string
ActorUID string
TargetID string
TargetManifestSHA256 string
ExpectedInstalledInventorySHA256 string
ExpectedRevocationEpoch uint64
IdempotencyKey string
AllowReboot bool
}
AdmitRequest is the already-authorized admission of one upgrade attempt. The caller must have authenticated a UID-bound administrator, checked platform policy and resolved the exact workspace/VM identity.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service coordinates durable upgrade attempts with the execution recording store. A nil store or attempts store disables admission entirely.
func NewService ¶
func NewService(store storage.Store, attempts storage.AgentUpgradeStore) *Service
NewService builds the coordinator. Both dependencies may be nil, which disables admission fail-closed.
func (*Service) ActiveAttempt ¶
func (s *Service) ActiveAttempt(ctx context.Context, vmUID string) (storage.AgentUpgradeAttempt, error)
ActiveAttempt returns the reservation-holding attempt for a VM.
func (*Service) Admit ¶
func (s *Service) Admit(ctx context.Context, req AdmitRequest) (storage.AgentUpgradeAttempt, bool, error)
Admit durably records the admission before any guest effect, opens the mandatory attempt recording and reserves the exclusive per-VM attempt. An identical idempotent replay returns the original attempt with replayed true; a replay with a different request is a conflict.
func (*Service) Cancel ¶
func (s *Service) Cancel(ctx context.Context, attemptID string) (storage.AgentUpgradeAttempt, error)
Cancel closes out or requests safe cancellation. Before any install phase the attempt is cancelled immediately; during mutation it only records the request and the worker stops at its next safe transaction boundary. Stuck uncertain states are cleared by administrators through the same route.
func (*Service) Durability ¶
func (s *Service) Durability() storage.Durability
Durability describes the active recording store, or "none" when disabled.
func (*Service) Ready ¶
Ready reports whether both the recording/metadata store and the attempt store can admit work.
func (*Service) Rollback ¶
func (s *Service) Rollback(ctx context.Context, attemptID string) (storage.AgentUpgradeAttempt, error)
Rollback admits a separate, explicit rollback of a failed attempt to its pinned predecessor payload. The attempt must have failed and the worker must have pinned the predecessor from the verified manifest; admission itself performs no guest effect.
Source Files