Documentation
¶
Overview ¶
Package update knows whether a newer Pando has been released (R-349–R-352).
It reads GitHub's release list for trypando/pando, which the release workflow writes: one release per tag, its body exactly that version's CHANGELOG.md section, prerelease set for a tag with a suffix. Nothing else is published for it to read, so there is nothing else to keep in step.
It tells; it does not upgrade. Replacing the running container is issue #53's second half, and is opt-in through the deployment config.
Index ¶
- Constants
- func Breaks(from, to string) bool
- func HasSecurityFix(notes string) bool
- func Newer(a, b string) bool
- func Skewed(a, b string) bool
- func TrustedRoot(ctx context.Context, dir string) (root.TrustedMaterial, error)
- func VerifyChecksums(tm root.TrustedMaterial, checksums, raw []byte) error
- func VerifyImageBundle(tm root.TrustedMaterial, raw []byte, digest v1.Hash) error
- type Checker
- type GitHub
- type ImageVerifier
- type Install
- type Release
- type Settings
- type Source
- type Status
- type Upgrade
Constants ¶
const ( InstallContainer = "container" InstallBinary = "binary" )
How the server was installed, which decides how it is upgraded (R-352).
The server ships as the container image, run by the release's Compose file (internal/reference/install.go); packages and the Homebrew cask carry the CLI. So a server is either in a container, or a binary somebody started by hand — and the CLI's own upgrade is the CLI's business (internal/cli).
const ( Issuer = "https://token.actions.githubusercontent.com" ImageIdentity = `^https://github\.com/(bemeek-io|trypando)/pando/\.github/workflows/image\.yml@refs/(heads/main|tags/v)` ReleaseIdentity = `^https://github\.com/(bemeek-io|trypando)/pando/\.github/workflows/release\.yml@refs/(heads/main|tags/v)` )
What a release's signatures must say about who made them (R-357, R-363): GitHub's OIDC provider, vouching for a workflow in Pando's repository on its main branch or a version tag. The same identities docs/releasing.md tells a person to check with cosign by hand.
const DefaultInterval = 6 * time.Hour
DefaultInterval is how often the check runs. Four requests a day is well inside GitHub's unauthenticated limit of sixty an hour per address, and a security release is seen within a working morning of being published.
const Image = "trypando/pando"
Image is the published server image.
const MinCheckGap = time.Minute
MinCheckGap is the least time between two checks someone asks for. A request inside it is answered from the last check, so a button pressed repeatedly stays inside GitHub's limit for every installation behind one address.
const ReleasesURL = "https://api.github.com/repos/trypando/pando/releases?per_page=100"
ReleasesURL is where the release workflow publishes. A renamed repository redirects, and the client follows.
Variables ¶
This section is empty.
Functions ¶
func Breaks ¶
Breaks reports whether moving from one version to the next may break something: a MAJOR bump, or before 1.0 a MINOR one (docs/releasing.md).
func HasSecurityFix ¶
HasSecurityFix reads a CHANGELOG.md section's Security subsection. Every release carries one; "No new advisories." is what an empty one says.
func Skewed ¶
Skewed reports whether two versions differ in a way their interfaces may: MAJOR or MINOR. A PATCH release changes no interface (docs/releasing.md). Development builds are never skewed — there is nothing to compare.
func TrustedRoot ¶
TrustedRoot fetches Sigstore's public-good trusted root through its TUF repository, caching under dir. The root it starts from is embedded in sigstore-go, so a compromised mirror cannot substitute one.
func VerifyChecksums ¶
func VerifyChecksums(tm root.TrustedMaterial, checksums, raw []byte) error
VerifyChecksums checks a release's checksums.txt against its signature bundle and the release workflow's identity (R-363).
func VerifyImageBundle ¶
VerifyImageBundle checks a cosign signature bundle against an image's index digest and the image workflow's identity.
Types ¶
type Checker ¶
type Checker struct {
Source Source
Settings func(ctx context.Context) (Settings, error)
// Current is this binary's version, "dev" for a development build.
Current string
Install Install
Clock clock.Clock
Logger *zap.Logger
Interval time.Duration
// contains filtered or unexported fields
}
Checker asks Source on an interval while policy allows it, and answers Status from what it last heard.
func (*Checker) CheckNow ¶ added in v0.6.0
CheckNow asks Source on request rather than waiting for the next tick, and answers with what it found. Within MinCheckGap of the last check it sends nothing and answers from that one; while policy has the check off it sends nothing at all (R-349).
type GitHub ¶
GitHub lists releases from GitHub's API.
The request carries a User-Agent naming the version, which GitHub requires, and nothing else about the installation (R-349).
type ImageVerifier ¶
type ImageVerifier struct {
// Repository is the image, without a tag: index.docker.io/trypando/pando.
Repository string
Trusted func(ctx context.Context) (root.TrustedMaterial, error)
Remote []remote.Option
}
ImageVerifier checks a released image's signature before Pando runs it (R-357).
type Install ¶
type Install struct {
Kind string `json:"kind"`
}
Install is how this server was installed.
func DetectInstall ¶
func DetectInstall() Install
DetectInstall reads how this process was started. Docker writes /.dockerenv into every container it runs; a PANDO_ variable would be read as configuration.
type Release ¶
type Release struct {
Version string `json:"version"`
Prerelease bool `json:"prerelease"`
PublishedAt time.Time `json:"published_at"`
URL string `json:"url"`
// Notes is the version's CHANGELOG.md section, as Markdown.
Notes string `json:"notes"`
// Security is set when the Security section names an advisory rather than
// saying "No new advisories." (docs/releasing.md).
Security bool `json:"security"`
// Breaking is set when the version may break what the one before it did:
// a MAJOR bump, or a MINOR one before 1.0 (docs/releasing.md).
Breaking bool `json:"breaking"`
}
Release is one published version.
type Settings ¶
type Settings struct {
Enabled bool
Channel policy.UpdateChannel
}
Settings is what host policy says about the check.
func SettingsFrom ¶
SettingsFrom reads the check's settings from a policy document.
type Status ¶
type Status struct {
Current string `json:"current"`
// Development is set for a binary no release built, which has no version
// to compare: it is told what the latest is, never that it is behind.
Development bool `json:"development"`
Enabled bool `json:"enabled"`
Channel policy.UpdateChannel `json:"channel"`
CheckedAt *time.Time `json:"checked_at,omitempty"`
// Error is why the last check failed, when it did. What an earlier check
// found is still reported beside it.
Error string `json:"error,omitempty"`
Latest string `json:"latest,omitempty"`
// Available is set when Latest is newer than Current.
Available bool `json:"available"`
// Releases are the versions after Current up to Latest, newest first.
Releases []Release `json:"releases"`
Security bool `json:"security"`
Breaking bool `json:"breaking"`
// Upgrade says how to move this installation to Latest (R-352).
Upgrade *Upgrade `json:"upgrade,omitempty"`
}
Status is what the check knows, as every surface shows it (R-351).
type Upgrade ¶
type Upgrade struct {
Version string `json:"version"`
// Image is the image to run, for a container install.
Image string `json:"image,omitempty"`
// Command upgrades an installation run from the release's Compose file,
// from the directory that file is in.
Command string `json:"command"`
// Instructions says the same in a sentence, including the case the
// command does not cover.
Instructions string `json:"instructions"`
}
Upgrade is how to move this installation to a version, in the words and commands somebody would paste.