scheduledsnapshots

package

v0.2.0 Latest Latest Go to latest Published: Jul 8, 2026 License: MIT Imports: 8 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/kernel/hypeman

Links

Open Source Insights

README ¶

Scheduled Snapshots

This feature lets users attach a periodic snapshot policy to an instance.

A schedule runs on a fixed interval (for example 1h or 24h).
New schedules establish cadence at now + interval + deterministic jitter derived from the instance ID.
Updating only retention, metadata, or name_prefix preserves next_run_at; changing interval establishes a new cadence.
Each run auto-selects snapshot behavior from current instance state:
- Running or Standby source -> Standby snapshot
- Stopped source -> Stopped snapshot
For running sources, scheduled capture includes a brief pause/resume cycle during snapshot creation.
The minimum interval is 1m, but running/standby captures briefly pause/resume the guest, so larger intervals are recommended for heavier workloads.
Each schedule stores runtime status (next_run_at, last_run_at, last_snapshot_id, last_error).

Retention cleanup is required per schedule and can use either or both:

max_count: keep only the newest N scheduled snapshots for that instance.
max_age: delete scheduled snapshots older than a duration.

Cleanup only applies to snapshots created by that schedule for that same source instance. Manual snapshots are never deleted by scheduled retention.

If the source instance is deleted, the schedule is kept so retention can continue cleaning previously created scheduled snapshots. Once no scheduled snapshots remain for that deleted instance, the scheduler removes the stale schedule automatically.

Documentation ¶

Index ¶

Constants
func BuildSnapshotMetadata(instanceID string, userMetadata tags.Tags) tags.Tags
func BuildSnapshotName(prefix string, runAt time.Time) string
func InitialNextRunAt(instanceID string, interval time.Duration, now time.Time) time.Time
func IsScheduledSnapshot(metadata tags.Tags, instanceID string) bool
func ListInstanceIDs(dir string) ([]string, error)
func MarshalSchedule(schedule *Schedule) ([]byte, error)
func NextRun(previous time.Time, interval time.Duration, now time.Time) time.Time
func ValidateSetRequest(req SetRequest, validateName func(name string) error) error
type Retention
type Schedule
- func UnmarshalSchedule(content []byte) (*Schedule, error)
type SetRequest

Constants ¶

View Source

const (
	MetadataKeyScheduled        = "hypeman.scheduled"
	MetadataKeySourceInstanceID = "hypeman.schedule_instance_id"
	DefaultNamePrefix           = "scheduled"
	NameTimestampFormat         = "20060102-150405"
	MaxSnapshotNameLength       = 63
	MaxNamePrefixLength         = MaxSnapshotNameLength - len(NameTimestampFormat) - 1
	MinInterval                 = time.Minute
)

Variables ¶

This section is empty.

Functions ¶

func BuildSnapshotMetadata ¶

func BuildSnapshotMetadata(instanceID string, userMetadata tags.Tags) tags.Tags

func BuildSnapshotName ¶

func BuildSnapshotName(prefix string, runAt time.Time) string

func InitialNextRunAt ¶

func InitialNextRunAt(instanceID string, interval time.Duration, now time.Time) time.Time

func IsScheduledSnapshot ¶

func IsScheduledSnapshot(metadata tags.Tags, instanceID string) bool

func ListInstanceIDs ¶

func ListInstanceIDs(dir string) ([]string, error)

func MarshalSchedule ¶

func MarshalSchedule(schedule *Schedule) ([]byte, error)

func NextRun ¶

func NextRun(previous time.Time, interval time.Duration, now time.Time) time.Time

func ValidateSetRequest ¶

func ValidateSetRequest(req SetRequest, validateName func(name string) error) error

Types ¶

type Retention ¶

type Retention struct {
	MaxCount int           // Keep at most this many scheduled snapshots for the instance (0 = unlimited)
	MaxAge   time.Duration // Delete scheduled snapshots older than this age (0 = unlimited)
}

Retention defines automatic cleanup rules for scheduled snapshots.

type Schedule ¶

type Schedule struct {
	InstanceID     string
	Interval       time.Duration
	NamePrefix     string
	Metadata       tags.Tags
	Retention      Retention
	NextRunAt      time.Time
	LastRunAt      *time.Time
	LastSnapshotID *string
	LastError      *string
	CreatedAt      time.Time
	UpdatedAt      time.Time
}

Schedule defines periodic snapshot capture for a single instance.

func UnmarshalSchedule ¶

func UnmarshalSchedule(content []byte) (*Schedule, error)

type SetRequest ¶

type SetRequest struct {
	Interval   time.Duration
	NamePrefix string
	Metadata   tags.Tags
	Retention  Retention
}

SetRequest configures or updates a schedule for an instance.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL