Documentation
¶
Overview ¶
Package resolve decides which package versions to install and whether a package's requirements and conflicts are satisfied.
It deliberately is not a general SAT solver. Requirements are mostly on capabilities, constraints are expected to be loose, and a distribution pins exact versions; a solver that finds clever combinations nobody tested would be a liability. The search below takes the highest acceptable version of each package, prefers providers that are already installed, and backtracks only within that order.
Index ¶
- Constants
- Variables
- func CheckRequirement(q v1.Requirement) error
- func Conflicts(r Release, st State) []string
- func Satisfies(version, constraint string) (bool, error)
- type Action
- type Catalog
- type Change
- type Installed
- type Pass
- type Passed
- type Plan
- type Release
- type Request
- type Requirement
- type State
- type Unmet
Constants ¶
const APIPrefix = "api:"
APIPrefix marks a capability that the API server can satisfy through discovery, e.g. "api:cert-manager.io/v1".
const Unversioned = "0.0.0-unversioned"
Unversioned is the version of a package that declares none.
Variables ¶
var ErrConflictingRequirements = errors.New("packages that require it disagree")
ErrConflictingRequirements is returned when packages that require the same package ask for different variants of it or pass different values for the same key.
var ErrUnresolvable = errors.New("requests cannot be satisfied")
ErrUnresolvable is returned when no combination satisfies the requests. The wrapped message explains the closest attempt.
Functions ¶
func CheckRequirement ¶ added in v1.3.0
func CheckRequirement(q v1.Requirement) error
CheckRequirement refuses what a requirement cannot carry: a variant or values without a package, or values that are not an object.
Types ¶
type Change ¶
type Change struct {
Name string
From string
To string
Action Action
// Reason says why the package is in the plan: "requested" or the
// requirement that pulled it in.
Reason string
// Variant is the variant the package is resolved in.
Variant string
// Passed is what the packages requiring this one pass to it.
Passed Passed
}
Change is one line of a plan.
type Installed ¶
type Installed struct {
Release
Ready bool
// VariantSet is true when the Package names its variant, so the
// variant is a choice the plan must not change.
VariantSet bool
// Leaving is true for a package being deleted: what it passes to the
// packages it requires no longer counts.
Leaving bool
}
Installed is a package present in the cluster.
type Pass ¶ added in v1.3.0
type Pass struct {
From string
Variant string
Values map[string]map[string]any
// Invalid says why the requirement's values cannot be read.
Invalid string
}
Pass is what one package passes to a package it requires: a variant, values by component, or both.
type Passed ¶ added in v1.3.0
type Passed struct {
// Variant is the variant they ask for; empty when none asks.
Variant string
// Values are the values for each component, merged.
Values map[string]map[string]any
// From names the packages that pass something, sorted.
From []string
}
Passed is the merged outcome of what several packages pass to one.
func MergePasses ¶ added in v1.3.0
MergePasses merges what several packages pass to the package name. Values merge key by key; two packages setting the same key to different values, or asking for different variants, is an error wrapping ErrConflictingRequirements that names them. Nothing is resolved silently, since either choice would break the other package.
type Plan ¶
type Plan struct {
Changes []Change
}
Plan is the outcome of resolving a set of requests.
type Release ¶
type Release struct {
Name string
Version string
Provides []string
Requires []Requirement
Conflicts []string
// Variant is the variant Requires belongs to; empty means default.
Variant string
// Variants holds the requirements of every variant, so a package can
// be resolved in a variant that a package requiring it asks for.
Variants map[string][]Requirement
}
Release is one version of a package as published in a repository.
func ReleaseOf ¶
ReleaseOf describes one variant of a package version for resolving, with the requirements of its other variants for packages that require it in one of them. A missing variant leaves the release without requirements.
func (Release) VariantName ¶ added in v1.3.0
VariantName is the variant a release is resolved in.
type Requirement ¶
type Requirement struct {
Package string
Capability string
Version string
Optional bool
// Variant is the variant of the required package asked for.
Variant string
// Values are passed to the required package's components, by
// component name.
Values map[string]map[string]any
// Invalid says why values given for the requirement cannot be read.
Invalid string
}
Requirement is a dependency on a package or a capability.
func RequirementsOf ¶
func RequirementsOf(v *v1.Variant, ignore []string) []Requirement
RequirementsOf turns a variant's dependsOn and requires into requirements, minus the packages and capabilities listed in ignore.
func (Requirement) String ¶
func (r Requirement) String() string
type State ¶
type State struct {
Packages map[string]Installed
// APIs holds served group versions, e.g. "cert-manager.io/v1".
APIs map[string]bool
}
State is what the cluster has: installed packages and served APIs.
type Unmet ¶
type Unmet struct {
Requirement Requirement
Reason string
}
Unmet is a requirement that is not satisfied, with the reason.
func Check ¶
func Check(reqs []Requirement, st State) ([]Unmet, error)
Check evaluates requirements against the cluster. A requirement is met only by a Ready package, because the operator uses this to gate installation: something that exists but is not working yet does not count. Optional requirements are reported only when present but not ready.