Documentation
¶
Overview ¶
Package execution owns agent-backed machine management, independently of the desktop/display grant and the existing serial/SSH/container exec bridges.
Index ¶
- Variables
- func CurrentEpoch(ws *unstructured.Unstructured, vmUID string) (uint64, error)
- type AdmissionRequest
- type ReplayAuthorizer
- type S3Config
- type Service
- func (s *Service) Admit(ctx context.Context, req AdmissionRequest) (*Session, error)
- func (s *Service) Close() error
- func (s *Service) Durability() storage.Durability
- func (s *Service) Get(ctx context.Context, executionID string) (storage.ExecutionRecord, storage.ExecutionOutcome, error)
- func (s *Service) List(ctx context.Context, f storage.Filter) ([]storage.ExecutionRecord, error)
- func (s *Service) Mode() string
- func (s *Service) Ready(ctx context.Context) error
- func (s *Service) RecordingStatus(ctx context.Context) (mode string, durable bool, available bool)
- func (s *Service) Replay(ctx context.Context, actorID, executionID string) (storage.Reader, storage.ExecutionRecord, error)
- func (s *Service) ReplayRecording(ctx context.Context, actorID, executionID string) (storage.Reader, storage.ExecutionRecord, error)
- func (s *Service) WithReplayAuthorizer(a ReplayAuthorizer) *Service
- type Session
- func (s *Session) Abort(ctx context.Context, reason string) error
- func (s *Session) AppendChunk(ctx context.Context, plaintext []byte) error
- func (s *Session) Audit(ctx context.Context, kind string, detail map[string]string) error
- func (s *Session) Finish(ctx context.Context, outcome storage.ExecutionOutcome) error
- func (s *Session) Record() storage.ExecutionRecord
- func (s *Session) Start(ctx context.Context) error
- type StorageConfig
- type StorageMode
Constants ¶
This section is empty.
Variables ¶
var ErrAdmissionDenied = errors.New("execution admission denied")
ErrAdmissionDenied is returned when an execution may not proceed. In every case the caller must treat it as fail-closed and must not start a process.
Functions ¶
func CurrentEpoch ¶
func CurrentEpoch(ws *unstructured.Unstructured, vmUID string) (uint64, error)
CurrentEpoch reads controller-owned status, bound to the current VM UID. A monotonic spec minimum may request revocation but never supplies authority. Missing status (including an old CRD pruning it), malformed state, and a request not yet acknowledged by the controller all deny admission.
Types ¶
type AdmissionRequest ¶
type AdmissionRequest struct {
ExecutionID string
RecordingID string
ActorID string
Operation storage.Operation
Namespace string
WorkspaceName string
WorkspaceUID string
WorkspaceGeneration int64
GrantVersion string
OSIdentity string
Elevated bool
}
AdmissionRequest is the off-guest, already-authorized description of one execution. The caller must have authenticated the actor and checked the controller-owned grants BEFORE calling Admit; the service only enforces storage readiness, durability and recording.
type ReplayAuthorizer ¶
type ReplayAuthorizer interface {
AuthorizeReplay(ctx context.Context, actorID string, rec storage.ExecutionRecord) error
}
ReplayAuthorizer decides whether a principal may replay a recording. It must re-check workspace.execution.recordings.read against the record's namespace and workspace on every call; it must never trust a previously-admitted execution ID as authority on its own.
type S3Config ¶
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the execution admission and recording coordinator. A zero-value or disabled store can never admit work, and a persistent store that is not Ready is never treated as permission to run.
func NewService ¶
NewService builds the coordinator. A nil store disables admission entirely (every Admit fails closed with ErrAdmissionDenied). Replay is denied until a ReplayAuthorizer is supplied via WithReplayAuthorizer.
func (*Service) Admit ¶
Admit durably records the admission before any process is created, opens the mandatory recording, and returns a session for streaming output and audit. The returned error always wraps ErrAdmissionDenied so callers cannot mistake a failure for permission to run.
func (*Service) Durability ¶
func (s *Service) Durability() storage.Durability
func (*Service) Get ¶
func (s *Service) Get(ctx context.Context, executionID string) (storage.ExecutionRecord, storage.ExecutionOutcome, error)
Get returns the stored admission record and its last known outcome. It fails closed when storage is disabled or unready.
func (*Service) List ¶
List returns admission records matching the filter. The caller must scope the filter to what the actor is allowed to see before calling; this method only enforces storage readiness.
func (*Service) Ready ¶
Ready reports whether the backing store can admit work. It is safe to call on a nil-store service and returns the store error otherwise.
func (*Service) RecordingStatus ¶
RecordingStatus reports whether the store can admit and replay recordings right now. It never returns an error; callers use it for capability display.
func (*Service) Replay ¶
func (s *Service) Replay(ctx context.Context, actorID, executionID string) (storage.Reader, storage.ExecutionRecord, error)
Replay authorizes, verifies, and audits access before returning any recording.
func (*Service) ReplayRecording ¶
func (s *Service) ReplayRecording(ctx context.Context, actorID, executionID string) (storage.Reader, storage.ExecutionRecord, error)
ReplayRecording authorizes and opens the finalized recording bound to executionID, mirroring Replay but keyed by the execution the caller saw.
func (*Service) WithReplayAuthorizer ¶
func (s *Service) WithReplayAuthorizer(a ReplayAuthorizer) *Service
WithReplayAuthorizer installs the replay policy and returns the service.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session serializes recording and lifecycle operations for one admission.
func (*Session) Abort ¶
Abort preserves partial evidence and marks the execution failed. The caller must terminate any running process; this coordinator never owns a process.
func (*Session) AppendChunk ¶
AppendChunk encrypts and stores the next contiguous recording chunk. Plaintext ordering is preserved; a gap is impossible because indices are session-owned.
func (*Session) Finish ¶
Finish finalizes the recording and writes the terminal outcome. If finalizing the recording fails the outcome is marked recording_lost; the execution is still finalized so the state never silently stays running.
func (*Session) Record ¶
func (s *Session) Record() storage.ExecutionRecord
Record returns a copy of the admission record bound to this session.
type StorageConfig ¶
type StorageConfig struct {
Mode StorageMode
RecordingRetention time.Duration
MetadataRetention time.Duration
EphemeralDir string
EphemeralMaxBytes int64
DatabaseURL string `json:"-"`
S3 S3Config
KeyID string
// contains filtered or unexported fields
}
StorageConfig contains resolved deployment configuration, not runtime storage health. A valid configuration alone must never enable execution admission.
func StorageConfigFromEnv ¶
func StorageConfigFromEnv() (StorageConfig, error)
func (StorageConfig) Persistent ¶
func (c StorageConfig) Persistent() bool
func (StorageConfig) RecordingKey ¶
func (c StorageConfig) RecordingKey() []byte
RecordingKey returns a copy of the recording encryption key for storage engines. The result is secret material; never log it.
func (StorageConfig) StorageOptions ¶
func (c StorageConfig) StorageOptions() storage.Options
StorageOptions translates the validated deployment configuration into the decoupled storage options. It never enables admission on its own: callers must Open the store and require Ready before permitting execution.
func (StorageConfig) String ¶
func (c StorageConfig) String() string
String prevents accidental credential/key disclosure through ordinary logging.
type StorageMode ¶
type StorageMode string
const ( StorageDisabled StorageMode = "disabled" StorageEphemeral StorageMode = "ephemeral" StorageExternal StorageMode = "external" StorageBundled StorageMode = "bundled" )
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package enrollment implements one-use, CSR-bound management bootstrap issuance.
|
Package enrollment implements one-use, CSR-bound management bootstrap issuance. |
|
Package grants defines the independently verifiable management-v1 grant envelope.
|
Package grants defines the independently verifiable management-v1 grant envelope. |
|
Package management wires the opt-in management issuer and trusted bootstrap importer.
|
Package management wires the opt-in management issuer and trusted bootstrap importer. |
|
Package pki defines management-only certificate identities and mutual TLS.
|
Package pki defines management-only certificate identities and mutual TLS. |
|
Package qga implements the server side of the approved QGA pod-exec pilot transport (`qga-pod-exec/v1`): a Kubernetes-authenticated pod exec into the current KubeVirt virt-launcher, driving the fixed installed runner through the QEMU guest agent.
|
Package qga implements the server side of the approved QGA pod-exec pilot transport (`qga-pod-exec/v1`): a Kubernetes-authenticated pod exec into the current KubeVirt virt-launcher, driving the fixed installed runner through the QEMU guest agent. |
|
Package storage implements the durable-and-ephemeral execution store: a searchable metadata/audit layer (PostgreSQL in persistent modes, bounded in-memory in ephemeral mode) plus an encrypted, hash-chained recording chunk store (S3-compatible in persistent modes, bounded encrypted temp files in ephemeral mode).
|
Package storage implements the durable-and-ephemeral execution store: a searchable metadata/audit layer (PostgreSQL in persistent modes, bounded in-memory in ephemeral mode) plus an encrypted, hash-chained recording chunk store (S3-compatible in persistent modes, bounded encrypted temp files in ephemeral mode). |
|
Package updates verifies publisher-authenticated agent-update manifests, authenticated machine inventory reports and the write-ahead upgrade journal, plus bounded payload streams.
|
Package updates verifies publisher-authenticated agent-update manifests, authenticated machine inventory reports and the write-ahead upgrade journal, plus bounded payload streams. |
|
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.
|
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. |