Documentation
¶
Overview ¶
Package runnerharness runs the runner against the Ptah image support/ptah.json pins, without a cluster, and holds what Ptah printed to the committed captures.
The runner's contract with Ptah is the arguments it builds, the documents it decodes, the exit statuses it reads and the standard error it reads or ignores. The harness builds each operation's Job through internal/workload, runs that Job's containers in Docker in the shape the Job declares, with the runner from this commit calling a recording runner.Executor inside the executor image, against PostgreSQL, MySQL, an OCI registry and the end-to-end Git server. Every document is decoded with internal/dataplane, every result is framed and parsed back with the manager's parser, and everything is compared with the captures under internal/dataplane/testdata. A write mode regenerates those captures, so a repin is one command and a reviewed diff:
DOCKER_CONTEXT=<context> make runner-harness # compare DOCKER_CONTEXT=<context> make runner-harness-write # regenerate
CompareCaptures and Masker say what counts as a change of shape and which values are volatile. Declared is the set of operations and commands the run is counted against. Translate is the stand-in for the kubelet.
A run removes what it made when it ends. One that passes its -timeout or is killed cannot, so a second process it starts, the janitor, clears it from outside. RunRecord is what a later run on the same daemon reads to clear a run whose janitor could not finish.
It does not replace kind. Admission, RBAC, the Job and Pod lifecycle, NetworkPolicy and durable result delivery are proven there.
Index ¶
- Constants
- Variables
- func CheckCount(operations []OperationCase, commands []string, ran Ran) error
- func CommandWords(args []string) string
- func DecodeDocument(args []string, exit int, stdout []byte) error
- func DocumentPath(row string, index int, command string, document []byte) string
- func DrivenImages(driver []byte) (postgres, mysql, registry string, err error)
- func MatchSourceCommands(source, declared []string) error
- func PinnedExecutor(catalog []byte) (image, commit, release string, err error)
- func Scrub(document []byte) ([]byte, error)
- func SourceCommands(directory string) ([]string, error)
- func SourceOperations(source []byte) ([]runner.Operation, error)
- func StrayFiles(root string, captures Captures) ([]string, error)
- func WriteCaptures(root string, masker *Masker, committed, fresh Captures) error
- type Captures
- type Change
- type Child
- type Cluster
- type Container
- type Difference
- type EnvVar
- type Gate
- type Masker
- type Mount
- type OperationCase
- type Pod
- type Provenance
- type Ran
- type Row
- type RunRecord
- type Source
- type Volume
Constants ¶
const ( // RequireVariable says the harness has to run: a missing prerequisite then // fails it rather than skipping it. The make targets set it, so the target // CI runs can only pass by running every row, as PTAH_REQUIRE_ENVTEST does // for envtest. Unset, a plain `go test ./...` skips the run and touches no // Docker daemon. RequireVariable = "PTAH_REQUIRE_RUNNER_HARNESS" // ContextVariable names the Docker context to use. It has no default: every // container goes to the daemon somebody named. ContextVariable = "DOCKER_CONTEXT" // WriteVariable regenerates the committed captures. WriteVariable = "RUNNER_HARNESS_WRITE" // ImageVariable runs another executor image than the pin, to see what it // breaks. It cannot write captures. ImageVariable = "RUNNER_HARNESS_IMAGE" // PrefixVariable starts the name of everything the run creates, and a random // part follows it. Unset, the names start with ptah-runner-harness. PrefixVariable = "RUNNER_HARNESS_PREFIX" // OutVariable keeps the fresh captures of a run in this directory. OutVariable = "RUNNER_HARNESS_OUT" )
The variables a run reads.
const CapturesDirectory = "internal/dataplane/testdata"
CapturesDirectory holds every committed capture, relative to the repository root: documents at the paths the decoders' tests read them from, and the transcript that says which row printed each one.
const RunLabel = "operator.ptah.run/runner-harness"
RunLabel marks the network a run creates first and removes last. Its value is the run's RunRecord, so a network that outlived its run says what is left of that run and when nothing can still be using it.
Variables ¶
var Declared = struct { Operations []OperationCase Commands []string }{ Operations: []OperationCase{ {runner.OperationResolve, SourceOCI}, {runner.OperationResolve, SourceGit}, {runner.OperationVerify, SourceOCI}, {runner.OperationObserve, SourceOCI}, {runner.OperationObserve, SourceGit}, {runner.OperationPlan, SourceOCI}, {runner.OperationPlan, SourceGit}, {runner.OperationApply, SourceNone}, {runner.OperationMigrationHistory, SourceOCI}, {runner.OperationMigrationHistory, SourceGit}, {runner.OperationMigrationApply, SourceOCI}, {runner.OperationMigrationApply, SourceGit}, }, Commands: []string{ "migrations pull", "migrations status", "migrations up", "oci inspect", "oci resolve", "oci verify", "schema apply", "schema apply --dry-run", "schema drift", "schema plan", "schema pull", "schema validate", }, }
Declared is the set a complete run is held to. A row that runs anything else fails the run, and so does anything here that no row ran. A runner operation or a Ptah command added without a row here fails TestDeclaredCommandsAreTheOnesInTheSource, and a row reaching a new command fails the run: adding it is one line here and the row that runs it.
Functions ¶
func CheckCount ¶
func CheckCount(operations []OperationCase, commands []string, ran Ran) error
CheckCount holds what ran to the declared set, and fails on a declared case nothing ran, on a case nobody declared, and on a run of no rows.
func CommandWords ¶
CommandWords names a Ptah command by its first two arguments. The plan validation is a command of its own: it reads the same report at another outcome, and a release can change one and not the other.
func DecodeDocument ¶
DecodeDocument reads what a child printed with the decoder the runner uses for that command, so a release that moves a contract fails here as it would in a Pod. A command that prints no document under this runner's arguments, the OCI fetch and a refused Git pull, has nothing to read.
func DocumentPath ¶
DocumentPath is where a row's document is stored when the row names no other path: under the row's own name, numbered by the child that printed it.
func DrivenImages ¶
DrivenImages reads the database and registry images the lifecycle driver pins.
func MatchSourceCommands ¶
MatchSourceCommands compares what the sources write down with the declared commands. "*" in a source command matches any word there.
func PinnedExecutor ¶
PinnedExecutor reads the image, commit and release support/ptah.json pins for edge. The catalog is what a repin edits, so nothing here names a version.
func Scrub ¶
Scrub removes the scrubbed fields from a document Ptah printed with two spaces of indentation, keeping every other byte. A document without them is returned as it came, and one that still holds them afterwards is an error.
func SourceCommands ¶
SourceCommands reads the Ptah commands a package's sources write down: every []string literal assigned to Args or args whose first element is not a flag. An element that is not a string literal reads as "*", which stands for whichever verb or family the code computes.
func SourceOperations ¶
SourceOperations reads the Operation constants a runner source declares.
func StrayFiles ¶
StrayFiles names the files under root that no row of the set names: a document the run no longer prints, which no test would ever read again.
func WriteCaptures ¶
WriteCaptures stores fresh as the committed captures under root.
A document whose only differences from the committed one are volatile values stays as it is, so a repin's diff holds what the release changed and nothing else. A file under root that no row names is removed.
Types ¶
type Captures ¶
type Captures struct {
Rows []Row
Documents map[string][]byte
Provenance Provenance
}
Captures is a complete set: the rows, every document they name by its path under CapturesDirectory, and what they were captured from.
func LoadCaptures ¶
LoadCaptures reads every committed capture.
type Change ¶
type Change struct {
Row string
Difference Difference
}
Change is one way a fresh run differs from the committed captures.
func CompareCaptures ¶
CompareCaptures reports every change of shape between two sets, and a row or a document in one and not the other. What it compares under each row is the whole record, so an exit status, an argument, a line of standard error and the frame's payload are held exactly as a document's fields are.
type Child ¶
type Child struct {
Command string `json:"command"`
Args []string `json:"args"`
Exit int `json:"exit"`
Stderr string `json:"stderr,omitempty"`
// Stdout is the file holding what it printed, under CapturesDirectory. A
// child that printed nothing has none.
Stdout string `json:"stdout,omitempty"`
}
Child is what one Ptah command did, in the form it is committed: arguments, standard error and status in the transcript, with the volatile values masked, and standard output in a file of its own, as printed.
type Cluster ¶
type Cluster struct {
Secrets map[string]map[string][]byte
ConfigMaps map[string]map[string][]byte
}
Cluster is the Secrets and ConfigMaps a Job's Pod reads, by name and key.
type Container ¶
type Container struct {
Name, Image string
Command, Args []string
WorkingDir string
Env []EnvVar
User string
ReadOnlyRoot bool
NoNewPrivilege bool
DropCapability []string
Mounts []Mount
}
Container is one container of a Pod.
func (Container) RunArgs ¶
func (c Container) RunArgs(name, network string, mounts func(Mount) ([]string, error), extraArgs ...string) ([]string, error)
RunArgs is the docker run command line for a container of the Pod. A Secret's value goes by name, so that it is on no command line: the caller sets it in the docker client's own environment (see SecretEnv).
mounts resolves each of the container's mounts to its --mount or --tmpfs flags.
type Difference ¶
type Difference struct {
Path string
// Kind is added, removed, retyped or changed.
Kind string
Committed string
Fresh string
}
Difference is one change of shape, at a path inside a capture.
func CompareDocuments ¶
func CompareDocuments(masker *Masker, committed, fresh []byte) []Difference
CompareDocuments reports every change of shape between two documents a child printed. JSON is compared as a tree and anything else line by line.
func CompareLines ¶
func CompareLines(masker *Masker, committed, fresh string) []Difference
CompareLines reports every line of text that differs, by its number.
func CompareValues ¶
func CompareValues(masker *Masker, committed, fresh any) []Difference
CompareValues reports every change of shape between two decoded JSON values.
func (Difference) String ¶
func (d Difference) String() string
type EnvVar ¶
EnvVar is a resolved environment variable. Secret says the value came from a Secret: the Job's literals are not secrets, and these are.
type Masker ¶
type Masker struct {
// contains filtered or unexported fields
}
Masker masks the volatile values and counts what each rule matched, so a run can refuse a rule that masked nothing. It is safe for concurrent use: the rows of a run share one.
func (*Masker) UnusedRules ¶
UnusedRules names the declared rules that masked nothing yet.
type OperationCase ¶
OperationCase is one operation from one source.
type Pod ¶
type Pod struct {
// InstallTo is where the Job installs the runner. The harness puts the
// recorder there instead of running the install container.
InstallTo string
// Containers are the init containers after the runner's install, then the
// operation container, in order.
Containers []Container
Volumes []Volume
}
Pod is an operation Job's Pod, as the harness runs it. It carries the values the Job declares rather than a second statement of them: the user, the read- only root file system, the dropped capabilities, the environment, the mounts, the command and its arguments all come from the Job the builder made.
type Provenance ¶
type Provenance struct {
PtahRelease string `json:"ptahRelease"`
PtahCommit string `json:"ptahCommit"`
PtahImage string `json:"ptahImage"`
}
Provenance is the Ptah build a set of captures was taken from.
type Ran ¶
type Ran struct {
Rows int
Operations map[OperationCase]int
Commands map[string]int
}
Ran is what a complete run counted.
type Row ¶
type Row struct {
Name string `json:"name"`
Operation string `json:"operation,omitempty"`
Source Source `json:"source,omitempty"`
// Engine is the engine the row's target runs, as a plan's decoder is told it.
Engine string `json:"engine,omitempty"`
Children []Child `json:"children"`
// Refusal is the error a fetch or a guard returned.
Refusal string `json:"refusal,omitempty"`
// Result is the frame's payload as the manager's parser read it.
Result any `json:"result,omitempty"`
// SavedPlan is the file holding the plan a Plan operation saved.
SavedPlan string `json:"savedPlan,omitempty"`
}
Row is one operation's run, or one command a row ran on its own.
type RunRecord ¶
type RunRecord struct {
// Prefix starts the name of everything the run made.
Prefix string `json:"prefix"`
// Expires is a time after the run's own deadline. Until then the run may
// still be alive, so another run on the same daemon leaves it alone.
Expires time.Time `json:"expires"`
// Pulled names the images the host did not hold when the run started.
Pulled []string `json:"pulled,omitempty"`
}
RunRecord is what a later run needs to clear a run that died and whose janitor could not finish.
func ParseRunRecord ¶
ParseRunRecord reads the label's value. It refuses a record that does not say whose objects these are or when they expire, so a sweep removes nothing on the strength of it.
type Volume ¶
type Volume struct {
Name string
Empty bool
// SizeBytes bounds an empty volume.
SizeBytes int64
Files []volumes.Entry
// Group is the Pod's fsGroup.
Group int
}
Volume is one volume of a Pod. A volume with Empty set starts empty and writable by the Pod's group; otherwise it holds Files.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Command runner-harness-recorder is the runner from this commit, in the form the harness runs inside the executor image.
|
Command runner-harness-recorder is the runner from this commit, in the form the harness runs inside the executor image. |
|
Package recording is what the runner harness keeps of a run inside the executor image: a runner.Executor that records every child it starts, and the transcript test/runnerharness/recorder prints for the harness to read.
|
Package recording is what the runner harness keeps of a run inside the executor image: a runner.Executor that records every child it starts, and the transcript test/runnerharness/recorder prints for the harness to read. |
|
Package volumes writes and unpacks what the harness's stand-in for the kubelet puts on a Pod's volumes: the directories an emptyDir starts as, and the files a Secret or a ConfigMap projects, with their owners and modes.
|
Package volumes writes and unpacks what the harness's stand-in for the kubelet puts on a Pod's volumes: the directories an emptyDir starts as, and the files a Secret or a ConfigMap projects, with their owners and modes. |