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 ¶
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.
const Version = 1
Version is the only file format version this build accepts.
Variables ¶
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 Parse ¶
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 ¶
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 ¶
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 ¶
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 ¶
HasImageRules reports whether an image or registry list is set.
func (*Policy) RequireNonRoot ¶
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 ¶
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 ¶
BootError reports a file that has not loaded since startup. It clears once a reload succeeds.