prune

Documentation

Overview

Package prune implements scheduled host-health cleanup: a "prune" job kind run by the jobs runner, fed by a per-host scheduler that fires on a configurable interval or disk high-water threshold. It never reaps in-use resources.

Index

• Constants
• type Defaults
• type Handler
  • func (h *Handler) Run(ctx context.Context, job store.Job, jc *jobs.JobContext) error
• type HostPolicy
• type Metrics
• type Payload
• type Policy
  • func Resolve(hc *config.PruneConfig, def Defaults) (Policy, error)
  • func (p Policy) HasScope(s string) bool
• type Scheduler
  • func (s *Scheduler) Start(ctx context.Context, hostsFn func() []HostPolicy)
  • func (s *Scheduler) Wait()

Constants

const (
	ScopeDangling   = "dangling"    // dangling image layers
	ScopeAllImages  = "all-images"  // also unused tagged images
	ScopeContainers = "containers"  // exited containers
	ScopeBuildCache = "build-cache" // dangling build cache (libpod prunes it via the images-prune endpoint, which also reaps dangling image layers)
	ScopeVolumes    = "volumes"     // unused (unattached) volumes, protect-filtered
)

Scope tokens. Dangling is the only default; the rest are opt-in.

const ProtectLabel = "podman-api.protect"

ProtectLabel marks a volume that must never be reaped by the volumes scope. The volume prune passes a "label!" filter so volumes carrying it are excluded.

NOTE: internal/podman/real_prune_integration_test.go duplicates this string (the podman package cannot import prune — prune imports podman) and is the only test that exercises the real filter. If you rename this, update that copy.

const TickInterval = time.Minute

TickInterval is how often the scheduler re-evaluates every host. It is the granularity of both the interval and threshold gates.

Types

type Defaults

type Defaults struct {
	Enabled       bool
	Interval      time.Duration
	DiskThreshold int // percent 0..100; 0 disables the threshold trigger
	Scope         []string
	DryRun        bool
}

Defaults are the global flag-derived policy defaults a per-host config merges over.

type Handler

type Handler struct {
	Client podman.Client
	// Jobs, when set, enables a run-time safety re-check: before running the
	// volumes scope the handler re-queries for an active migrate/evacuate and
	// skips volumes if one is in flight. The scheduler also drops the volumes
	// scope at enqueue time, but a job can sit queued while a move starts, so the
	// guarantee belongs here too.
	Jobs    store.JobStore // optional
	Metrics Metrics        // optional
}

Handler implements jobs.Handler for the "prune" kind.

func (*Handler) Run

func (h *Handler) Run(ctx context.Context, job store.Job, jc *jobs.JobContext) error

Run executes the policy's enabled scopes in a fixed safe order.

type HostPolicy

type HostPolicy struct {
	Host   string
	Policy Policy
}

HostPolicy pairs a host id with its resolved policy. The caller (main) builds this slice once at startup and again on SIGHUP reload.

type Metrics

type Metrics interface {
	RunDone(host, result string)
	Reclaimed(host, scope string, bytes int64)
}

Metrics records prune outcomes. nil-safe via Handler.metric().

type Payload

type Payload struct {
	Host   string `json:"host"`
	Policy Policy `json:"policy"`
}

Payload is the job-args shape the scheduler enqueues and the handler reads. It carries a snapshot of the resolved policy so a mid-flight config reload cannot change a running job's behavior.

type Policy

type Policy struct {
	Enabled       bool
	Interval      time.Duration // zero disables the interval trigger
	DiskThreshold int           // percent 0..100; 0 disables the threshold trigger
	Scope         []string
	DryRun        bool
}

Policy is a fully-resolved, validated per-host prune policy. Defaults and Policy are intentionally the same shape: Defaults carries unvalidated flag-derived values, Policy is the post-Resolve, post-validate form.

func Resolve

func Resolve(hc *config.PruneConfig, def Defaults) (Policy, error)

Resolve merges a raw per-host config (nil = inherit everything) over defaults and validates the result. Unknown scope tokens, unparseable intervals, and out-of-range thresholds are errors.

func (Policy) HasScope

func (p Policy) HasScope(s string) bool

HasScope reports whether the policy enables scope s.

type Scheduler

type Scheduler struct {
	Store  store.JobStore
	Client podman.Client
	Now    func() time.Time
	// contains filtered or unexported fields
}

Scheduler enqueues prune jobs on a schedule. Store/Client/Now are injected so the tick logic is unit-testable without real time or a real podman host.

func (*Scheduler) Start

func (s *Scheduler) Start(ctx context.Context, hostsFn func() []HostPolicy)

Start launches the ticker loop until ctx is cancelled. hostsFn returns the current host policies on each tick (so SIGHUP reloads are picked up). An immediate first pass runs before the ticker so a host already over threshold (or past its interval) at boot is handled without waiting a full tick. Use Wait to block until the loop has exited after cancellation.

func (*Scheduler) Wait

func (s *Scheduler) Wait()

Wait blocks until the scheduler goroutine has exited (after its ctx is cancelled). Mirrors jobs.Runner so callers can drain cleanly on shutdown.