upgrade

Documentation

Overview

Package upgrade detects the release upgrades running on an installation's Cluster API clusters and keeps the automatic holds that stop the installation's merges and lease claims while they run.

A cluster's upgrade begins when its release changes: the Cluster's release.giantswarm.io/version label differs from the release cluster-api-events last recorded for it (giantswarm.io/last-known-cluster-upgrade-version), cluster-api-events has marked it upgrading (giantswarm.io/cluster-upgrading "true", set from the release change until its control plane and workers have rolled), or its scheduled upgrade is due (alpha.giantswarm.io/update-schedule-target-release differs from the label and update-schedule-target-time has passed). An upgrade that began runs on while the cluster's control plane or node pools have not rolled: a KubeadmControlPlane whose status.version is not its spec.version, or a control plane, MachinePool or MachineDeployment with fewer up-to-date replicas than replicas or a RollingOut condition that is True, or a Cluster whose own RollingOut condition is True. A cluster on an older release than another is not upgrading: only a change of its own release begins an upgrade.

Index

• Constants
• Variables
• func Describe(installation string, u Upgrade) string
• func EndLine(h state.Hold) string
• func Held(st *state.State, installation string, now time.Time) (state.Hold, bool)
• func HeldClusters(st *state.State, now time.Time) func(installation, cluster string) bool
• func HoldTarget(installation, cluster string) string
• func Is(h state.Hold) bool
• func Lift(st *state.State, target string, by state.Party, now time.Time) bool
• func Line(h state.Hold) string
• func Reconcile(st *state.State, installation string, running []Upgrade, now time.Time, ...) (begun, ended []state.Hold)
• type Condition
• type Object
  • func Parse(raw []byte) ([]Object, error)
• type Progress
  • func (p Progress) String() string
• type Reader
  • func (r Reader) Read(ctx context.Context, targets []Target, now time.Time, ...) []Status
• type Reading
• type Readings
  • func (rs Readings) Fresh(installation string, now time.Time, within time.Duration) bool
  • func (rs Readings) Keep(statuses []Status, at time.Time)
  • func (rs Readings) Merge(o Readings)
  • func (rs Readings) Running(installation string) bool
• type Status
  • func (s Status) Words(now time.Time) string
• type Target
• type Upgrade
  • func Detect(objs []Object, now time.Time, held func(cluster string) bool) []Upgrade

Constants

const (
	// HoldPrefix starts the target of an upgrade's automatic hold,
	// upgrade:<installation>/<cluster>.
	HoldPrefix = "upgrade:"
)

const ReadingsFile = "upgrades.json"

ReadingsFile is the state store's side file of the last readings, shared by every watch, snapshot and ui of the machine: one reads an installation, the others use its reading while it is fresh.

Variables

var Kinds = []string{
	"clusters.v1beta2.cluster.x-k8s.io",
	"kubeadmcontrolplanes.v1beta2.controlplane.cluster.x-k8s.io",
	"machinepools.v1beta2.cluster.x-k8s.io",
	"machinedeployments.v1beta2.cluster.x-k8s.io",
}

Kinds are the lists read per installation, one each per reading, at the API version whose fields the detection reads.

Functions

func Describe

func Describe(installation string, u Upgrade) string

Describe is an upgrade in words: <installation>/<cluster> <from> → <to>.

func EndLine

func EndLine(h state.Hold) string

EndLine is a hold's end line.

func Held

func Held(st *state.State, installation string, now time.Time) (state.Hold, bool)

Held returns an active upgrade hold of the installation.

func HeldClusters

func HeldClusters(st *state.State, now time.Time) func(installation, cluster string) bool

HeldClusters says which clusters of which installation hold an upgrade, lifted or not: an upgrade whose hold was lifted still runs.

func HoldTarget

func HoldTarget(installation, cluster string) string

HoldTarget is the hold target of a cluster's upgrade.

func Is

func Is(h state.Hold) bool

Is reports whether a hold is an upgrade's automatic hold.

func Lift

func Lift(st *state.State, target string, by state.Party, now time.Time) bool

Lift records a person's lift of an upgrade hold: the hold stays, inactive, until its upgrade ends. It reports whether the target held an active hold.

func Line

func Line(h state.Hold) string

Line is a hold's begin line, UPGRADE <installation>/<cluster> <from> → <to>.

func Reconcile

func Reconcile(st *state.State, installation string, running []Upgrade, now time.Time, by state.Party) (begun, ended []state.Hold)

