Documentation
¶
Overview ¶
Package profile is the engine's notion of a node profile: a named set of hardened settings an importer registers through pkg/cli.WithProfiles and a node selects by name. The engine renders what a profile declares and nothing more: apiserver flags, kubelet settings, config files written before the apiserver, secrets minted once and carried in the HA join bundle, sysctls, and a few booleans the start and the lifecycle read.
The package is a leaf. The renderers (internal/staticpod, internal/runtime, internal/host), the start (internal/cluster), the HA join and the upgrade import it, so it imports no stratum package back. A profile never names a path: a file is a name under a directory the engine owns, and a flag or a setting that needs a path says which kind of file it means.
Index ¶
- Constants
- Variables
- func EngineOwnsAPIServerFlag(name string) bool
- func EngineOwnsConfigName(name string) bool
- func EngineOwnsKubeletKey(key string) bool
- func EngineOwnsSysctl(key string) bool
- func PlainFileName(name string) error
- func Registered() []string
- func ReservedSecretName(name string) bool
- func SetRegistered(ps []Profile) error
- func SetRegistrationError(err error)
- func SharedSecretNames() []string
- type Context
- type File
- type FileKind
- type Flag
- type Locations
- type Profile
- type Secret
- type Setting
- type Source
Constants ¶
const CISEncryptionConfigName = "encryption-config.yaml"
CISEncryptionConfigName is the cis profile's at-rest encryption config, the one shared secret the engine reads by name: the join bundle derives a proof of its key from the secretbox layout the cis profile writes, and the join refuses a bundle without it on a cis cluster. Another profile's secret of that name would be minted and then fail every upload, so only the cis profile may declare it.
const CISName = "cis"
CISName is the name of the engine's own cis profile. The engine spells it in the few places that treat that profile specially (its legacy flag and state field, its sysctl drop-in) while it still ships one; they go with it.
const CISUnregisteredNote = "The cis profile is part of Stratum PRO; on a node that does not already run cis, remove --profile cis and any cis selection from the config; " + "for a node already running cis, move it onto a Stratum PRO binary with `stratum upgrade --from <binary>` (see " + ProDocsURL + ")"
CISUnregisteredNote is appended to the ErrUnregistered error Select returns for the cis profile, which this engine does not carry: the note says the profile is part of Stratum PRO and gives the two ways forward, both through flags of this binary. Tests and wrappers match this constant, never a copy of its text.
const ProDocsURL = "https://docs.ciq.com/stratum/pro/"
ProDocsURL is the Stratum PRO documentation page, which lists what the commercial edition adds. Every message that sends an operator there uses this constant, so the address is written once.
const ReservedSecretPrefix = "carotate-"
ReservedSecretPrefix starts the name of every CA-rotation state file the engine keeps in its PKI directory (carotate-forced, carotate-promoted and the rest). Those files are the rotation's state, read by their presence and removed by its cleanup, so a shared secret may not take one of their names.
Variables ¶
var ErrUnregistered = errors.New("profile is not registered in this binary")
ErrUnregistered is wrapped by Select when a name is not registered.
Functions ¶
func EngineOwnsAPIServerFlag ¶
EngineOwnsAPIServerFlag reports whether name is an apiserver flag the engine renders itself, which a profile may not declare.
func EngineOwnsConfigName ¶
EngineOwnsConfigName reports whether name is a file or directory the engine keeps in its config directory, which a profile's config file of that name would replace: one of engineConfigNames, or a payload import marker (<archive>.imported).
func EngineOwnsKubeletKey ¶
EngineOwnsKubeletKey reports whether key is a top-level kubelet.conf key the engine writes itself, which a profile may not set.
func EngineOwnsSysctl ¶
EngineOwnsSysctl reports whether key, in dotted or slashed form and with or without sysctl.d's leading "-" (apply, ignoring a failure), is one the engine sets in its own sysctl drop-in.
func PlainFileName ¶
PlainFileName reports why name is not a plain file name a profile may declare: it must be a bare name, UTF-8, with no control character, newline or backslash. The engine records the names of a profile's files one per line (the upgrade's backup record), reads them back as path elements, and a name a record cannot round-trip would make a rollback restore or remove the wrong file.
func Registered ¶
func Registered() []string
Registered returns the registered profiles' names, sorted.
func ReservedSecretName ¶
ReservedSecretName reports whether a shared secret may not be named name: it is one of the join bundle's own non-certificate entries, or "version" in any case. The legacy flat-map bundle is decoded first for a "version" field to tell it from the v1 envelope, and Go's JSON decoder matches a field name whatever its case, so a secret of that name would make the bundle undecodable.
func SetRegistered ¶
SetRegistered replaces the binary's registered profiles after validating each and refusing a name declared twice.
func SetRegistrationError ¶
func SetRegistrationError(err error)
SetRegistrationError records that registering the binary's profiles failed, so a renderer that later needs a node's profile reports why instead of rendering the node without it. Nil clears it.
func SharedSecretNames ¶
func SharedSecretNames() []string
SharedSecretNames returns the names of every registered profile's shared secrets, sorted and without repeats: the profile entries an HA join bundle may carry.
Types ¶
type Context ¶
type Context struct {
// KubernetesVersion is the version the binary runs, as vMAJOR.MINOR.PATCH
// with any pre-release suffix the stamp carries.
KubernetesVersion string
}
Context is what a profile may read when it renders a file.
type File ¶
type File struct {
// Name is the file name; no directory.
Name string
Kind FileKind
// Render returns the file's bytes.
Render func(Context) ([]byte, error)
}
File is a config file the engine writes under its config directory on a control plane before the apiserver renders, backs up across an upgrade and restores first on a rollback.
type FileKind ¶
type FileKind int
FileKind says how the engine treats a config file beyond writing it.
const ( // PlainFile is written and may be named by a ConfigFile flag. PlainFile FileKind = iota + 1 // AdmissionConfiguration is an apiserver AdmissionConfiguration the engine // merges its own admission plugins into. The engine names the merged file // on the apiserver's argv itself; the profile does not. AdmissionConfiguration )
type Flag ¶
type Flag struct {
// Name is the flag with its leading --.
Name string
// Value is the literal, or what From resolves.
Value string
From Source
}
Flag is one apiserver flag, rendered on control planes.
type Locations ¶
type Locations struct {
Config func(name string) string
Secret func(name string) string
Log func(name string) string
PKI func(name string) string
}
Locations resolves the file names a profile's flags and settings name to the paths the engine writes them at. The engine supplies it; the profile never names a path.
type Profile ¶
type Profile struct {
// Name selects the profile: a DNS-1123 label, unique in the binary.
Name string
// APIServerFlags are spliced into the apiserver's argv, in order.
APIServerFlags []Flag
// KubeletSettings are rendered into kubelet.conf, in order.
KubeletSettings []Setting
// ConfigFiles are written on control planes.
ConfigFiles []File
SharedSecrets []Secret
// Sysctls are key=value lines the engine writes as a sysctl drop-in on
// every node. A node that cannot apply them does not start.
Sysctls []string
// RequiresOperator refuses a control plane that turned the operator off.
RequiresOperator bool
// RequiresSELinux refuses spec.selinux: false and treats a missing SELinux
// policy as fatal.
RequiresSELinux bool
// KubeletServerTLSBootstrap makes every node, control planes included,
// bootstrap its kubelet serving certificate through the CSR flow.
KubeletServerTLSBootstrap bool
// DisableNodeShell turns the dashboard's privileged node shell off by
// default.
DisableNodeShell bool
}
Profile is one registered node profile.
func All ¶
func All() []Profile
All returns a copy of the registered profiles, in registration order.
func ForNode ¶
ForNode returns the profile a node's state names, for a renderer: none for an empty name, and an error for a name that is not registered or when registering the binary's profiles failed. A renderer that cannot resolve the profile stops; it never renders the node without it.
func Select ¶
Select returns the profile a node runs: none for an empty name, the registered one for a known name, and an error wrapping ErrUnregistered that names both the profile and the binary's registered ones otherwise. For the cis profile, which this engine does not carry, the error also carries CISUnregisteredNote.
func (Profile) APIServerArgs ¶
APIServerArgs is the profile's apiserver flags as argv entries, in order, with their values resolved.
func (Profile) AdmissionFile ¶
AdmissionFile returns the profile's AdmissionConfiguration file, if it declares one.
func (Profile) KubeletLines ¶
KubeletLines is the profile's kubelet settings as kubelet.conf lines, in order, with their values resolved.
func (Profile) SecretNames ¶
SecretNames returns the names of the profile's shared secrets, sorted.
type Secret ¶
type Secret struct {
// Name is the file name; no directory.
Name string
// Mint returns the bytes a new cluster starts with.
Mint func() ([]byte, error)
}
Secret is a file the engine mints once, on a cluster's first control plane, and carries to every later control plane in the HA join bundle. It is written 0600 under the engine's PKI directory and never regenerated: a node that already holds it keeps it, and a join whose bundle lacks it while the cluster's profile declares it is refused.
type Setting ¶
type Setting struct {
// Key is the kubelet.conf key.
Key string
// Value is the literal, or what From resolves.
Value string
From Source
}
Setting is one kubelet.conf line, rendered on every node.
type Source ¶
type Source int
Source says where a flag's or a setting's value comes from. The zero value is invalid on purpose: an entry that fails to say reads as undeclared.
const ( // Literal uses the entry's Value as written. Literal Source = iota + 1 // ConfigFile resolves Value, the name of one of the profile's ConfigFiles // or SharedSecrets, to the path the engine wrote it at. ConfigFile // LogFile resolves Value, a file name, to a path under the engine's log // directory. LogFile // PKIFile resolves Value, a file name, to a path under the engine's PKI // directory. PKIFile )
Directories
¶
| Path | Synopsis |
|---|---|
|
Package profiletest gives tests a hardened node profile shaped like the cis profile a Stratum PRO binary registers: an audit policy and an admission configuration as config files, an at-rest encryption config as a shared secret, kernel sysctls, and every property set.
|
Package profiletest gives tests a hardened node profile shaped like the cis profile a Stratum PRO binary registers: an audit policy and an admission configuration as config files, an at-rest encryption config as a shared secret, kernel sysctls, and every property set. |