receipt

package
v0.41.1 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package receipt builds the structured record of one cargoship run.

When cargoship runs as an Ansible module a playbook gets a structured result; when an operator runs the same lifecycle commands from the CLI the command returns nothing but an error, and everything the run knew is left in log lines on stderr. This is the artifact that closes that gap: one self-describing JSON document per run, carrying what was run, against which package, against which fleet, and what moved.

It is written on failure as well as success. A failed apply is the run an auditor most wants a record of, and it is the run whose log lines are least likely to still be in a scrollback buffer by the time anyone asks.

Index

Constants

View Source
const (
	// DispositionRan means the phase executed, as itself or by its own dry-run path.
	DispositionRan = "ran"
	// DispositionPlanned means a dry run reported the phase instead of running it.
	DispositionPlanned = "planned"
	// DispositionSkipped means ShouldRun filtered the phase out. It is not the same as doing
	// nothing: a phase can finish its work in Prepare and then have nothing left to run.
	DispositionSkipped = "skipped"
)

Phase dispositions: where a phase ended up.

View Source
const (
	// DryRunSkip means a dry run reports the phase and does not run it.
	DryRunSkip = "skip"
	// DryRunReadOnly means the phase reads hosts and changes nothing, so a dry run runs it as
	// itself.
	DryRunReadOnly = "read-only"
	// DryRunOwnPath means the phase has its own dry-run path.
	DryRunOwnPath = "own-path"
)

Dry-run classifications, as a receipt reports them.

View Source
const SchemaVersion = "1.1"

SchemaVersion is the version of the receipt document format.

It is first in the document and first here because a receipt outlives the cargoship that wrote it: these are kept for audit, parsed by things cargoship knows nothing about, and read back after an upgrade. Bump the minor for a field added, the major for a field removed or given a new meaning.

Variables

This section is empty.

Functions

func Write

func Write(path string, r Receipt) error

Write serializes the receipt to path, creating the parent directory if it does not exist.

The file is truncated and its mode reset on every write. Both matter on a path an operator reuses between runs: O_TRUNC alone would leave the tail of a longer previous receipt behind, and the create mode does not apply to a file that already exists, so a receipt written into a world-readable file left by something else would stay world-readable.

Types

type Cluster

type Cluster struct {
	Name string `json:"name,omitempty"`
	// LoadBalancer is the cluster's control-plane endpoint, as configured.
	LoadBalancer string `json:"loadBalancer,omitempty"`
	ConfigPath   string `json:"configPath,omitempty"`
	HostCount    int    `json:"hostCount"`
}

Cluster is the fleet the run was pointed at.

type Host

type Host struct {
	Address          string `json:"address"`
	Hostname         string `json:"hostname,omitempty"`
	Role             string `json:"role,omitempty"`
	Profile          string `json:"profile,omitempty"`
	Arch             string `json:"arch,omitempty"`
	OS               string `json:"os,omitempty"`
	OSVersion        string `json:"osVersion,omitempty"`
	PrivateAddress   string `json:"privateAddress,omitempty"`
	PrivateInterface string `json:"privateInterface,omitempty"`
	EngineVersion    string `json:"engineVersion,omitempty"`
	// Changed is whether any phase that reports per host said this one moved.
	Changed bool `json:"changed"`
	// PhasesNamed is how many phases named this host and PhasesReporting how many declared per
	// host at all. The pair is reported because the numerator alone cannot be read: named by
	// two of two phases is complete coverage, named by two of fifteen is not, and they look the
	// same without the denominator.
	PhasesNamed     int `json:"phasesNamed"`
	PhasesReporting int `json:"phasesReporting"`
}

Host is one host of the fleet, as the run found it.

Every field here is copied in by name. Nothing marshals cluster.Host directly and nothing should: it embeds a live rig client and a metadata struct full of connection state, so a receipt built by excluding the fields that must not appear would leak the next field somebody adds. An allowlist fails closed -- a new fact is absent from receipts until someone adds it here, which is the safe direction to be wrong in.

type HostChange

type HostChange struct {
	Host    string             `json:"host"`
	Changed bool               `json:"changed"`
	Details []HostChangeDetail `json:"details,omitempty"`
}

HostChange is what one phase did to one host.

type HostChangeDetail

type HostChangeDetail struct {
	Path   string `json:"path,omitempty"`
	Reason string `json:"reason,omitempty"`
	// Diff can carry anything the file carried, which for an engine configuration includes join
	// tokens and registry credentials. The sanitizer drops it outright; nothing that leaves the
	// management node should contain it.
	Diff string `json:"diff,omitempty"`
}

HostChangeDetail is one thing a phase did to one host.

type Invocation

type Invocation struct {
	Command string `json:"command"`
	// Args is the command line as given, with the value of any flag known to carry a secret
	// replaced. See redactArgs for why that is a shorter list than it looks.
	Args       []string  `json:"args,omitempty"`
	Version    string    `json:"version,omitempty"`
	Commit     string    `json:"commit,omitempty"`
	Operator   string    `json:"operator,omitempty"`
	Host       string    `json:"host,omitempty"`
	Platform   string    `json:"platform,omitempty"`
	DryRun     bool      `json:"dryRun"`
	StartedAt  time.Time `json:"startedAt"`
	FinishedAt time.Time `json:"finishedAt"`
	// Duration is the whole run's wall clock, which is not the sum of the phase durations: it
	// includes loading the package, resolving values and connecting, none of which is a phase.
	Duration string `json:"duration,omitempty"`
}

Invocation is what was run, by whom, from where.

type Options

type Options struct {
	// Command is the lifecycle command that ran: apply, prepare, reset, engine-config-sync.
	Command string
	// Args is the raw command line. It is redacted on the way in, not by the caller.
	Args []string
	// Version and Commit identify the cargoship that ran. They come from the config package
	// rather than being read here, so a test can pin them.
	Version string
	Commit  string
	// ConfigPath is the cluster configuration the run was given.
	ConfigPath string
	// Package describes the distro package, and is nil for a command that loads none.
	Package *Package
	// StartedAt is when the command began, which is earlier than the first phase.
	StartedAt time.Time
	// DryRun is whether the run was a dry run.
	DryRun bool
	// Observed is whether any run reached its phases, from phase.ResultSink.Observed. It is
	// passed rather than inferred because an empty RunResult and a run that never started look
	// identical from the result alone.
	Observed bool
	// Err is how the run ended, nil on success.
	Err error
}

Options is everything the caller knows that the run result does not.

type Outcome

type Outcome struct {
	Succeeded bool   `json:"succeeded"`
	Error     string `json:"error,omitempty"`
	Changed   bool   `json:"changed"`
	// ChangedSignal says how much Changed is worth: complete when every phase the run reached
	// said whether it changed anything, partial when some did not, unknown when the run never
	// reached its phases.
	ChangedSignal string `json:"changedSignal"`
	// ChangedUndeclared names the phases that did not say, and HostsUndeclared those that did
	// not say per host. They are what make a partial signal actionable rather than a warning
	// with nothing behind it.
	ChangedUndeclared []string `json:"changedUndeclared,omitempty"`
	HostsUndeclared   []string `json:"hostsUndeclared,omitempty"`
	// Warnings are what the phases decided that an operator may want to undo. A run can
	// succeed with warnings, so this is reported next to the outcome rather than inside it:
	// Succeeded stays true and the warnings say what the success cost.
	Warnings []Warning `json:"warnings,omitempty"`
}

Outcome is how the run ended.

type Package

type Package struct {
	Path string `json:"path,omitempty"`
	Name string `json:"name,omitempty"`
	// Version is the package's own version, not cargoship's.
	Version string `json:"version,omitempty"`
	// SHA256 is the digest of the archive as given, present only when the package was loaded
	// from a local file. It is what an auditor compares against the artifact they were shipped.
	SHA256 string `json:"sha256,omitempty"`
	// Digest is the OCI manifest digest computed over the package contents at load. It differs
	// from SHA256 -- that is the bytes of one archive, this is the identity of what is inside
	// it, and the same contents repacked keep this and change that.
	Digest       string `json:"digest,omitempty"`
	Architecture string `json:"architecture,omitempty"`
	Engine       string `json:"engine,omitempty"`
	Signed       bool   `json:"signed"`
	// Verification is the strategy the run was asked to apply: never, if-possible, or always.
	// Signed says the package carried a signature; this says whether anyone checked it.
	Verification string `json:"verification,omitempty"`
}