Reconcile makes the installation's upgrade holds those of its running upgrades: a hold for each that has none (begun), none for any that no longer runs (ended). A lifted hold stays lifted while its upgrade runs; a different upgrade of the cluster (another target release) replaces it with an active hold. Only a readable installation is reconciled.

Types

type Condition

type Condition struct {
	Type   string `json:"type"`
	Status string `json:"status"`
}

Condition is a status condition.

type Object

type Object struct {
	Kind     string `json:"kind"`
	Metadata struct {
		Name        string            `json:"name"`
		Namespace   string            `json:"namespace"`
		Labels      map[string]string `json:"labels,omitempty"`
		Annotations map[string]string `json:"annotations,omitempty"`
	} `json:"metadata"`
	Spec struct {
		Version string `json:"version,omitempty"`
	} `json:"spec"`
	Status struct {
		Version          string      `json:"version,omitempty"`
		Replicas         *int32      `json:"replicas,omitempty"`
		UpToDateReplicas *int32      `json:"upToDateReplicas,omitempty"`
		Conditions       []Condition `json:"conditions,omitempty"`
	} `json:"status"`
}

Object is the part of a Cluster, KubeadmControlPlane, MachinePool or MachineDeployment the detection reads.

func Parse

func Parse(raw []byte) ([]Object, error)

Parse reads a `kubectl get -o json` list.

type Progress

type Progress struct {
	UpToDate int32 `json:"upToDate"`
	Replicas int32 `json:"replicas"`
}

Progress is how many replicas of a cluster's control plane or node pools are up to date.

func (Progress) String

func (p Progress) String() string

type Reader

type Reader struct {
	// Kubectl is the kubectl binary.
	Kubectl string
	// Timeout bounds the reading of one installation.
	Timeout time.Duration
}

Reader lists an installation's clusters, control planes and node pools with kubectl.

func (Reader) Read

func (r Reader) Read(ctx context.Context, targets []Target, now time.Time, held func(installation, cluster string) bool) []Status

Read reads every target in parallel, each within r.Timeout: one list of all kinds, and for an upgrade whose hold does not exist yet and whose from release is unknown, its cluster's events. held says which clusters hold an upgrade.

type Reading

type Reading struct {
	At     time.Time `json:"at"`
	Status Status    `json:"status"`
}

Reading is an installation's last status and when its reading began.

type Readings

type Readings map[string]Reading

Readings are the last readings by installation.

func (Readings) Fresh

func (rs Readings) Fresh(installation string, now time.Time, within time.Duration) bool

Fresh says whether the installation's last reading began less than within before now.

func (Readings) Keep

func (rs Readings) Keep(statuses []Status, at time.Time)

Keep records the statuses read at at.

func (Readings) Merge

func (rs Readings) Merge(o Readings)

Merge keeps the newer reading of each installation.

func (Readings) Running

func (rs Readings) Running(installation string) bool

Running says whether the installation's last reading found an upgrade.

type Status

type Status struct {
	Installation string    `json:"installation"`
	Err          string    `json:"error,omitempty"`
	Upgrades     []Upgrade `json:"upgrades,omitempty"`
	// NoClusterAPI is an installation that serves none of the kinds: it has
	// no cluster to upgrade.
	NoClusterAPI bool `json:"noClusterAPI,omitempty"`
}

Status is one installation's reading: its running upgrades, or why it could not be read. An unreadable installation is neither upgrading nor quiet.

func (Status) Words

func (s Status) Words(now time.Time) string

Words is the status in one line: the installation and none, unreadable, or its upgrades; with a now, also how long each has run and its progress.

type Target

type Target struct {
	Name    string
	Context string
}

Target is an installation to read and the kube context that reaches it.

type Upgrade

type Upgrade struct {
	Cluster      string    `json:"cluster"`
	Namespace    string    `json:"namespace"`
	From         string    `json:"from,omitempty"`
	To           string    `json:"to,omitempty"`
	Since        time.Time `json:"since,omitzero"`
	ControlPlane Progress  `json:"controlPlane"`
	NodePools    Progress  `json:"nodePools"`
	// Rolling is an upgrade whose release change is done and whose
	// rollout is not; it runs on only while its hold does.
	Rolling bool `json:"rolling,omitempty"`
}

Upgrade is a cluster's running upgrade. From is empty until it is known.

func Detect

func Detect(objs []Object, now time.Time, held func(cluster string) bool) []Upgrade

Detect returns the upgrades running on the clusters in objs at now, in the clusters' order. held says whether a cluster's upgrade hold is active: an upgrade that began runs on until its cluster has rolled.