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 CheckNetworks(cfg *types.Config) error
- func CheckSetOnce(current, next *types.Config) error
- func ClusterDNS(cfg *types.Config) (string, error)
- func Defaults() *types.Config
- func Installed(path string) *types.Config
- func KeepImmutable(cfg, from *types.Config)
- func KeepUnflagged(cfg, from *types.Config)
- func KubernetesServiceIP(serviceCIDR string) (string, error)
- func Marshal(cfg *types.Config) ([]byte, error)
- func MergePatchFor(path string, cfg *types.Config) ([]byte, error)
- func NormaliseImageRef(image string) (string, error)
- func RefuseNetworkChange(cfg *types.Config) 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 PortUse
- 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 NodeIPWarning(cfg *types.Config, ip string) (Warning, bool)
- func Parse(raw []byte, cfg *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 every closure 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 CheckNetworks ¶ added in v1.3.0
CheckNetworks refuses a start whose cluster networks differ from the ones the cluster was created with. The config API and kubesoloctl refuse the change, but the file can be edited by hand.
Until the cluster's database exists nothing was allocated from them, so they are recorded again at each start. A cluster without a record was created before they were configurable, with the defaults.
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 ClusterDNS ¶ added in v1.3.0
ClusterDNS is the cluster IP of the CoreDNS Service: the one configured, or the tenth address of the service CIDR.
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 Installed ¶ added in v1.3.0
Installed is the configuration of the install whose file is at path: the defaults, with the file over them when there is one. A file that cannot be read is passed over and the defaults stand. It is for kubesoloctl's checks, which want the ports and networks an install listens on and should not fail over a file KubeSolo itself reports on when it starts.
func KeepImmutable ¶ added in v1.3.0
KeepImmutable carries every immutable setting of from over to cfg: what a reset of the whole document must leave as it is, or be refused by its own immutability check. The immutable settings are all strings, which Set takes as they are.
func KeepUnflagged ¶ added in v1.3.0
KeepUnflagged carries over from from every setting with no flag: the ones a configuration built from flags, as the installer builds it, cannot set. The API socket, derived from path where it was not put elsewhere, moves with a new path.
func KubernetesServiceIP ¶ added in v1.3.0
KubernetesServiceIP is the cluster IP of the kubernetes Service: the first address of the service CIDR, which the API server allocates to it. The API server certificate carries 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 RefuseNetworkChange ¶ added in v1.3.0
RefuseNetworkChange is CheckNetworks without recording anything, for a configuration about to be saved.
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
// Unchangeable says why an immutable setting cannot be changed, for the
// message that refuses or warns about it. Empty for the others.
Unchangeable string
// 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. Path is: // every certificate, the kine database and all containerd state live below // it, and nothing migrates them. So are the pod and service networks: the // node's spec.podCIDR, every Service's cluster IP and the API server // certificate's kubernetes Service IP were allocated from 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 PortUse ¶ added in v1.3.0
type PortUse struct {
Port int
Name string
// ConfigPath is the setting that chooses the port, for messages.
ConfigPath string
}
PortUse is one port KubeSolo listens on, and what for.
func HostPorts ¶ added in v1.3.0
HostPorts returns the TCP ports KubeSolo listens on on the host, as cfg sets them: the ones a conflict with another process makes KubeSolo fail on. pprof is among them only when it is enabled, the metrics endpoint likewise.
kube-proxy's metrics endpoint is not: KubeSolo disables it. CoreDNS's ports are not either: they are its pod's own, not the host's.
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 NodeIPWarning ¶ added in v1.3.0
NodeIPWarning warns when ip, the node's address, is in the pod or the service network: the host's own address then collides with the cluster's, and traffic for the node can be routed into the cluster instead.
func Parse ¶ added in v1.3.0
Parse applies a configuration document onto cfg, as Read does a file: keys it does not mention are left at what cfg holds.
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. |