Package is the provenance of the distro package the run applied.

There is no SBOM field. Cargoship does not produce one yet -- package creation hardcodes SkipSBOM -- and a field that is always absent is worse than no field, because it reads as "this package had none" rather than "nothing here records that".

type Phase

type Phase struct {
	Title       string `json:"title"`
	Explanation string `json:"explanation,omitempty"`
	// Disposition is one of DispositionRan, DispositionPlanned or DispositionSkipped.
	Disposition string `json:"disposition"`
	// DryRun is what a dry run does with this phase, whether or not this run was one.
	DryRun string `json:"dryRun,omitempty"`
	// Declared is whether the phase said anything about changing the fleet. When it is false,
	// Changed is false because nothing was asked, not because nothing happened.
	Declared bool `json:"declared"`
	Changed  bool `json:"changed"`
	// HostsDeclared stands to Hosts as Declared stands to Changed.
	HostsDeclared bool         `json:"hostsDeclared"`
	Hosts         []HostChange `json:"hosts,omitempty"`
	Duration      string       `json:"duration,omitempty"`
}

Phase is one phase of the run.

type Receipt

type Receipt struct {
	SchemaVersion string `json:"schemaVersion"`
	// Redacted marks a receipt that has been through the sanitizer for sharing. It is absent on
	// a full receipt rather than false, so that a reviewer handed a file can tell the two apart
	// at a glance instead of inferring it from which fields happen to be missing.
	Redacted   bool       `json:"redacted,omitempty"`
	Invocation Invocation `json:"invocation"`
	// Package is absent for a command that loads none, which is what reset and kube-config do.
	Package *Package `json:"package,omitempty"`
	Cluster Cluster  `json:"cluster"`
	Phases  []Phase  `json:"phases"`
	Hosts   []Host   `json:"hosts"`
	Outcome Outcome  `json:"outcome"`
}

Receipt is the record of one cargoship run.

func Build

func Build(cfg *cluster.Cluster, result phase.RunResult, opts Options) Receipt

Build assembles the receipt from the run.

It never fails. A receipt is written on the failure path, and a builder that could itself fail there would be one more reason for an operator to end up with no record of the run that most needed one -- so every field is best-effort, and an unknown is left empty rather than reported.

func Read

func Read(path string) (Receipt, error)

Read loads a receipt from path.

func Redact

func Redact(r Receipt) Receipt

Redact returns a copy of r that is safe to attach to a public issue.

It is a projection, not an edit: the full receipt stays as it is on disk, because redaction is lossy and one-way and the operator's own copy is the audit record. What survives is everything a maintainer triages from -- the phase ledger with its dispositions, durations and change reasons, the package provenance, the outcome and the error -- and what goes is everything that identifies the fleet or could carry a secret:

  • Hosts become host-01, host-02 in the order the receipt lists them, consistently across every phase, so a reader can still follow which host failed without learning its address.
  • Diff bodies are dropped. This is the sharpest edge: an engine config.yaml diff carries join tokens, TLS SANs and registry credentials. The file's path and the reason it changed are what a maintainer needs; the content is what leaks.
  • The cluster name, the operator, the management host and the command line are dropped outright. Nothing in triage needs them, and config and package paths routinely carry customer and site names.

type Warning added in v0.38.0

type Warning struct {
	Phase string `json:"phase"`
	// Host is the address of the host this is about, absent for a warning about the run
	// itself. A redacted receipt carries its alias, the same one the phase ledger uses.
	Host string `json:"host,omitempty"`
	// Path is the file this is about, absolute as the host sees it.
	Path string `json:"path,omitempty"`
	// Reason is why, in the vocabulary the phases log: "kept, unmanaged".
	Reason string `json:"reason,omitempty"`
}

Warning is one thing a phase decided that an operator may want to know about.

The case this exists for is phase 50 keeping image tarballs it does not own, because the host carries the marker file that asks it to. Nothing failed, so there is no error to record, and without this the only trace is a log line from the middle of the run.

Jump to

Keyboard shortcuts

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