Documentation
¶
Overview ¶
Package action are various actions used by the package
Index ¶
- Variables
- func DistroModule(id string) (distrocfg.Distro, error)
- func NewManager(ctx context.Context, opts ManagerOptions) (*phase.Manager, error)
- type Apply
- type ApplyOptions
- type EngineConfigSync
- type EngineConfigSyncOptions
- type KubeConfig
- type KubeConfigOptions
- type ManagerOptions
- type Prepare
- type PrepareOptions
- type Refresh
- type RefreshOptions
- type Reset
- type ResetOptions
Constants ¶
This section is empty.
Variables ¶
var ErrNoDistroSelected = errors.New("no distro selected: pass --distro, or set distro.type in the cargoship config file")
ErrNoDistroSelected is returned when an action is built with no distro at all, rather than with one no module claims.
Functions ¶
func DistroModule ¶ added in v0.41.1
DistroModule builds the distro module named by id.
Every action needs this and each used to inline it, which is how three of them came to drop the error on the floor and hand their caller a nil action to call a method on. Both failures belong to the lookup rather than to any one action, so they are reported here.
An empty id is reported as the missing setting it is rather than as a lookup that failed. A command invoked with no --distro, outside a directory holding a cargoship config file and with no CARGOSHIP_CONFIG set, reaches here with "", and a module-not-found error does not tell an operator what to pass.
func NewManager ¶ added in v0.41.1
NewManager resolves a package layout against a cluster inventory and builds the phase manager every action in this package takes.
The ordering here is the point of the function. Values are merged and schema-checked, then ApplyValues renders and maps the engine configuration, then RenderFiles renders the contents of the files the package marked as templates, in place in the extracted package -- and all of it happens before any phase runs. Without ApplyValues and RenderFiles an install writes a flavor whose engine config still holds raw `{{ ... }}`, which reaches the host as invalid YAML; rke2-multi-cni-cilium's HelmChartConfig did exactly that, and the CNI never installed. The resolved values are handed to the manager as well, because the `when` gate on a templated file reads Manager.Values and a nil map has no path set, so every gated file is skipped for the whole run without it.
It lived in cmd/ as an unexported helper, with a second copy in the e2e harness, which is how the two of them came to resolve values differently. It is exported because the ordering is not discoverable from the parts: each step is already an exported method on the layout, and nothing about their signatures says they must be called in this order, once, before the manager is built. The Cluster API provider is the out-of-tree caller that needs it; see docs/agent/choice-capi-provider.md.
The manager owns the extracted package at Manager.TempDirectory, which is the layout's own directory. Removing it stays with the caller, the way each command does it on the way out.
Types ¶
type Apply ¶
type Apply struct {
ApplyOptions
Phases phase.Phases
// contains filtered or unexported fields
}
Apply state logic
func (Apply) KubeConfigBytes ¶ added in v0.35.0
KubeConfigBytes is the cluster's admin credentials, serialized, as the run built them.
It is read after Run, and only means anything for a run that enabled UpdateKubeConfig: the phase is skipped otherwise and there is nothing to return. What comes back is cluster-admin, so a caller holding it is holding the cluster.
type ApplyOptions ¶
type ApplyOptions struct {
// Manager is the phase manager
Manager *phase.Manager
// AllowDowngrade continues when a host already runs a version newer than the package,
// rather than refusing the run
AllowDowngrade bool
// NoDrain skips draining worker nodes
NoDrain bool
// ModifyHosts updates the /etc/hosts file with all the nodes in the cluster
ModifyHosts bool
// ModifyFirewall updates the firewall, firewalld, ufw, or nftables, on the nodes
ModifyFirewall bool
// WorkerConcurrent number of workers that will be installed or upgraded at a time, as a fixed
// count ("5") or a percentage of the batch ("25%")
WorkerConcurrent string
// UpdateKubeConfig whether to update the config
UpdateKubeConfig bool
// KubeConfigPath is the kubeconfig file to merge the admin creds into, the standard
// location when empty
KubeConfigPath string
// NoKubeConfigFile builds the admin credentials without merging them into the operator's
// kubeconfig, so that a caller can read them through KubeConfigBytes and nothing on the
// machine running the apply is changed.
//
// It is phrased as the negative for the reason KubeConfigOptions.NoWrite is: the zero value
// writes, which is what every caller before this field existed did. The OpenTofu provider is
// the caller that sets it -- an apply that merged credentials into ~/.kube/config as a side
// effect would be changing a machine the resource does not describe.
NoKubeConfigFile bool
// LabelNodes whether to check and add the node-role.kubernetes.io/<profile> label on nodes
LabelNodes bool
// AllowUnmanagedNodes lets an apply continue when the cluster holds a node no host in the
// config accounts for, rather than stopping on it
AllowUnmanagedNodes bool
// Keyring decrypts encrypted registry credentials, in either supported format
Keyring *clustercfg.Keyring
}
ApplyOptions struct
type EngineConfigSync ¶
type EngineConfigSync struct {
EngineConfigSyncOptions
Phases phase.Phases
}
EngineConfigSync state logic
func NewEngineConfigSync ¶
func NewEngineConfigSync(opts EngineConfigSyncOptions) (*EngineConfigSync, error)
NewEngineConfigSync an engine-config-sync action object
type EngineConfigSyncOptions ¶
type EngineConfigSyncOptions struct {
// Manager is the phase manager
Manager *phase.Manager
// WorkerConcurrent number of workers that will be synced at a time, as a fixed
// count ("5") or a percentage of the batch ("25%")
WorkerConcurrent string
// Keyring decrypts encrypted registry credentials, in either supported format
Keyring *clustercfg.Keyring
// LabelNodes whether to check and add the node-role.kubernetes.io/<profile> label on nodes
LabelNodes bool
// UpdateKubeConfig whether to update a kubeconfig file with the admin creds for the cluster
UpdateKubeConfig bool
// KubeConfigPath is the kubeconfig file to merge the admin creds into, the standard
// location when empty
KubeConfigPath string
// AllowDowngrade continues when a host already runs a version newer than the package,
// rather than refusing the run
AllowDowngrade bool
}
EngineConfigSyncOptions struct
type KubeConfig ¶
type KubeConfig struct {
KubeConfigOptions
Phases phase.Phases
// contains filtered or unexported fields
}
KubeConfig state logic
func NewKubeConfig ¶
func NewKubeConfig(opts KubeConfigOptions) (*KubeConfig, error)
NewKubeConfig pulls the admin cert from a control-plane node and updates the local kube-config
func (KubeConfig) Bytes ¶ added in v0.35.0
func (a KubeConfig) Bytes() ([]byte, error)
Bytes is the kubeconfig the run built, serialized.
It is read after Run, and it is the half of this action that has nothing to do with the operator's own kubeconfig: phase.KubeConfig builds the credentials whether or not it writes them, and #305 separated the two so a caller could have the value without touching ~/.kube/config. Before this, the only way to reach it was to rebuild the phase list by hand.
What comes back is cluster-admin credentials, so a caller holding them is holding the cluster.
func (KubeConfig) Config ¶ added in v0.35.0
func (a KubeConfig) Config() *clientcmdapi.Config
Config is the same credentials as a structure, for a caller that wants to read a field rather than a file. Nil until Run has built it.
type KubeConfigOptions ¶
type KubeConfigOptions struct {
// Manager is the phase manager
Manager *phase.Manager
// KubeConfigPath is the kubeconfig file to merge the admin creds into, the standard
// location when empty
KubeConfigPath string
// NoWrite leaves the operator's kubeconfig alone, so the credentials are built and returned
// and nothing on this machine is touched.
//
// It is phrased as the negative so that the zero value writes, which is what every caller
// before this field existed did: `cargoship install kube-config` exists to write the file.
// A caller that wants the value instead reads Bytes or Config after Run; see
// docs/agent/choice-tofu-secrets.md for why the OpenTofu provider is that caller and why it
// does not expose the result unless it is asked to.
NoWrite bool
}
KubeConfigOptions struct
type ManagerOptions ¶ added in v0.41.1
type ManagerOptions struct {
// Cluster is the parsed inventory. The CLI reads it from a file through
// load.ClusterDefinition; a caller holding bytes uses cluster.Parse, and one assembling it in
// memory -- a controller building hosts from somewhere other than a YAML file -- just fills
// the struct in.
Cluster cluster.Cluster
// Layout is the extracted package, from distro.Load or distro.Build. Nil builds the manager
// reset and kube-config build, which load no package because neither installs anything;
// DistroID is then the only way to name the engine, and TempDirectory is left empty so there
// is nothing for the caller to clean up.
Layout *layout.DistroLayout
// DistroID names the engine. It is read only when Layout is nil, because a layout carries the
// authoritative answer in its own distro definition.
DistroID string
// ValueOverrides are merged after Cluster.Spec.Config.Values, in order, last wins. The CLI
// passes what --values read, so that the command line beats the inventory.
ValueOverrides []map[string]any
// Concurrency caps how many hosts a phase acts on at once, and is used for uploads too. Zero
// means unlimited; a negative value is clamped to zero rather than refused.
Concurrency int
// DryRun reaches phase.Manager.DryRun.
DryRun bool
// Timeout bounds the retry loops phases run through Manager.RetryTimeout. Zero leaves the
// manager's own default in place.
Timeout time.Duration
}
ManagerOptions are the inputs to NewManager.
type PrepareOptions ¶
type PrepareOptions struct {
// Manager is the phase manager
Manager *phase.Manager
// NoDrain skips draining worker nodes
NoDrain bool
// ModifyHosts updates the /etc/hosts file with all the nodes in the cluster
ModifyHosts bool
// ModifyFirewall updates the firewall, firewalld, ufw, or nftables, on the nodes
ModifyFirewall bool
// ModifyModules whether to update the host kernel modules
ModifyModules bool
}
PrepareOptions struct
type Refresh ¶ added in v0.35.0
type Refresh struct {
RefreshOptions
Phases phase.Phases
}
Refresh state logic
func NewRefresh ¶ added in v0.35.0
func NewRefresh(opts RefreshOptions) (*Refresh, error)
NewRefresh a refresh action object.
Refresh is the read-only half of an apply: it connects to every host the configuration names, resolves each one's OS, gathers its network facts and reads the engine version already installed on it, and disconnects. Every phase in the list declares ReadOnly(), which is the property that makes the whole action safe to run against a live fleet -- nothing is written, and no cluster lock is taken, because Lock deliberately declares neither interface.
It exists as an action rather than as a phase list each caller assembles because there is now more than one caller. The OpenTofu provider reads a fleet during a plan and during a refresh, and a provider that built its own list would be a second place where "which phases are safe to run" is decided -- which is exactly the question ReadOnly() exists to answer once. The CLI has no command for it yet; see docs/agent/design-tofu-provider-install.md.
What it leaves behind is on the hosts themselves: each phase records what it learned on the Host it ran against, so a caller reads the facts off Manager.Config.Spec.Hosts afterwards rather than out of a return value.
type RefreshOptions ¶ added in v0.35.0
RefreshOptions struct
type ResetOptions ¶
type ResetOptions struct {
// Manager is the phase manager
Manager *phase.Manager
// NoDrain skips draining worker nodes
NoDrain bool
// DistroID is the type of Kubernetes engine that will be removed
DistroID string
// WorkerConcurrent number of workers that will be installed or upgraded at a time, as a fixed
// count ("5") or a percentage of the batch ("25%")
WorkerConcurrent string
// TargetHosts names the hosts to delete and uninstall, by hostname or by the address the
// configuration connects through. Empty means every host in the configuration, which is what
// a reset has always done.
//
// The hosts not named still take part: leader selection scans the whole configuration, so a
// controller that is staying is what the node deletions are driven through. That separation is
// the whole point -- see #339.
TargetHosts []string
}
ResetOptions struct