createpolicy

package
v0.6.13 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package createpolicy loads the operator's create policy (SB_CREATE_POLICY_FILE, plans/agent-sandbox-feature-parity.md T3): which images, registries and runtimes a create may use, how big a sandbox may be, whether its image must run as a non-root user and whether it may ask for a GPU. sandboxd checks it in memory at create and resize; the file is read at boot and on reload, never on the create path. Unset means today's behavior: every rule is off.

Index

Constants

View Source
const (
	RuleImages         = "images"
	RuleRuntimes       = "runtimes"
	RuleMaxCPU         = "limits.max_cpu"
	RuleMaxMemoryMB    = "limits.max_memory_mb"
	RuleMaxDiskGB      = "limits.max_disk_gb"
	RuleRequireNonRoot = models.CreatePolicyRuleRequireNonRoot
	RuleAllowGPU       = "allow_gpu"
)

Rule names, as a refusal and the aerolvm_create_policy_denied_total metric name them. Each is the YAML path of the setting that refused.

View Source
const Version = 1

Version is the only file format version this build accepts.

Variables

View Source
var ErrInvalidAtBoot = errors.New("create policy file invalid")

ErrInvalidAtBoot is returned when the file is set but did not load at startup. Callers refuse creates and resizes (503 create_policy_invalid): the limits are unknown, so failing closed is the only safe answer.

Functions

This section is empty.

Types

type Create

type Create struct {
	// Image is the image the runtime will start, after snapshot names are
	// resolved; empty for a runtime that runs no image.
	Image string
	// ImageRules is false for runtimes that run a module or a bundle, not an
	// image (wasm, isolate): the image rules do not apply to them.
	ImageRules bool
	// LocalOnly marks an image only this node can have (a snapshot commit
	// or a build): it was never pulled from a registry, so only an image
	// pattern can allow it.
	LocalOnly bool
	// ImageID marks a reference the engine resolves by image id: it names
	// no repository, so no rule can allow it.
	ImageID  bool
	Runtime  string
	CPU      float64
	MemoryMB int
	DiskGB   int
	GPU      bool
}

Create is what a create is checked on: the values after the server's defaults are filled in, so a create that leaves a field out is held to the same limit as one that sets it.

type File

type File struct {
	Version int `yaml:"version"`
	Images  struct {
		// AllowedRegistries are registry hosts (with a port when the
		// registry has one); an image from one of them passes.
		AllowedRegistries []string `yaml:"allowed_registries"`
		// Allowed are image patterns; "*" matches any run of characters,
		// "/" included.
		Allowed []string `yaml:"allowed"`
	} `yaml:"images"`
	Runtimes []string `yaml:"runtimes"`
	Limits   struct {
		MaxCPU      float64 `yaml:"max_cpu"`
		MaxMemoryMB int     `yaml:"max_memory_mb"`
		MaxDiskGB   int     `yaml:"max_disk_gb"`
	} `yaml:"limits"`
	RequireNonRoot bool  `yaml:"require_non_root"`
	AllowGPU       *bool `yaml:"allow_gpu"`
}

File is the YAML document.

type Policy

type Policy struct {
	// contains filtered or unexported fields
}

Policy is a validated create policy. A nil *Policy allows everything, so callers never branch on "is there a file".

func Load

func Load(path string) (*Policy, error)

Load reads and validates path.

func Parse

func Parse(raw []byte) (*Policy, error)

Parse validates a policy document. Unknown keys and explicitly empty lists are errors: in a security file a typo, or "allowed: []" meant as "allow nothing", must not silently mean "no rule".

func (*Policy) CheckCreate

func (p *Policy) CheckCreate(c Create) error

CheckCreate applies every rule and returns the first refusal (*models.CreatePolicyError): the runtime first, since it decides whether the image rules apply, then the image, the size and the GPU.

func (*Policy) CheckImage

func (p *Policy) CheckImage(image string, localOnly, imageID bool) error

CheckImage holds an image reference to the image rules. It matches the parsed reference, never the caller's spelling: "python:3.12", "docker.io/library/python:3.12" and "index.docker.io/library/python:3.12" are one image and get one answer. A pattern is tried against both the full name (docker.io/library/python:3.12) and the short one (python:3.12), which name the same image, so either style works in the file.

func (*Policy) CheckSize

func (p *Policy) CheckSize(cpu float64, memoryMB, diskGB int) error

CheckSize holds a size to the limits. A zero value is "not changing" (a resize names only what it changes) and always passes.

func (*Policy) HasImageRules

func (p *Policy) HasImageRules() bool

HasImageRules reports whether an image or registry list is set.

func (*Policy) Hash

func (p *Policy) Hash() string

Hash identifies the file's content.

func (*Policy) RequireNonRoot

func (p *Policy) RequireNonRoot() bool

RequireNonRoot reports whether container images must run as a non-root user. The runtime checks it once it has the image config (models.CheckImageUserNonRoot).

type Watcher

type Watcher struct {
	// contains filtered or unexported fields
}

Watcher keeps the last good policy, the same way the egress operator file's watcher does (internal/egress/operator): a changed file is picked up by an mtime poll and by Reload (SIGHUP); an invalid reload keeps the last good policy and counts a failure. Unlike the egress file, a path that names no file is an error at boot, not "no policy": an operator who set the variable expects its rules, and a missing file would drop them all.

func NewWatcher

func NewWatcher(path string, log *slog.Logger) *Watcher

NewWatcher loads path once. An empty path means no policy (nil Policy, today's behavior). A file that is missing or invalid leaves BootError set until a later reload succeeds.

func (*Watcher) BootError

func (w *Watcher) BootError() error

BootError reports a file that has not loaded since startup. It clears once a reload succeeds.

func (*Watcher) Current

func (w *Watcher) Current() *Policy

Current returns the last good policy, or nil.

func (*Watcher) Failures

func (w *Watcher) Failures() uint64

Failures counts failed loads (aerolvm_create_policy_load_failures_total).

func (*Watcher) Reload

func (w *Watcher) Reload() error

Reload re-reads the file now.

func (*Watcher) Run

func (w *Watcher) Run(ctx context.Context, interval time.Duration)

Run polls the file's mtime every interval until ctx ends.

Jump to

Keyboard shortcuts

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