Help us shape the future of Go! Take the 2026 Go Developer Survey

profile

package
v1.37.1-stratum.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 26, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

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

View Source
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.

View Source
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.

View Source
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.

View Source
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.

View Source
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

View Source
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

func EngineOwnsAPIServerFlag(name string) bool

EngineOwnsAPIServerFlag reports whether name is an apiserver flag the engine renders itself, which a profile may not declare.

func EngineOwnsConfigName

func EngineOwnsConfigName(name string) bool

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

func EngineOwnsKubeletKey(key string) bool

EngineOwnsKubeletKey reports whether key is a top-level kubelet.conf key the engine writes itself, which a profile may not set.

func EngineOwnsSysctl

func EngineOwnsSysctl(key string) bool

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

func PlainFileName(name string) error

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

func ReservedSecretName(name string) bool

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

func SetRegistered(ps []Profile) error

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 are minted on the first control plane and shared.
	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

func ForNode(name string) (Profile, error)

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 Lookup

func Lookup(name string) (Profile, bool)

Lookup returns the registered profile of that name.

func Select

func Select(name string) (Profile, error)

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

func (p Profile) APIServerArgs(at Locations) []string

APIServerArgs is the profile's apiserver flags as argv entries, in order, with their values resolved.

func (Profile) AdmissionFile

func (p Profile) AdmissionFile() (File, bool)

AdmissionFile returns the profile's AdmissionConfiguration file, if it declares one.

func (Profile) KubeletLines

func (p Profile) KubeletLines(at Locations) string

KubeletLines is the profile's kubelet settings as kubelet.conf lines, in order, with their values resolved.

func (Profile) None

func (p Profile) None() bool

None reports whether p is the absence of a profile.

func (Profile) SecretNames

func (p Profile) SecretNames() []string

SecretNames returns the names of the profile's shared secrets, sorted.

func (Profile) Validate

func (p Profile) Validate() error

Validate reports the first thing wrong with the profile's declaration.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL