phase

package
v0.29.0 Latest Latest
Warning

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

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

Documentation

Overview

Package phase is all the various phases used for bootstrapping a cluster. The phase files are named in a rough order used during an install; - 0x are for preconnection resources, along with ssh-ing into the node - 1x are used to gather information about the nodes in the cluster - 2x are for modifying host services, like firewalls, host files, and enabling kernel level modules - 5x are for staging files for the distro engine, e.i. rpm's, apt's, or binary files - 6x are for starting the engine or for upgrading an existing install - 8x are for resetting the engine from the nodes - 9x are last minute things and finally disconnecting from a node - ext are files that are currently not used but may be incorporated later

Index

Constants

View Source 
const (
	// FAPolicydRuleFile path on the host
	FAPolicydRuleFile = "/etc/fapolicyd/rules.d/31-cargoship.rules"
	// FAPOLICYD name of the service for fapolicyd
	FAPOLICYD = "fapolicyd"
)
View Source 
const (
	// FIREWALLD name of the service for firewalld
	FIREWALLD = firewall.FirewalldService
	// UFW name of the service for ufw
	UFW = firewall.UFWService
)
View Source 
const (
	// ContainerSELinux package name
	ContainerSELinux = "container-selinux"
)
View Source 
const (
	// UnknownVersion for when the version is not set
	UnknownVersion = "v0.0.0"
)

Variables

View Source 
var ErrNoControllers = errors.New("no controllers are running")

ErrNoControllers an error for when no controllers are running

View Source 
var ErrNoKubeConfig = errors.New("kubeconfig has not been built")

ErrNoKubeConfig is returned when the config is asked for before the phase has run

View Source 
var ErrUnmanagedNodes = errors.New("the cluster holds nodes the config does not: add the host back to the config, run `cargoship install reset` against it, or pass --allow-unmanaged-nodes to apply anyway")

ErrUnmanagedNodes is returned when the cluster holds a node no host in the config accounts for. Apply removes nothing, so continuing would report success over a machine that is still running the engine and still joined.

View Source 
var Force bool

Force is used by various phases to attempt a forced installation

View Source 
var (
	// Interval is the time to wait between retry attempts
	Interval = 10 * time.Second
)
View Source 
var NoWait bool

NoWait is used by various phases to decide if node ready state should be waited for or not

Functions

func DryRunNote 

func DryRunNote(p Phase) string

DryRunNote returns the phase's own account of why a dry run runs it, or "" for a phase that gives none. Only read-only phases carry one: they are the phases a dry run runs against live hosts, so they are the ones a reader is entitled to an argument about.

func Titles 

func Titles(results []PhaseResult) []string

Titles names the phases in a slice, for a caller that reports a list of names rather than the detail behind them.

Types

type APTUploadFiles 

type APTUploadFiles struct {
	UploadFilesCommon
}

APTUploadFiles implements a phase which upload files to hosts

func (*APTUploadFiles) Explanation 

func (p *APTUploadFiles) Explanation() string

Explanation about the current phase, used for documentation generation

func (*APTUploadFiles) Prepare 

func (p *APTUploadFiles) Prepare(ctx context.Context, c *cluster.ZarfCluster, d *distro.ZarfDistro) error

Prepare the phase

func (*APTUploadFiles) Run 

func (p *APTUploadFiles) Run(ctx context.Context) (err error)

Run the phase

func (*APTUploadFiles) Title 

func (p *APTUploadFiles) Title() string

Title for the phase

type BINUploadFiles 

type BINUploadFiles struct {
	UploadFilesCommon
	Distro distrocfg.Distro
}

BINUploadFiles implements a phase which upload files to hosts

func (*BINUploadFiles) Explanation 

func (p *BINUploadFiles) Explanation() string

Explanation about the current phase, used for documentation generation

func (*BINUploadFiles) Prepare 

func (p *BINUploadFiles) Prepare(ctx context.Context, c *cluster.ZarfCluster, d *distro.ZarfDistro) error

Prepare the phase

func (*BINUploadFiles) Run 

func (p *BINUploadFiles) Run(ctx context.Context) (err error)

Run the phase

func (*BINUploadFiles) Title 

func (p *BINUploadFiles) Title() string

Title for the phase

type ConfigureEngine 

type ConfigureEngine struct {
	GenericPhase
	Distro distrocfg.Distro
	// Keyring decrypts encrypted registry credentials, in either supported format. If it holds
	// nothing that reads a given value, Prepare errors.
	Keyring *clustercfg.Keyring
	// contains filtered or unexported fields
}

ConfigureEngine writes the engine configuration to host engine config dir

func (*ConfigureEngine) Explanation 

func (p *ConfigureEngine) Explanation() string

Explanation about the current phase, used for documentation generation

func (*ConfigureEngine) Prepare 

func (p *ConfigureEngine) Prepare(ctx context.Context, c *cluster.ZarfCluster, d *distro.ZarfDistro) error

Prepare the phase

func (*ConfigureEngine) Run 

func (p *ConfigureEngine) Run(ctx context.Context) error

Run the phase title

func (*ConfigureEngine) Title 

func (p *ConfigureEngine) Title() string

Title returns the phase title

type ConfigureFirewall 

type ConfigureFirewall struct {
	GenericPhase
	Distro  distrocfg.Distro
	Enabled bool
	// contains filtered or unexported fields
}

ConfigureFirewall state

func (*ConfigureFirewall) Explanation 

func (p *ConfigureFirewall) Explanation() string

Explanation about the current phase, used for documentation generation

func (*ConfigureFirewall) Prepare 

func (p *ConfigureFirewall) Prepare(ctx context.Context, _ *cluster.ZarfCluster, _ *distro.ZarfDistro) error

Prepare the phase

func (*ConfigureFirewall) Run 

func (p *ConfigureFirewall) Run(ctx context.Context) error

Run the phase

func (*ConfigureFirewall) ShouldRun 

func (p *ConfigureFirewall) ShouldRun() bool

ShouldRun is true when the firewall is being managed and at least one node runs one

func (*ConfigureFirewall) Title 

func (p *ConfigureFirewall) Title() string

Title for the phase

type Connect 

type Connect struct {
	GenericPhase
}

Connect connects to each of the hosts

func (*Connect) Explanation 

func (p *Connect) Explanation() string

Explanation about the current phase, used for documentation generation

func (*Connect) ReadOnly 

func (p *Connect) ReadOnly() string

ReadOnly marks this phase safe under a dry run, and returns the reason for the phase docs.

func (*Connect) Run 

func (p *Connect) Run(ctx context.Context) error

Run the phase

func (*Connect) Title 

func (p *Connect) Title() string

Title for the phase

type DaemonReload 

type DaemonReload struct {
	GenericPhase
}

DaemonReload phase runs `systemctl daemon-reload` or equivalent on all hosts.

func (*DaemonReload) Explanation 

func (p *DaemonReload) Explanation() string

Explanation about the current phase, used for documentation generation

func (*DaemonReload) Run 

func (p *DaemonReload) Run(ctx context.Context) error

Run the phase

func (*DaemonReload) ShouldRun 

func (p *DaemonReload) ShouldRun() bool

ShouldRun is true when there are controllers that needs to be reset

func (*DaemonReload) Title 

func (p *DaemonReload) Title() string

Title for the phase

type DeleteCommon 

type DeleteCommon struct {
	GenericPhase
	Distro distrocfg.Distro
	// contains filtered or unexported fields
}

DeleteCommon phase state

func (*DeleteCommon) Prepare 

func (p *DeleteCommon) Prepare(ctx context.Context, _ *cluster.ZarfCluster, _ *distro.ZarfDistro) error

Prepare the phase

type DeleteControllers 

type DeleteControllers struct {
	DeleteCommon
	NoDrain bool
	// contains filtered or unexported fields
}

DeleteControllers phase state

func (*DeleteControllers) Explanation 

func (p *DeleteControllers) Explanation() string

Explanation about the current phase, used for documentation generation

func (*DeleteControllers) Prepare 

func (p *DeleteControllers) Prepare(ctx context.Context, c *cluster.ZarfCluster, d *distro.ZarfDistro) error

Prepare the phase

func (*DeleteControllers) Run 

func (p *DeleteControllers) Run(ctx context.Context) error

Run the phase

func (*DeleteControllers) ShouldRun 

func (p *DeleteControllers) ShouldRun() bool

ShouldRun is true when this phase is enabled

func (*DeleteControllers) Title 

func (p *DeleteControllers) Title() string

Title for the phase

type DeleteWorkers 

type DeleteWorkers struct {
	DeleteCommon
	NoDrain          bool
	WorkerConcurrent string
	// contains filtered or unexported fields
}

DeleteWorkers phase state

func (*DeleteWorkers) Explanation 

func (p *DeleteWorkers) Explanation() string

Explanation about the current phase, used for documentation generation

func (*DeleteWorkers) Prepare 

func (p *DeleteWorkers) Prepare(ctx context.Context, c *cluster.ZarfCluster, d *distro.ZarfDistro) error

Prepare the phase

func (*DeleteWorkers) Run 

func (p *DeleteWorkers) Run(ctx context.Context) error

Run the phase

func (*DeleteWorkers) ShouldRun 

func (p *DeleteWorkers) ShouldRun() bool

ShouldRun is true when this phase is enabled

func (*DeleteWorkers) Title 

func (p *DeleteWorkers) Title() string

Title for the phase

type DetectOS 

type DetectOS struct {
	GenericPhase
}

DetectOS performs remote OS detection

func (*DetectOS) Explanation 

func (p *DetectOS) Explanation() string

Explanation about the current phase, used for documentation generation

func (*DetectOS) ReadOnly 

func (p *DetectOS) ReadOnly() string

ReadOnly marks this phase safe under a dry run, and returns the reason for the phase docs.

func (*DetectOS) Run 

func (p *DetectOS) Run(ctx context.Context) error

Run the phase

func (*DetectOS) Title 

func (p *DetectOS) Title() string

Title for the phase

type DetectRemovedHosts 

type DetectRemovedHosts struct {
	GenericPhase
	Distro distrocfg.Distro
	// AllowUnmanaged downgrades the refusal to a warning. A cluster can hold nodes cargoship
	// never joined, and refusing on those would block every apply on a working setup, so the
	// operator needs a way to say the extra nodes are deliberate.
	AllowUnmanaged bool
	// contains filtered or unexported fields
}

DetectRemovedHosts state.

Apply drives the cluster towards the config, but only ever forwards: every phase after this one reads Spec.Hosts and acts on what it finds there. A host deleted from the config is therefore invisible to all of them, and the machine keeps running the engine and stays joined to the cluster while apply reports success. This phase is what stops that from being silent.

It detects and refuses. It does not reconcile, and the reason is not effort: apply cannot reach the machine it would have to clean up. Draining a node and deleting its Node object needs only the name, which the API gives us. Uninstalling the engine needs an SSH connection, and the address, user and key for that lived in the host block that was just deleted. Deleting the Node object without the uninstall is worse than doing nothing, because it looks like the removal worked while the machine keeps its certificates and tries to rejoin -- and for a controller it stays an etcd member, so the quorum arithmetic silently moves against a member nobody can reach.

The layer that does hold the connection details for a removed host is the OpenTofu provider, which still has the old host block in its state file when it plans the destroy. That is where a real removal path belongs, and it can call reset against exactly that host. Until then this phase makes the gap loud instead of invisible.

func (*DetectRemovedHosts) Explanation 

func (p *DetectRemovedHosts) Explanation() string

Explanation about the current phase, used for documentation generation

func (*DetectRemovedHosts) Prepare 

func (p *DetectRemovedHosts) Prepare(ctx context.Context, _ *cluster.ZarfCluster, _ *distro.ZarfDistro) error

Prepare the phase.

The leader is any host in the config already running the controller service, which is the same way the label and delete phases find one. Nothing is running on a first install, so there is no leader, and ShouldRun turns the phase off: a cluster that does not exist yet cannot have had a host removed from it.

func (*DetectRemovedHosts) ReadOnly 

func (p *DetectRemovedHosts) ReadOnly() string

ReadOnly marks this phase safe under a dry run, and returns the reason for the phase docs.

func (*DetectRemovedHosts) Run 

func (p *DetectRemovedHosts) Run(ctx context.Context) error

Run the phase.

Only positive evidence stops the apply. Failing to reach the cluster says nothing about whether a host was removed, and this phase runs before every phase that does the real work, so treating an unreachable cluster as a refusal would turn a transient failure into a failed apply that had nothing to do with removals. Those cases warn and continue.

func (*DetectRemovedHosts) ShouldRun 

func (p *DetectRemovedHosts) ShouldRun() bool

ShouldRun is true once there is a running controller to ask

func (*DetectRemovedHosts) Title 

func (p *DetectRemovedHosts) Title() string

Title for the phase

type Disconnect 

type Disconnect struct {
	GenericPhase
}

Disconnect disconnects from the hosts

func (*Disconnect) DryRun 

func (p *Disconnect) DryRun() error

DryRun cleans up the temporary binary from the hosts

func (*Disconnect) Explanation 

func (p *Disconnect) Explanation() string

Explanation about the current phase, used for documentation generation

func (*Disconnect) Run 

func (p *Disconnect) Run(ctx context.Context) error

Run the phase

func (*Disconnect) Title 

func (p *Disconnect) Title() string

Title for the phase

type DryRunBehavior 

type DryRunBehavior int

DryRunBehavior is what a dry run does with a phase. It is derived from the interfaces the phase implements, and it is exported so magefiles/pkg/gen/docs/phase.go can label each phase in docs/phases/<name>.md with the same classification Run() gates on. The docs and the gate cannot disagree, because there is only one classifier. 

const (
	// DryRunSkip is the default: the phase declares nothing, so a dry run reports it and
	// does not run it.
	DryRunSkip DryRunBehavior = iota
	// DryRunReadOnly is a phase implementing readOnly. It reads hosts and changes nothing,
	// so a dry run runs it as itself.
	DryRunReadOnly
	// DryRunOwnPath is a phase implementing withDryRun. A dry run calls DryRun() instead of
	// Run().
	DryRunOwnPath
)

func ClassifyDryRun 

func ClassifyDryRun(p Phase) DryRunBehavior

ClassifyDryRun reports what a dry run does with p.

func (DryRunBehavior) String 

func (b DryRunBehavior) String() string

String is the label written into the phase docs.

type EngineConfigSyncController 

type EngineConfigSyncController struct {
	EngineConfigSyncHosts
}

EngineConfigSyncController phase state

func (*EngineConfigSyncController) Explanation 

func (p *EngineConfigSyncController) Explanation() string

Explanation about the current phase, used for documentation generation

func (*EngineConfigSyncController) Prepare 

func (p *EngineConfigSyncController) Prepare(ctx context.Context, c *cluster.ZarfCluster, d *distro.ZarfDistro) error

Prepare the phase

func (*EngineConfigSyncController) Run 

func (p *EngineConfigSyncController) Run(ctx context.Context) error

Run the phase

func (*EngineConfigSyncController) Title 

func (p *EngineConfigSyncController) Title() string

Title for the phase

type EngineConfigSyncHosts 

type EngineConfigSyncHosts struct {
	GenericPhase
	Distro distrocfg.Distro
	// Keyring decrypts encrypted registry credentials, in either supported format.
	Keyring *clustercfg.Keyring
	// contains filtered or unexported fields
}

EngineConfigSyncHosts phase state

func (*EngineConfigSyncHosts) Changed 

func (p *EngineConfigSyncHosts) Changed() bool

Changed reports whether this phase altered any host, which is what Ansible's changed is built from. See changedReporter in 05_manager.go.

There are two ways this phase changes a host and both count. The obvious one is the sync itself. The other is the file a host carries that the engine re-reads without a restart: that is written while Prepare is deciding which hosts have drifted, and the host is then not listed as needing a sync, so a run that changed only those files would otherwise read as a run that did nothing.

func (*EngineConfigSyncHosts) ShouldRun 

func (p *EngineConfigSyncHosts) ShouldRun() bool

ShouldRun is true when there are hosts to sync

type EngineConfigSyncWorker 

type EngineConfigSyncWorker struct {
	EngineConfigSyncHosts
	WorkerConcurrent string
}

EngineConfigSyncWorker phase state

func (*EngineConfigSyncWorker) Explanation 

func (p *EngineConfigSyncWorker) Explanation() string

Explanation about the current phase, used for documentation generation

func (*EngineConfigSyncWorker) Prepare 

func (p *EngineConfigSyncWorker) Prepare(ctx context.Context, c *cluster.ZarfCluster, d *distro.ZarfDistro) error

Prepare the phase

func (*EngineConfigSyncWorker) Run 

func (p *EngineConfigSyncWorker) Run(ctx context.Context) error

Run the phase

func (*EngineConfigSyncWorker) Title 

func (p *EngineConfigSyncWorker) Title() string

Title for the phase

type GatherFacts 

type GatherFacts struct {
	GenericPhase
	// contains filtered or unexported fields
}

GatherFacts gathers information about hosts

func (*GatherFacts) Explanation 

func (p *GatherFacts) Explanation() string

Explanation about the current phase, used for documentation generation

func (*GatherFacts) ReadOnly 

func (p *GatherFacts) ReadOnly() string

ReadOnly marks this phase safe under a dry run, and returns the reason for the phase docs.

func (*GatherFacts) Run 

func (p *GatherFacts) Run(ctx context.Context) error

Run the phase

func (*GatherFacts) Title 

func (p *GatherFacts) Title() string

Title for the phase

type GatherFactsDistro 

type GatherFactsDistro struct {
	GenericPhase
	Distro distrocfg.Distro
	// contains filtered or unexported fields
}

GatherFactsDistro state

func (*GatherFactsDistro) Explanation 

func (p *GatherFactsDistro) Explanation() string

Explanation about the current phase, used for documentation generation

func (*GatherFactsDistro) Prepare 

func (p *GatherFactsDistro) Prepare(_ context.Context, _ *cluster.ZarfCluster, d *distro.ZarfDistro) error

Prepare the phase

func (*GatherFactsDistro) ReadOnly 

func (p *GatherFactsDistro) ReadOnly() string

ReadOnly marks this phase safe under a dry run, and returns the reason for the phase docs.

func (*GatherFactsDistro) Run 

func (p *GatherFactsDistro) Run(ctx context.Context) (err error)

Run the phase

func (*GatherFactsDistro) Title 

func (p *GatherFactsDistro) Title() string

Title for the phase

type GenericPhase 

type GenericPhase struct {
	// contains filtered or unexported fields
}

GenericPhase state

func (*GenericPhase) GetConfig 

func (p *GenericPhase) GetConfig() *cluster.ZarfCluster

GetConfig is an accessor to phase Config

func (*GenericPhase) GetDistro 

func (p *GenericPhase) GetDistro() *distro.ZarfDistro

GetDistro is an accessor to phase Distro

func (*GenericPhase) Prepare 

func (p *GenericPhase) Prepare(c *cluster.ZarfCluster, d *distro.ZarfDistro) error

Prepare the phase

func (*GenericPhase) SetManager 

func (p *GenericPhase) SetManager(m *Manager)

SetManager adds a reference to the phase manager

func (*GenericPhase) VersionGreater 

func (p *GenericPhase) VersionGreater(host *cluster.ZarfHost, version string) bool

VersionGreater if host version is greater then the distro version

func (*GenericPhase) VersionLess 

func (p *GenericPhase) VersionLess(host *cluster.ZarfHost, version string) bool

VersionLess if host version is less then the distro version

func (*GenericPhase) Wet 

func (p *GenericPhase) Wet(host fmt.Stringer, msg string, funcs ...errorfunc) error

Wet is a shorthand for manager.Wet

type ImportImages added in v0.29.0 

type ImportImages struct {
	GenericPhase
	Distro distrocfg.Distro
	// contains filtered or unexported fields
}

ImportImages imports uploaded image tarballs into a distro's engine, for a distro whose engine does not do this on its own. rke2 and k3s's own agents import automatically, so most applies skip this phase entirely -- ShouldRun is false unless the distro opts in.

func (*ImportImages) Explanation added in v0.29.0 

func (p *ImportImages) Explanation() string

Explanation about the current phase, used for documentation generation

func (*ImportImages) Prepare added in v0.29.0 

func (p *ImportImages) Prepare(ctx context.Context, c *cluster.ZarfCluster, d *distro.ZarfDistro) error

Prepare the phase

func (*ImportImages) Run added in v0.29.0 

func (p *ImportImages) Run(ctx context.Context) error

Run the phase

func (*ImportImages) ShouldRun added in v0.29.0 

func (p *ImportImages) ShouldRun() bool

ShouldRun is true when the distro needs images imported for it and there is somewhere to import them from.

func (*ImportImages) Title added in v0.29.0 

func (p *ImportImages) Title() string

Title for the phase

type InitializeControllers 

type InitializeControllers struct {
	GenericPhase
	Distro distrocfg.Distro
	// contains filtered or unexported fields
}

InitializeControllers phase state

func (*InitializeControllers) Explanation 

func (p *InitializeControllers) Explanation() string

Explanation about the current phase, used for documentation generation

func (*InitializeControllers) Prepare 

func (p *InitializeControllers) Prepare(ctx context.Context, _ *cluster.ZarfCluster, _ *distro.ZarfDistro) error

Prepare the phase

func (*InitializeControllers) Run 

func (p *InitializeControllers) Run(ctx context.Context) error

Run the phase

func (*InitializeControllers) ShouldRun 

func (p *InitializeControllers) ShouldRun() bool

ShouldRun is true when there are workers

func (*InitializeControllers) Title 

func (p *InitializeControllers) Title() string

Title for the phase

type InitializeWorkers 

type InitializeWorkers struct {
	GenericPhase
	Distro distrocfg.Distro

	WorkerConcurrent string
	// contains filtered or unexported fields
}

InitializeWorkers phase state

func (*InitializeWorkers) Explanation 

func (p *InitializeWorkers) Explanation() string

Explanation about the current phase, used for documentation generation

func (*InitializeWorkers) Prepare 

func (p *InitializeWorkers) Prepare(ctx context.Context, _ *cluster.ZarfCluster, _ *distro.ZarfDistro) error

Prepare the phase

func (*InitializeWorkers) Run 

func (p *InitializeWorkers) Run(ctx context.Context) error

Run the phase

func (*InitializeWorkers) ShouldRun 

func (p *InitializeWorkers) ShouldRun() bool

ShouldRun is true when there are workers

func (*InitializeWorkers) Title 

func (p *InitializeWorkers) Title() string

Title for the phase

type KubeConfig 

type KubeConfig struct {
	GenericPhase
	Distro    distrocfg.Distro
	ClusterID string
	ClusterLB string
	Enabled   bool
	// Write merges the config into the operator's local kubeconfig once it is built. The
	// CLI sets it. A caller that only wants the value -- a provider holding it as an
	// attribute, say -- leaves it false and reads Config after the run, so nobody's
	// ~/.kube/config is touched as a side effect.
	Write bool
	// Path is the kubeconfig file Write merges into. Empty means the standard location:
	// KUBECONFIG when set, otherwise ~/.kube/config. A path that does not exist is created,
	// and one that does keeps every cluster already in it.
	Path string
	// contains filtered or unexported fields
}

KubeConfig phase state

func (*KubeConfig) Bytes 

func (p *KubeConfig) Bytes() ([]byte, error)

Bytes is Config serialized as a kubeconfig file, which is the form a caller storing it elsewhere wants.

func (*KubeConfig) Config 

func (p *KubeConfig) Config() *clientcmdapi.Config

Config is the kubeconfig for this cluster, built during Run from the admin credentials on the leader. It is nil until the phase has run.

func (*KubeConfig) Explanation 

func (p *KubeConfig) Explanation() string

Explanation about the current phase, used for documentation generation

func (*KubeConfig) Prepare 

func (p *KubeConfig) Prepare(ctx context.Context, c *cluster.ZarfCluster, _ *distro.ZarfDistro) error

Prepare the phase

func (*KubeConfig) Run 

func (p *KubeConfig) Run(_ context.Context) error

Run the phase

func (*KubeConfig) ShouldRun 

func (p *KubeConfig) ShouldRun() bool

ShouldRun is true when enabled by flags

func (*KubeConfig) Title 

func (p *KubeConfig) Title() string

Title for the phase

type LabelNodes 

type LabelNodes struct {
	GenericPhase
	Distro    distrocfg.Distro
	ClusterLB string
	Enabled   bool
	// contains filtered or unexported fields
}

LabelNodes phase state

func (*LabelNodes) Explanation 

func (p *LabelNodes) Explanation() string

Explanation about the current phase, used for documentation generation

func (*LabelNodes) Prepare 

func (p *LabelNodes) Prepare(ctx context.Context, c *cluster.ZarfCluster, _ *distro.ZarfDistro) error

Prepare the phase

func (*LabelNodes) Run 

func (p *LabelNodes) Run(ctx context.Context) error

Run the phase

func (*LabelNodes) ShouldRun 

func (p *LabelNodes) ShouldRun() bool

ShouldRun is true when enabled by flags

func (*LabelNodes) Title 

func (p *LabelNodes) Title() string

Title for the phase

type Lock 

type Lock struct {
	GenericPhase
	// contains filtered or unexported fields
}

Lock phase state

func (*Lock) Cancel 

func (p *Lock) Cancel(_ context.Context)

Cancel releases the lock

func (*Lock) CleanUp 

func (p *Lock) CleanUp()

CleanUp calls Cancel to release the lock

func (*Lock) Explanation 

func (p *Lock) Explanation() string

Explanation about the current phase, used for documentation generation

func (*Lock) Prepare 

func (p *Lock) Prepare(ctx context.Context, c *cluster.ZarfCluster, _ *distro.ZarfDistro) error

Prepare the phase

func (*Lock) Run 

func (p *Lock) Run(ctx context.Context) error

Run the phase

func (*Lock) Title 

func (p *Lock) Title() string

Title for the phase

func (*Lock) UnlockPhase 

func (p *Lock) UnlockPhase() Phase

UnlockPhase returns an unlock phase for this lock phase

type Manager 

type Manager struct {
	Config *cluster.ZarfCluster
	Distro *distro.ZarfDistro
	// Values is the configuration the package ships with, merged with the
	// overrides in the cluster inventory and checked against the package's
	// values schema. Phases read it instead of re-reading either source, so
	// every phase sees the same values.
	Values            map[string]any
	DistroID          string
	Concurrency       int
	ConcurrentUploads int
	DryRun            bool
	Writer            io.Writer
	TempDirectory     string
	Timeout           time.Duration
	// Result is what the last Run did, phase by phase. Run fills it in whether it succeeded or
	// failed, so a caller reading it after an error sees the phases the run got through. It is
	// a field rather than a return value because Run has five call sites and one caller that
	// wants this.
	Result RunResult
	// contains filtered or unexported fields
}

Manager executes phases to construct the cluster

func NewManager 

func NewManager(config *cluster.ZarfCluster, distro distrocfg.Distro) (*Manager, error)

NewManager creates a new Manager

func (*Manager) AddPhase 

func (m *Manager) AddPhase(p ...Phase)

AddPhase adds a Phase to Manager

func (*Manager) GetDistroOSFiles 

func (m *Manager) GetDistroOSFiles() v1alpha1.ZarfFiles

GetDistroOSFiles returns the ZarfFiles for a distro

func (*Manager) RetryTimeout 

func (m *Manager) RetryTimeout(ctx context.Context, f func(ctx context.Context) error) error

RetryTimeout wraps retry Timeout logic

func (*Manager) Run 

func (m *Manager) Run(ctx context.Context) error

Run executes all the added Phases in order

func (*Manager) SetPhases 

func (m *Manager) SetPhases(p Phases)

SetPhases sets the list of phases

func (*Manager) SetTimeout added in v0.29.0 

func (m *Manager) SetTimeout(tm time.Duration)

SetTimeout sets the timeout for the manager

func (*Manager) Wet 

func (m *Manager) Wet(_ fmt.Stringer, _ string, funcs ...errorfunc) error

Wet runs the first given function when not in dry-run mode. The second function will be run when in dry-mode and the message will be displayed. Any error returned from the functions will be returned and will halt the operation.

type ManagerDistroConfig 

type ManagerDistroConfig struct {
	BinaryDir string
	Binary    string
	Config    string
	Token     string
	Data      string
	Version   string
}

ManagerDistroConfig stores some values for manager distro config

type ManifestEntry 

type ManifestEntry struct {
	// Category labels why the file was uploaded, e.g. "engine", "image", "file", "data".
	Category string
	// Path is the absolute path of the file on the remote host.
	Path string
}

ManifestEntry is a single file cargoship uploaded to a host, recorded so it can be found and removed later during an upgrade or uninstall.

func ParseManifest 

func ParseManifest(content string) []ManifestEntry

ParseManifest reads manifest file content back into entries. Malformed lines are skipped.

type ModifyHosts 

type ModifyHosts struct {
	GenericPhase
	Enabled bool
	// contains filtered or unexported fields
}

ModifyHosts state

func (*ModifyHosts) Explanation 

func (p *ModifyHosts) Explanation() string

Explanation about the current phase, used for documentation generation

func (*ModifyHosts) Prepare 

func (p *ModifyHosts) Prepare(ctx context.Context, _ *cluster.ZarfCluster, _ *distro.ZarfDistro) error

Prepare the phase

func (*ModifyHosts) Run 

func (p *ModifyHosts) Run(ctx context.Context) error

Run the phase

func (*ModifyHosts) ShouldRun 

func (p *ModifyHosts) ShouldRun() bool

ShouldRun is true when this phase is enabled

func (*ModifyHosts) Title 

func (p *ModifyHosts) Title() string

Title for the phase

type Phase 

type Phase interface {
	Run(context.Context) error
	Title() string
	Explanation() string
}

Phase represents a runnable phase which can be added to Manager.

type PhaseResult 

type PhaseResult struct {
	Title       string
	Explanation string
	// DryRun is what a dry run does with this phase, whether or not this run was one.
	DryRun DryRunBehavior
	// Declared is whether the phase implements changedReporter. When it is false, Changed is
	// false because nothing was asked, not because nothing happened.
	Declared bool
	Changed  bool
}

PhaseResult is what a single phase did during a run.

type Phases 

type Phases []Phase

Phases is a slice of Phases

func (Phases) Index 

func (p Phases) Index(title string) int

Index returns the index of the first occurrence matching the given phase title or -1 if not found

func (*Phases) InsertAfter 

func (p *Phases) InsertAfter(title string, phase Phase)

InsertAfter inserts a phase after the first occurrence of a phase with the given title

func (*Phases) InsertBefore 

func (p *Phases) InsertBefore(title string, phase Phase)

InsertBefore inserts a phase before the first occurrence of a phase with the given title

func (*Phases) Replace 

func (p *Phases) Replace(title string, phase Phase)

Replace replaces the first occurrence of a phase with the given title

type PrepareFapolicy 

type PrepareFapolicy struct {
	GenericPhase
	// contains filtered or unexported fields
}

PrepareFapolicy installs required packages and so on on the hosts.

func (*PrepareFapolicy) Explanation 

func (p *PrepareFapolicy) Explanation() string

Explanation about the current phase, used for documentation generation

func (*PrepareFapolicy) Prepare 

func (p *PrepareFapolicy) Prepare(ctx context.Context, _ *cluster.ZarfCluster, _ *distro.ZarfDistro) error

Prepare the phase

func (*PrepareFapolicy) Run 

func (p *PrepareFapolicy) Run(ctx context.Context) error

Run the phase

func (*PrepareFapolicy) ShouldRun 

func (p *PrepareFapolicy) ShouldRun() bool

ShouldRun is true when there is a host with selinux or fapolicyd on the hosts

func (*PrepareFapolicy) Title 

func (p *PrepareFapolicy) Title() string

Title for the phase

type PrepareHosts 

type PrepareHosts struct {
	GenericPhase
	// contains filtered or unexported fields
}

PrepareHosts installs required packages and so on on the hosts.

func (*PrepareHosts) Explanation 

func (p *PrepareHosts) Explanation() string

Explanation about the current phase, used for documentation generation

func (*PrepareHosts) Prepare 

func (p *PrepareHosts) Prepare(_ context.Context, _ *cluster.ZarfCluster, d *distro.ZarfDistro) error

Prepare the phase

func (*PrepareHosts) Run 

func (p *PrepareHosts) Run(ctx context.Context) error

Run the phase

func (*PrepareHosts) Title 

func (p *PrepareHosts) Title() string

Title for the phase

type PrepareKernelModules 

type PrepareKernelModules struct {
	GenericPhase
	Enabled bool
	// contains filtered or unexported fields
}

PrepareKernelModules enables the list of requested modules on the host, then reboots the box if modules are added

func (*PrepareKernelModules) Explanation 

func (p *PrepareKernelModules) Explanation() string

Explanation about the current phase, used for documentation generation

func (*PrepareKernelModules) Prepare 

func (p *PrepareKernelModules) Prepare(_ context.Context, _ *cluster.ZarfCluster, _ *distro.ZarfDistro) error

Prepare the phase

func (*PrepareKernelModules) Run 

func (p *PrepareKernelModules) Run(ctx context.Context) error

Run the phase

func (*PrepareKernelModules) ShouldRun 

func (p *PrepareKernelModules) ShouldRun() bool

ShouldRun is true when we need to enable kernel modules

func (*PrepareKernelModules) Title 

func (p *PrepareKernelModules) Title() string

Title for the phase

type PrepareSelinux 

type PrepareSelinux struct {
	GenericPhase
	// contains filtered or unexported fields
}

PrepareSelinux installs required packages and so on on the hosts.

func (*PrepareSelinux) Explanation 

func (p *PrepareSelinux) Explanation() string

Explanation about the current phase, used for documentation generation

func (*PrepareSelinux) Prepare 

func (p *PrepareSelinux) Prepare(ctx context.Context, _ *cluster.ZarfCluster, _ *distro.ZarfDistro) error

Prepare the phase

func (*PrepareSelinux) Run 

func (p *PrepareSelinux) Run(ctx context.Context) error

Run the phase

func (*PrepareSelinux) ShouldRun 

func (p *PrepareSelinux) ShouldRun() bool

ShouldRun is true when there is a host with selinux on the hosts

func (*PrepareSelinux) Title 

func (p *PrepareSelinux) Title() string

Title for the phase

type RPMUploadFiles 

type RPMUploadFiles struct {
	UploadFilesCommon
}

RPMUploadFiles implements a phase which upload files to hosts

func (*RPMUploadFiles) Explanation 

func (p *RPMUploadFiles) Explanation() string

Explanation about the current phase, used for documentation generation

func (*RPMUploadFiles) Prepare 

func (p *RPMUploadFiles) Prepare(ctx context.Context, c *cluster.ZarfCluster, d *distro.ZarfDistro) error

Prepare the phase

func (*RPMUploadFiles) Run 

func (p *RPMUploadFiles) Run(ctx context.Context) (err error)

Run the phase

func (*RPMUploadFiles) Title 

func (p *RPMUploadFiles) Title() string

Title for the phase

type ResultSink 

type ResultSink struct {
	// contains filtered or unexported fields
}

ResultSink collects the RunResult of every Manager.Run that happens on a context.

It exists because the Ansible module mode runs cargoship by building an argument vector and calling the ordinary command, which returns an error and nothing else -- see src/cmd.ExecuteArgs. Threading a return value back through cobra, the action and the manager would change five call sites to serve one caller. A sink on the context that nobody else installs does not, and a run with no sink on its context pays nothing for this.

func WithResultSink 

func WithResultSink(ctx context.Context) (context.Context, *ResultSink)

WithResultSink returns a context carrying a sink, and the sink itself.

func (*ResultSink) Observed 

func (s *ResultSink) Observed() bool

Observed reports whether any run reached its phases at all. A command that failed before that -- an unreadable package, a configuration that does not validate -- publishes nothing, and that is a different thing from a run in which no phase changed anything.

func (*ResultSink) Result 

func (s *ResultSink) Result() RunResult

Result is every run that reached its phases on this context, flattened into one.

type RunResult 

type RunResult struct {
	// Ran are the phases that executed, in order. That includes the read-only phases a dry run
	// runs as themselves and the phases that took their own dry-run path. Running is not
	// changing: Connect, DetectOS, GatherFacts and ValidateHosts all land here and change
	// nothing, which is why Changed is asked separately.
	Ran []PhaseResult
	// Planned are the phases a dry run reported instead of running.
	Planned []PhaseResult
	// Skipped are the phases ShouldRun filtered out. They are kept because a phase can finish
	// its work in Prepare and then have nothing left to run: EngineConfigSyncHosts writes the
	// files the engine re-reads without a restart while it is deciding which hosts have
	// drifted, and then reports no hosts to sync.
	Skipped []PhaseResult
}

RunResult is what a whole Manager.Run did, phase by phase. Manager.Run fills it in on the way through, so a run that returned an error still carries the phases it got through first.

func (RunResult) Changed 

func (r RunResult) Changed() bool

Changed reports whether any phase said it changed something on the fleet. Phases that declared nothing do not contribute; read Complete to find out whether that leaves the answer partial.

func (RunResult) Complete 

func (r RunResult) Complete() bool

Complete reports whether every phase the run reached declared whether it changed anything.

func (RunResult) Outstanding 

func (r RunResult) Outstanding() bool

Outstanding is the dry-run counterpart of Changed: it reports whether any phase that can report a change was reported rather than run. A phase reaches Planned only after its ShouldRun said there was work to do, so this answers "would a real run change anything" for the phases that have said how to tell.

func (RunResult) Undeclared 

func (r RunResult) Undeclared() []string

Undeclared names the phases that did not say whether they changed anything, in the order the run reached them. A caller reporting Changed is expected to report these alongside it.

type UninstallEngine 

type UninstallEngine struct {
	GenericPhase
	Distro           distrocfg.Distro
	WorkerConcurrent string
	// contains filtered or unexported fields
}

UninstallEngine state

func (*UninstallEngine) Explanation 

func (p *UninstallEngine) Explanation() string

Explanation about the current phase, used for documentation generation

func (*UninstallEngine) Prepare 

func (p *UninstallEngine) Prepare(ctx context.Context, _ *cluster.ZarfCluster, _ *distro.ZarfDistro) error

Prepare the phase

func (*UninstallEngine) Run 

func (p *UninstallEngine) Run(ctx context.Context) error

Run the phase

func (*UninstallEngine) Title 

func (p *UninstallEngine) Title() string

Title for the phase

type Unlock 

type Unlock struct {
	GenericPhase
	Cancel func(context.Context)
}

Unlock phase state

func (*Unlock) Explanation 

func (p *Unlock) Explanation() string

Explanation about the current phase, used for documentation generation

func (*Unlock) Prepare 

func (p *Unlock) Prepare(_ context.Context, c *cluster.ZarfCluster, _ *distro.ZarfDistro) error

Prepare the phase

func (*Unlock) Run 

func (p *Unlock) Run(ctx context.Context) error

Run the phase

func (*Unlock) Title 

func (p *Unlock) Title() string

Title for the phase

type UpgradeController 

type UpgradeController struct {
	UpgradeHosts
}

UpgradeController phase state

func (*UpgradeController) Explanation 

func (p *UpgradeController) Explanation() string

Explanation about the current phase, used for documentation generation

func (*UpgradeController) Prepare 

func (p *UpgradeController) Prepare(ctx context.Context, _ *cluster.ZarfCluster, d *distro.ZarfDistro) error

Prepare the phase

func (*UpgradeController) Run 

func (p *UpgradeController) Run(ctx context.Context) error

Run the phase

func (*UpgradeController) Title 

func (p *UpgradeController) Title() string

Title for the phase

type UpgradeHosts 

type UpgradeHosts struct {
	GenericPhase
	Distro distrocfg.Distro
	// contains filtered or unexported fields
}

UpgradeHosts phase state

func (*UpgradeHosts) ShouldRun 

func (p *UpgradeHosts) ShouldRun() bool

ShouldRun is true when there are workers

type UpgradeWorkers 

type UpgradeWorkers struct {
	UpgradeHosts
	WorkerConcurrent string
}

UpgradeWorkers phase state

func (*UpgradeWorkers) Explanation 

func (p *UpgradeWorkers) Explanation() string

Explanation about the current phase, used for documentation generation

func (*UpgradeWorkers) Prepare 

func (p *UpgradeWorkers) Prepare(ctx context.Context, _ *cluster.ZarfCluster, d *distro.ZarfDistro) error

Prepare the phase

func (*UpgradeWorkers) Run 

func (p *UpgradeWorkers) Run(ctx context.Context) error

Run the phase

func (*UpgradeWorkers) Title 

func (p *UpgradeWorkers) Title() string

Title for the phase

type UploadFiles 

type UploadFiles struct {
	GenericPhase
	// contains filtered or unexported fields
}

UploadFiles implements a phase which upload files to hosts

func (*UploadFiles) Explanation 

func (p *UploadFiles) Explanation() string

Explanation about the current phase, used for documentation generation

func (*UploadFiles) Prepare 

func (p *UploadFiles) Prepare(ctx context.Context, c *cluster.ZarfCluster, d *distro.ZarfDistro) error

Prepare the phase

func (*UploadFiles) Run 

func (p *UploadFiles) Run(ctx context.Context) error

Run the phase

func (*UploadFiles) ShouldRun 

func (p *UploadFiles) ShouldRun() bool

ShouldRun is true when there are workers

func (*UploadFiles) Title 

func (p *UploadFiles) Title() string

Title for the phase

type UploadFilesCommon 

type UploadFilesCommon struct {
	GenericPhase
	// contains filtered or unexported fields
}

UploadFilesCommon implements a phase which upload files to hosts

func (*UploadFilesCommon) CleanUp 

func (p *UploadFilesCommon) CleanUp(ctx context.Context)

CleanUp the phase

func (*UploadFilesCommon) Prepare 

func (p *UploadFilesCommon) Prepare(_ context.Context, _ *cluster.ZarfCluster, _ *distro.ZarfDistro) error

Prepare the phase

func (*UploadFilesCommon) Run 

func (p *UploadFilesCommon) Run(ctx context.Context) (err error)

Run the phase

func (*UploadFilesCommon) ShouldRun 

func (p *UploadFilesCommon) ShouldRun() bool

ShouldRun is true when there are workers

type ValidateHosts 

type ValidateHosts struct {
	GenericPhase
	// contains filtered or unexported fields
}

ValidateHosts performs remote OS detection

func (*ValidateHosts) Explanation 

func (p *ValidateHosts) Explanation() string

Explanation about the current phase, used for documentation generation

func (*ValidateHosts) ReadOnly 

func (p *ValidateHosts) ReadOnly() string

ReadOnly marks this phase safe under a dry run, and returns the reason for the phase docs.

func (*ValidateHosts) Run 

func (p *ValidateHosts) Run(ctx context.Context) error

Run the phase

func (*ValidateHosts) Title 

func (p *ValidateHosts) Title() string

Title for the phase

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.