Documentation
¶
Overview ¶
Package config derives KubeSolo's runtime configuration.
BuildEmbedded turns the resolved settings into the types.Embedded struct that every service is constructed from. It is deliberately free of side effects — no host probing, no filesystem writes, no process exit — so that the mapping from settings to paths can be tested directly. Host probing (node IP, MTU, container detection) happens in the caller and arrives here as Input.
Index ¶
- Variables
- func BuildEmbedded(cfg *types.Config, probe Probe) types.Embedded
- func CheckSetOnce(current, next *types.Config) error
- func Defaults() *types.Config
- func Marshal(cfg *types.Config) ([]byte, error)
- func MergePatchFor(path string, cfg *types.Config) ([]byte, error)
- func NormaliseImageRef(image string) (string, error)
- func ResolveContainerMode(cfg *types.Config, detected bool) bool
- func Write(path string, cfg *types.Config) error
- type Descriptor
- type Field
- type FlagValues
- type Host
- type Mutability
- type Probe
- type SetOnceError
- type Warning
- func Load(cfgPath string, fv FlagValues) (*types.Config, []Warning, error)
- func LoadWithoutEnv(cfgPath string, fv FlagValues) (*types.Config, []Warning, error)
- func Read(path string, cfg *types.Config) (found bool, warnings []Warning, err error)
- func Validate(cfg *types.Config, host Host) ([]Warning, error)
Constants ¶
This section is empty.
Variables ¶
var Registry = sync.OnceValue(buildRegistry)
Registry is every configurable setting. It is the source of truth: a setting absent from here is invisible to the loader, the CLI and the API.
The table is built once and shared. Treat the result as read-only — it is a constant, and callers on the request path would otherwise rebuild twenty-nine closures apiece.
--full is deliberately absent. It has had no effect for several releases; the flag remains and still warns, but there is nothing to configure.
Functions ¶
func BuildEmbedded ¶
BuildEmbedded derives every path and setting KubeSolo runs with.
func CheckSetOnce ¶ added in v1.2.3
CheckSetOnce returns a *SetOnceError for the first set-once setting next changes, when current configures a Portainer agent. Callers pass as current the configuration KubeSolo started with, which the agent was deployed from.
func Defaults ¶
Defaults returns the configuration KubeSolo runs with when nothing is set.
This is the single source of the default values. The kingpin flags carry no defaults of their own: a flag that declared one would be indistinguishable from a flag the user set, and the config file could then never win over it.
func MergePatchFor ¶
MergePatchFor builds the smallest RFC 7386 merge patch that sets one setting to the value it holds in cfg.
A dotted config path is also the path through the JSON document — "network. nodeIP" is {"network":{"nodeIP":...}} — so the patch is that nesting with the typed value at the leaf. Taking the value from a marshalled document rather than from Get keeps the JSON representation authoritative: a map, a list and an int each land in the patch exactly as the server would read them back.
func NormaliseImageRef ¶
NormaliseImageRef expands a short image reference such as portainerci/agent:develop into a fully qualified one (docker.io/portainerci/agent:develop). The containerd client, unlike the Docker CLI, applies no Docker Hub defaults and would otherwise treat the first component as a registry host and fail to resolve it.
func ResolveContainerMode ¶
ResolveContainerMode reports whether KubeSolo runs in container mode: the configured value if it states one, otherwise what detection found.
func Write ¶
Write saves cfg, replacing any existing file atomically.
The new document is written to a temporary file in the same directory, then renamed over the target. At no point does the path hold a partial document: a reader sees either the whole previous file or the whole new one, which matters on an edge device that can lose power mid-write.
The temporary file is deliberately created in the target directory rather than the system temp directory. /etc and /tmp are routinely separate filesystems, and os.Rename cannot cross one (EXDEV).
The previous file is copied — not moved — to path + ".bak" beforehand, so the original stays readable right up to the instant it is replaced.
Types ¶
type Descriptor ¶
type Descriptor struct {
Path string `json:"path"`
// Type is the JSON type of the value: string, boolean, integer, array or
// object.
Type string `json:"type"`
// Default is what the setting holds when nothing sets it.
Default any `json:"default"`
// Flag is the deprecated CLI flag, without leading dashes. Absent for
// settings that never had one.
Flag string `json:"flag,omitempty"`
Envar string `json:"envar,omitempty"`
// Mutability is "restart", "immutable" or "set-once" — whether changing
// this on an existing install can take effect at all.
Mutability string `json:"mutability"`
// Secret marks a value that is redacted when read back.
Secret bool `json:"secret,omitempty"`
}
Descriptor describes one setting for something that has to present it — the CLI's schema command, and the config API's schema endpoint.
It is derived entirely from Registry(), so a setting cannot be added without appearing here.
type Field ¶
type Field struct {
// ConfigPath is the dotted path in the config document, e.g. "network.nodeIP".
ConfigPath string
// Flag is the frozen CLI flag, without leading dashes. Empty for settings
// that never had one.
Flag string
// Envar is the environment variable, empty if there is none.
Envar string
// Secret marks a value that must be redacted in API responses.
Secret bool
Mutability Mutability
// Get reads the current value, for display and for diffing.
Get func(*types.Config) any
// Set applies a value in its flag/environment string form. The config file
// is not routed through here — it is unmarshalled directly.
Set func(*types.Config, string) error
}
Field describes one configurable setting once, so that the config path, the frozen flag, the environment variable and the mutability class cannot drift apart. Everything that needs to enumerate settings — the loader, the dotted path CLI, the API schema and the restart-required report — reads this.
func FieldByPath ¶
FieldByPath looks up a single setting by its dotted config path.
type FlagValues ¶
FlagValues carries the parsed command line into the loader.
SetByUser is the part that matters. kingpin marks a flag as set by the user only when it came from the command line; a value supplied through the environment is applied via the same path as a default and is indistinguishable from one. Environment variables are therefore resolved here, directly against os.LookupEnv, rather than read back off the flag.
type Host ¶
type Host struct {
NumCPU int
GOARCH string
// ContainerMode is what host detection found. It is only consulted when the
// configuration does not state one explicitly.
ContainerMode bool
}
Host carries what the validator cannot discover for itself. Passing these in rather than reading runtime.NumCPU and runtime.GOARCH directly keeps Validate free of side effects, and lets architecture-specific rules be tested on any machine.
type Mutability ¶
type Mutability int
Mutability says whether a setting can be changed on an existing install.
const ( // MutabilityRestart means the change takes effect when KubeSolo restarts. // Almost everything is this: settings are read once during bootstrap and // baked into types.Embedded, which each service is constructed from. MutabilityRestart Mutability = iota // MutabilityImmutable means the change cannot be applied at all. Only Path // is immutable: every certificate, the kine database and all containerd // state live below it, and nothing migrates them. MutabilityImmutable // MutabilitySetOnce means the setting can be set while no Portainer agent // is configured, and not changed after. KubeSolo creates the agent's // ConfigMap and Secret from these when it first deploys the agent and // never updates them, so a later change would be saved but never applied. MutabilitySetOnce )
func (Mutability) String ¶
func (m Mutability) String() string
type Probe ¶
type Probe struct {
// Hostname is the host's name, the fallback for kubernetes.nodeName.
Hostname string
NodeIP string
NodeIPPinned bool
LoadBalancerIP string
MTU int
MTUPinned bool
ContainerMode bool
// RuntimeEndpoint is the endpoint parsed from runtime.endpoint. The zero
// value means KubeSolo runs its own containerd, in which case BuildEmbedded
// substitutes the embedded endpoint under the configured path.
RuntimeEndpoint cri.Endpoint
}
Probe carries what the host reported and BuildEmbedded cannot work out for itself. Everything else it needs comes from the configuration.
type SetOnceError ¶ added in v1.2.3
type SetOnceError struct {
Field string
}
SetOnceError is a change to a set-once setting after the Portainer agent is configured.
func (*SetOnceError) Error ¶ added in v1.2.3
func (e *SetOnceError) Error() string
type Warning ¶
type Warning struct {
// Field is the config path the warning concerns, empty if it concerns the
// document as a whole.
Field string
Message string
}
Warning is something worth telling the operator about that is not fatal.
func Load ¶
Load resolves the effective configuration.
Precedence, lowest to highest: built-in defaults, the config file, the environment, the command line. Each layer only overwrites the settings it actually specifies.
func LoadWithoutEnv ¶
LoadWithoutEnv is Load with the environment layer omitted.
It exists for kubesoloctl, which builds a configuration file for a service it is about to install. The environment kubesoloctl happens to run in is not the one that service will run in, and folding it in would write values into the file that the operator never asked for.
func Read ¶
Read parses a config file onto cfg, leaving keys the file does not mention at whatever cfg already holds. Callers pass Defaults(), so a file that sets one setting does not reset the rest.
A missing file is not an error: it reports found=false and leaves cfg alone. That is the state of every install made before the config file existed.
func Validate ¶
Validate checks a configuration and normalises it in place — expanding the Portainer image reference, filling in the CPU reservation the static policy requires, and disabling d2k where it cannot run.
It has no side effects beyond cfg and never exits. Startup treats a returned error as fatal; the config API turns it into a rejected request. A validator that called log.Fatal would take the cluster down over a bad API payload.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cpumanager validates the kubelet CPU-manager and node-reservation flags so a bad combination fails at startup with a clear message, rather than crash-looping the kubelet.
|
Package cpumanager validates the kubelet CPU-manager and node-reservation flags so a bad combination fails at startup with a clear message, rather than crash-looping the kubelet. |