harnesscontract

package
v0.0.0-...-8cfec81 Latest Latest
Warning

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

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

README

The external-harness contract

external-harness.yaml lists what a harness outside this repository may read from a deployed mesh: metric names, their labels and the closed sets of label values, the fields of a log line, the fields of the proxy's HTTP access log a harness reads, the annotations and ports a workload manifest names, and the chart objects a harness rolls or reads. (Until version 3 it also listed one Envoy stat prefix; see "Versions".)

A harness that lives in this repository changes in the same pull request as the code it reads. One that lives elsewhere does not, and the first sign of a rename would be a query that returns nothing, which often reads exactly like a healthy zero. The contract replaces that atomicity: the names are written down once, tests hold the code to them, and the harness pins the contract version it was written against.

Which version a deployed mesh satisfies

The aether chart is packaged with the contract's version, and the agent DaemonSet says it in an annotation on its own metadata (the entry object.annotation.harness_contract_version). A harness reads it before a run and compares it with the version it pins:

kubectl -n aether-system get daemonset aether-agent \
  -o jsonpath='{.metadata.annotations.aether\.io/harness-contract-version}'
  • It identifies the contract, not the build: the value is the version of this file at the commit the chart was packaged from, charts of different versions carry the same value while version stays, and it says nothing of the images that run.
  • No answer is "not known", never a version: a chart from before the annotation existed (earlier than 2.4.28), or one rendered from the source tree instead of from the package.
  • It is never on a pod template. A bump of version changes one annotation of one object at the next upgrade and replaces no pod (//charts/aether:aether_harness_contract_version_rolls_no_pod_test).

The number has no second copy: a build step of //charts/aether reads the top-level version: line of this file into the package, and nothing under charts/ is edited at a bump. Keep that line as it is written, alone on its line and unquoted; the step fails the build otherwise.

The rule

Change the code and external-harness.yaml together, in one pull request, and say so in its description.

Change version
An entry is removed bump
An entry changes meaning: a renamed metric, label, field or object; a label value removed from a closed set, or added to one; a field that changes type or unit; another rolling-update strategy; a metric that keeps its name and labels and counts something else, or is absent under other conditions bump
A label added to a metric, or removed from it bump
A render made with other set pairs, release or namespace bump
A new entry, a new object of a render no bump
A new field on a log line that keeps every field it had (add it to fields) no bump
A field of an access log listed for the first time (the record had it; the contract now promises it) no bump
A listed field of an access log that is renamed, dropped, or rendered by another format operator; another log_name; a reporter added or removed bump
Something more said of an entry that was said of nothing before: a key it did not have, one more pod label or container of an object, one more thing a container is held to no bump
checked_by, the order of a list, notes or a comment reworded without saying anything else no bump
What an entry MEANS, changed in notes, a comment or the code's behaviour while every key stays as it was (what a gauge counts, when a series is absent) bump, and no check asks for it: see below

A new value in a closed set is a change of meaning because a harness branches on the set: a grader that knows four reason values has to decide what a fifth one is, and until it does it can only fail. A new label on a metric is one for the same reason: a harness selects one series by its labels, and the selector it wrote now matches several.

The bump is a test

external-harness.lock.yaml holds, for the contract's current version, one line per promise: <entry id> <key> (and one more word per member where the contract says the set is open: the fields of a log line, an object's pod labels and containers, what a container is held to) with a digest of what is promised there. TestVersionBump in //test/harnesscontract:harnesscontract_test compares the two files:

  • A line of the lock that the contract no longer has, or whose digest no longer matches, is a promise a harness written against this version relied on. The test fails, names the entry and the key, and asks for the bump. It does not print a digest: there is nothing to paste that makes it pass without the bump.
  • With version bumped by one, the test prints the whole lock for the new version. Replace the file with it in the same change.
  • A promise the contract makes that the lock does not hold is new. The test prints the lines to add to the lock; version stays.
  • The lock is written exactly as the test prints it: the header, then one promise to a line, sorted. A lock that holds the right promises in another shape fails, and the test prints the whole file. The comparison with the base (below) reads the lock line by line, so its form is part of the check.

That test reads both files from one checkout, so on its own it cannot see a change made to both: an entry removed together with its lines, or a promise changed and its digest computed by hand. (A line deleted alone does not pass: the test asks for it back.) scripts/check-harness-contract-bump.sh closes that. The chart-version-bump job of ci.yaml runs it on every pull request with the base commit: every promise line of the lock at the base is still in the lock, unchanged, or version is higher than at the base.

So the table above is what the two checks decide, with one limit, and it is a real one. The lock holds the keys of an entry: names, types, sets, fields. What an entry means beyond its keys is written in notes and comments (what a gauge counts, when a series is absent and when it is zero, the entries under "What is review-only"), and prose has no line. A change of meaning that leaves every key alone, made in the code's behaviour and described in notes, passes both checks with version unchanged. Version 2 was such a change: a gauge kept its name, type and labels and counts something else. It is still a bump: whoever changes what an entry means bumps version by hand, and whoever reviews a diff of notes asks whether the meaning moved. A bump made for that reason goes through the same steps as any other (the test prints the new lock).

Every bump, whichever way it was found, gets a row in "Versions" below: that table is the one place that says what a version changed and what a harness pinned to an earlier one has to do.

Versions

What each bump changed, for whoever maintains a harness pinned to an earlier one.

version Change What a harness has to change
4 The entry envoy.capture.anyport_downstream_cx is removed. Chart 3.0.0 removes the any-port chain of the capture listener (cap_tcp_anyport_<cluster>): a raw-TCP service is reached on its declared ports and on the TCP mesh port only, and a connection to any other port of its address is no longer delivered to it (docs/runbook.md, "Chart 3.0.0"). No chain carries the stat prefix cap_tcp_anyport_, so tcp.cap_tcp_anyport_<cluster>.downstream_cx_total (stored as envoy_tcp_cap_tcp_anyport_.*_downstream_cx_total) has no series on 3.0.0 and later. Stop reading the counter: on 3.0.0 an absent series does not mean "no client used an undeclared port", it means the chain does not exist. A harness that graded on it being zero drops that check; one that dials a raw-TCP service on a port it does not declare must dial a declared port. A harness that addresses an HTTP service as <name>:18081, or sends the proxy port (127.0.0.1:18081) a Host without a port, moves to <name>:<declared port>: 18081 is the mesh's HTTP proxy port, not a port of a service, and chart 3.0.0 stops reading it, and a port-less name, as "the port the pods declare". To find such clients before upgrading, read the counter on 2.6.x, knowing that it undercounts: it does not move for a port number that another service declares as raw TCP.
3 The renders of the aether chart (chart.aether, chart.aether.agent_surge) pass clusterName. Chart 2.6.0 has no default for it and refuses to render without it (docs/runbook.md, "Chart 2.6.0"). Nothing else of those renders changed: the same objects, names, labels, arguments and roll strategies. Pass clusterName wherever the harness installs, upgrades or renders the chart. For a cluster that already runs the mesh it is the name that cluster runs with, read from the agent DaemonSet's --cluster-name argument; a different name is a rename of the cluster, with the consequences that runbook section lists.
2 agent.xds_acked_tls_clusters keeps its name, type and labels and means something else (#1508). It was the counts of the last snapshot whose cluster update the proxy acknowledged. It is the count of the clusters the proxy has accepted, each at the version it last acknowledged or stated. Do not read it as "the proxy holds the newest snapshot" after any cluster ACK: a rejected cluster stays at its accepted version through later ACKs, so the gauge can stay above agent.snapshot_tls_clusters for as long as the proxy rejects. Treat an absent series as "not known", and expect it to become absent AFTER having had samples, while the proxy holds a cluster whose pin state the agent cannot determine: a grader that takes a missing series for zero, or that carries the last sample forward, is wrong there. The entry's notes have the full statement.
1 The first version (#1535).

How an entry is tied to the code

Every entry has a checked_by: the Bazel test that compares it with the code that produces the thing, a list of them when several tests hold it, or review-only. Each test an entry names lists the entry among the ids it holds (Contract.Owns in a Go test, ids of a helm_contract_test) and fails when it does not, so checked_by is every test that fails when the entry and the code part. For a chart test the contract does not even load unless the two agree: an entry a render refers to names that render's test, and an entry that names a chart test is referred to by one of its renders.

Entries Compared with Test
metrics of the agent The real instruments, collected after every series was recorded: registered name, type, attribute keys, and the values of each closed label in both directions //agent/internal/xds/cache/cachemetrics:cachemetrics_test
metrics of the prober, resource_attributes service.name Every tier* and result* string constant of prober.go (read from the source, so a new one cannot be forgotten) recorded through the real record(); the resource the prober builds //prober/internal/prober:prober_test
log_lines A burst written by the real fail log with the real cap and window, then flushed as a stopping prober does; the lines are parsed as a harness parses them (marker, one JSON object, exact keys in order, RFC 3339 times, the summary's t and window_start) //prober/internal/prober:prober_test
access_logs The access log the real builder makes, for each reporter: its log_name, the field that names the reporter and the two values the code has for it, and every field the entry lists with the Envoy format operator that renders it. What Envoy renders for an operator, and that a store holds the record, are not compared //agent/internal/xds/proxy:proxy_test
envoy_stats None since version 4. (The one entry was the stat prefix of the any-port chain of a capture listener, which chart 3.0.0 removed; //agent/internal/xds/proxy:proxy_test now holds that no capture chain carries that prefix.)
names The Go constant the product itself uses //test/harnesscontract:harnesscontract_test, and //agent/internal/xds/xdsconst:xdsconst_test for the one constant that is internal to the agent
charts helm template of the packaged chart, run with the release name, namespace and --set pairs the entry gives //test/harnesscontract:{aether,prober,udsecho}_chart_test
resource_attributes k8s.node.name The keys OTEL_RESOURCE_ATTRIBUTES sets in the rendered agent and prober containers. The chart entries do not repeat the attribute: each container lists the entry's id (resource_attributes), and the chart test reads the key from the entry //test/harnesscontract:harnesscontract_test holds the link (every component has a container that refers to the entry, and no other container does); //test/harnesscontract:{aether,prober}_chart_test compare with the render
names mesh.default_domain Besides the Go constant: the --mesh-domain argument the aether chart renders for the agent and the mesh-DNS daemon when meshDomain is left at the chart's default, and the one the prober chart renders when probe.meshDomain is left at its default (a container's args maps the flag to the entry's id) //test/harnesscontract:{aether,prober}_chart_test, with harnesscontract_test holding the link for the agent
names port.outbound_http Besides the Go constant: the --egress argument the prober chart renders when probe.egress is left at its default (args maps the flag to a pattern, 127.0.0.1:<port.outbound_http>) //test/harnesscontract:prober_chart_test
names csi.driver Besides the Go constant: the name of the CSIDriver object the aether chart renders (the object has name_from: csi.driver in place of a name), and the kubelet plugin directory of the uds-csi DaemonSet: a hostPath volume of the path <--kubelet-root of the uds-csi container>/plugins/<csi.driver>, mounted by that container at that same path, which is where the plugin writes its socket and where the kubelet looks (host_paths: ["<arg:--kubelet-root>/plugins/<csi.driver>"]; a pattern without <arg:...> holds only the end of the path) //test/harnesscontract:aether_chart_test
names object.annotation.harness_contract_version No Go constant: only the chart writes the key. The agent DaemonSet of the aether chart's render has contract_version_annotation: <the entry>: its own metadata carries an annotation of that key whose value is the contract's version as a string, the version being the one this package loads (the chart reads it by a build step of its own, so the two reads are independent); the key is not a label of the object, not on its pod template, and on no other object of the render. Both packagings of the chart are rendered (other_packagings) //test/harnesscontract:aether_chart_test
names pod.label.managed Besides the Go constant: the label the controller's two pod webhooks select by in the aether chart's render (webhooks of the render's one MutatingWebhookConfiguration says, for each webhook, which of its two selectors selects by the entry: that selector is exactly the one label with the value "true", with no other label and no expression, and the webhook's other selector is empty, since every further requirement narrows what the webhook sees). Both webhooks ignore failures, so another key there would fail silently //test/harnesscontract:aether_chart_test
resource_attributes service.name of the prober Besides the resource the prober builds: the rendered prober container is given neither service.name in OTEL_RESOURCE_ATTRIBUTES nor OTEL_SERVICE_NAME, because the environment can replace what the code sets. OTEL_SERVICE_NAME is an explicit override and always does, so that rule is the one that matters; service.name in OTEL_RESOURCE_ATTRIBUTES no longer renames the prober (#1562, held by the prober's own test), and is refused here as well so that a chart never says a name the component ignores. A container whose OTEL_RESOURCE_ATTRIBUTES comes from valueFrom, or that has any envFrom, fails too: what cannot be read could carry either (the container lists the entry in code_resource_attributes) //test/harnesscontract:prober_chart_test

The last six rows exist because a Go constant is not always what is deployed (and one name has no constant at all). A component can be given the name by its chart (a flag, an environment variable), the chart can write the name a second time (an object it renders), or the chart's own defaults can spell it. Comparing the entry with the constant alone then passes while a default install does something else. When you add an entry, ask which of these holds; when one does, tie the entry to the render as well.

A tie is a reference under charts to another entry: name_from, args, resource_attributes, code_resource_attributes, host_paths, webhooks, contract_version_annotation. It is not a promise to a harness (an object's name is the same whether the contract writes it out or takes it from an entry), so the lock does not hold it, and writing the literal in its place changes nothing today. It would change the next rename: the entry moves, the chart stays, and no test compares the two any more. TestTies in harnesscontract_test therefore holds the contract to the list of its ties (ties in contract_test.go), in both directions: a tie that is gone fails, and a new one is added to the list. Neither needs a version bump.

The lock is written to match. Where a promise is made through a tie, its line is named and digested by what the tie comes to, never by the id of the entry: an object's name, the value an argument is run with, the path a host path pattern comes to, the attribute a container is given or is not to be given, the label a webhook selects by, the key of the annotation an object says the contract's version under (the version itself is in no line: every version says its own). So a tie moved to another entry that says the same is no bump (only ties changes), and the same tie coming to something else is one.

stored_name is checked against the usual OTLP-to-Prometheus translation of otel_name, computed by the test. Whether a given pipeline applies that translation is not something this repository can test.

Run them all:

bazel test //test/harnesscontract:checks

//test/harnesscontract:harnesscontract_test also fails when a checked_by names a test that is not in that suite, when a promise changed and version did not (above), and refuses a contract that is not well formed (an unknown key, an id used twice, an entry without checked_by, a reason that is in no class or in two, a chart test named by an entry it compares with nothing).

What is review-only
  • What joins two access-log records. That the caller's proxy and the destination's proxy log the same x_request_id for one request, and that the caller keeps it across its retries, is Envoy's request-id handling with the connection managers as the agent configures them. The test holds the field and its operator, not the join.
  • What a pipeline does to a name. The node and job labels of a stored series come from OpenTelemetry resource attributes (k8s.node.name, service.name) through the metrics pipeline's own configuration. That the product sets the attribute is checked (the table above); the label it becomes is the pipeline's. The same would hold for the stored name of an Envoy stat, of which the contract lists none since version 4: only the prefix the agent chooses can be tied to code.
  • The meaning of the two halves of reason (reason_classes): under which reasons the node published no TLS at all, and under which it published TLS that checks no server identity. The code states it in comments only.
  • The name of a generated mesh Service (the service's name, in the service's namespace). Only its label is tied to a constant.
  • A promise made only in prose. notes and comments have no line in the lock, so the version bump for a change of meaning written only there is kept by review.
  • The names the prober and udsecho charts put on their own pods are not the contract's to hold, and are not kept by review either: the mesh label, the annotations and the CSI driver of a volume are literals in those templates, and the charts' own helm_mesh_names_test targets compare them with the Go constants (charts/README.md). The contract compares the same names with the same constants from its side.

When a contract test fails

The message names this file and the rule. Then:

  1. You renamed or removed something on purpose. Update the entry, bump version if the table above says so, and say in the pull request description that the contract changed, so whoever maintains a harness can find the change.
  2. You did not mean to change it. The test just told you a harness reads it.

Adding an entry

Add it to the YAML with a checked_by, then make that test know it: each owning test declares the ids it holds (Contract.Owns), and fails when the contract assigns it an entry it has no check for. Prefer comparing with what the code really emits (an instrument's collected series, a line the real formatter wrote, a render) over comparing two constants. Then run //test/harnesscontract:harnesscontract_test: it prints the lines the new entry adds to external-harness.lock.yaml.

A metric label is on every series unless it has when: the test looks at each series on its own, because a harness selects one series by its labels.

For a chart object, write the YAML and add its id to the ids of that chart's helm_contract_test in BUILD.bazel: the render options and the expectations are both read from the entry, and ids is the test's list of what it holds (it fails when the two differ, in either direction). When a container must be given something another entry already names (a resource attribute, a name passed as a flag), or an object is named by one, refer to that entry by id (resource_attributes, args, name_from, contract_version_annotation) instead of writing the string again, add the id to ids as well, and add the chart test to that entry's checked_by. Mind which namespace a chart puts its objects in: udsecho takes it from its namespace value, not from the release. The chart tests live here and not in charts/<chart>/BUILD.bazel on purpose: a change under charts/ needs a chart version bump, and adding a contract entry is not a chart change.

Removing an entry

Removing an entry while the code still emits the thing fails the owning test (... no longer has the entry "<id>" ..., and the code it describes is still here), and TestVersionBump fails whether the code still emits it or not (... no longer has the entry "<id>", which it promised at version N). Remove the check in the same change, bump version, and replace the lock with the one the test then prints: the diff shows the entry, its check, the version and the lock moving together. For a charts entry or one of its objects the check is its id in the test's ids.

What is not in the contract

The last section of the file lists names a harness uses that belong to its own workloads and tools (a load generator's failure lines and counters, its client loops' log lines, its own labels). The product does not emit them.

Documentation

Overview

Package harnesscontract loads external-harness.yaml: the checked-in list of what a harness outside this repository may read from a deployed mesh (metric names and labels, log-line fields, chart object names).

It is test support. The tests that hold the code to the contract live with the code that owns each name (the `checked_by` of an entry names the Bazel test); they load the contract through this package, so a rename fails with a message that names the contract file. README.md says how each kind of entry is tied.

Index

Constants

View Source
const (
	ResourceEnv    = "OTEL_RESOURCE_ATTRIBUTES"
	ServiceNameEnv = "OTEL_SERVICE_NAME"
)

ResourceEnv is the environment variable the OpenTelemetry SDK reads resource attributes from, as comma-separated key=value pairs. ServiceNameEnv is the one it reads service.name from, ahead of ResourceEnv.

View Source
const (
	TypeCounter = "counter"
	TypeGauge   = "gauge"
)

Metric types, as the contract spells them.

View Source
const File = "test/harnesscontract/external-harness.yaml"

File is the contract's path in the repository. Failure messages name it.

View Source
const LockFile = "test/harnesscontract/external-harness.lock.yaml"

LockFile is the path in the repository of the contract's lock: the promises of the contract's current `version`, one line each.

View Source
const ReviewOnly = "review-only"

ReviewOnly is the checked_by of an entry no test in this repository can hold to the code.

View Source
const Rule = "Change the code and " + File + " together, in one pull request, and say so in its description. " +
	"Removing an entry or changing what it means bumps the contract's `version`; adding one does not. " +
	"See test/harnesscontract/README.md."

Rule is appended to every failure a contract check reports.

Variables

This section is empty.

Functions

func Errorf

func Errorf(tb testing.TB, format string, args ...any)

Errorf reports a difference between the code and the contract. Every such failure names the contract file and the rule, so whoever renamed something learns from the test log alone that a file outside the package has to change with it.

func OwnedIDs

func OwnedIDs(renders []Render, ids []string) []string

OwnedIDs compares the ids of renders, of their objects and of the entries of other sections their containers refer to (a resource attribute, the name an argument takes its value from) with the ids a chart test declares it holds (the `ids` of its helm_contract_test), in both directions, and returns what differs.

func StoredName

func StoredName(otelName, metricType string) string

StoredName is the name a Prometheus-compatible store holds for an OpenTelemetry instrument of the given type with no unit: every character outside [a-zA-Z0-9_:] becomes an underscore, and a monotonic counter gets the suffix _total unless it has it already.

Types

type AccessLog

type AccessLog struct {
	ID        string `json:"id"`
	Component string `json:"component"`
	// LogName is the record's `log_name`, by which a store keeps the stream
	// apart from the proxy's other logs.
	LogName string `json:"log_name"`
	// ReporterField is the field that says which proxy wrote the record, and
	// Reporters the closed set of its values.
	ReporterField string            `json:"reporter_field"`
	Reporters     []string          `json:"reporters"`
	Fields        map[string]string `json:"fields"`
	Notes         string            `json:"notes"`
	CheckedBy     CheckedBy         `json:"checked_by"`
}

AccessLog is a stream of structured access-log records a proxy exports: one record per request, its fields the attributes of the record.

Fields is not the whole record. It lists the fields a harness may read, each with the Envoy format operator that renders it, which is what the field means. The set is open: a record has more fields than these, and one the contract gains is a new promise.

type CheckedBy

type CheckedBy []string

CheckedBy is an entry's `checked_by`: the Bazel tests that hold the entry to the code, or ReviewOnly alone. The contract writes one test as a string and several as a list. Every test it names declares the entry among the ids it holds (Contract.Owns, or the `ids` of a helm_contract_test), so the list is every test that fails when the entry and the code part.

func (CheckedBy) Has

func (c CheckedBy) Has(target string) bool

Has reports whether target is one of the tests.

func (*CheckedBy) UnmarshalJSON

func (c *CheckedBy) UnmarshalJSON(data []byte) error

UnmarshalJSON reads one label or a list of them.

type Container

type Container struct {
	Name string `json:"name"`
	// EnvContains maps an environment variable to substrings its value holds.
	EnvContains map[string][]string `json:"env_contains"`
	// ResourceAttributes are ids of `resource_attributes` entries the container
	// is given in OTEL_RESOURCE_ATTRIBUTES. The key (and the value, when the
	// entry has one) is read from that entry, so the two cannot disagree.
	ResourceAttributes []string `json:"resource_attributes"`
	// CodeResourceAttributes are ids of `resource_attributes` entries the
	// component's own code sets. The environment can replace what the code
	// sets (OTEL_SERVICE_NAME always does; OTEL_RESOURCE_ATTRIBUTES does for a
	// component that reads the environment after its own attributes), so a
	// chart that gave the container the attribute could change what is deployed
	// while the code still says what the entry says: the container is given it
	// neither in OTEL_RESOURCE_ATTRIBUTES nor, for service.name, as
	// OTEL_SERVICE_NAME.
	CodeResourceAttributes []string `json:"code_resource_attributes"`
	// Args maps a command-line flag to the id of a `names` entry: the container
	// is run with `<flag>=<that entry's value>`. A value with `<id>` in it is a
	// pattern instead: the container is run with the flag set to that text,
	// each `<id>` replaced by the entry's value (`127.0.0.1:<port.outbound_http>`).
	Args map[string]string `json:"args"`
	// contains filtered or unexported fields
}

Container is a container of the object's pod template.

type Contract

type Contract struct {
	Version            int                 `json:"version"`
	Metrics            []Metric            `json:"metrics"`
	ReasonClasses      []ReasonClasses     `json:"reason_classes"`
	ResourceAttributes []ResourceAttribute `json:"resource_attributes"`
	LogLines           []LogLine           `json:"log_lines"`
	AccessLogs         []AccessLog         `json:"access_logs"`
	EnvoyStats         []EnvoyStat         `json:"envoy_stats"`
	Names              []Name              `json:"names"`
	Charts             []Render            `json:"charts"`
	NotContract        []NotContract       `json:"not_contract"`
}

Contract is external-harness.yaml.

func Load

func Load() (*Contract, error)

Load parses the embedded contract. An unknown key is an error: a misspelt field would otherwise be a check that silently never runs.

func MustLoad

func MustLoad(tb testing.TB) *Contract

MustLoad loads the contract or fails the test.

func (*Contract) AccessLog

func (c *Contract) AccessLog(tb testing.TB, id string) AccessLog

AccessLog returns the access-log entry with the given id, or fails the test.

func (*Contract) CheckLock

func (c *Contract) CheckLock(lock *Lock) []string

CheckLock compares the contract with the lock and returns what differs.

At the lock's version, every promise in the lock is still made and still says the same (anything else needs a version bump), and every promise the contract makes is in the lock (a new one is added to it, with no bump). One version on, the lock is replaced as a whole.

func (*Contract) CheckLockFile

func (c *Contract) CheckLockFile(data []byte) []string

CheckLockFile compares the contract with the lock file as it is written: it parses, holds what CheckLock holds, and is byte for byte the file Lock writes.

The form matters because scripts/check-harness-contract-bump.sh reads the lock at a pull request's base one line at a time. The same promises as an inline map, or indented otherwise, are the same lock to a YAML parser and no promise at all to that script.

func (*Contract) CheckNames

func (c *Contract) CheckNames(tb testing.TB, target string, code map[string]string, others ...string)

CheckNames compares the `names` entries assigned to target with the values the code has (id -> the Go constant), in both directions. others are the ids of the entries of other sections the same test holds with checks of its own: target's entries are exactly the names in code and those.

func (*Contract) EnvoyStat

func (c *Contract) EnvoyStat(tb testing.TB, id string) EnvoyStat

EnvoyStat returns the Envoy stat entry with the given id, or fails the test.

func (*Contract) HeldByChartTest

func (c *Contract) HeldByChartTest(target, name string, ids []string) []string

HeldByChartTest returns what differs between the contract and the chart test target, which renders the chart called name and declares in `ids` what it holds. Every render of the chart names the test in its checked_by; every entry whose checked_by names the test is one this chart's renders give it something to compare; and the ids are the ones OwnedIDs expects.

func (*Contract) IDs

func (c *Contract) IDs(target string) []string

IDs returns the id of every entry whose checked_by names target, sorted.

func (*Contract) Lock

func (c *Contract) Lock() []byte

Lock returns the lock of the contract as it is now: what external-harness.lock.yaml holds once a version bump is recorded.

func (*Contract) LogLine

func (c *Contract) LogLine(tb testing.TB, id string) LogLine

LogLine returns the log-line entry with the given id, or fails the test.

func (*Contract) Metric

func (c *Contract) Metric(tb testing.TB, id string) Metric

Metric returns the metric entry with the given id, or fails the test.

func (*Contract) Owns

func (c *Contract) Owns(tb testing.TB, target string, ids ...string)

Owns asserts that the entries whose checked_by names target are exactly ids: the test that calls it declares which entries it holds to the code.

Both directions matter. An entry assigned to this test that the test does not list is a promise nothing checks. An id the test lists that the contract no longer has was removed from the contract while the code that emits it is still here: removing an entry is a version bump, and the check goes with it.

func (*Contract) Promises

func (c *Contract) Promises() map[string]string

Promises returns everything the contract promises a harness.

The unit is chosen so that what README.md calls compatible adds promises and changes none, and everything else changes or removes one:

  • a key of an entry is one promise, whatever its value: a closed set of label values, a metric's labels, the classes of a reason set, the `set` pairs of a render. Adding to such a value changes it;
  • where the contract itself says the set is open, each member is its own promise: the fields of a log line (with whether the field is a time), the fields of an access log (with the format that renders each), the components of a resource attribute, an object's pod labels, its containers, and what each container is held to;
  • the order of a list is not a promise.

func (*Contract) RendersOf

func (c *Contract) RendersOf(name string) []Render

RendersOf returns the contract's renders of the chart called name.

func (*Contract) ResourceAttribute

func (c *Contract) ResourceAttribute(tb testing.TB, id string) ResourceAttribute

ResourceAttribute returns the resource-attribute entry with the given id, or fails the test.

func (*Contract) Targets

func (c *Contract) Targets() []string

Targets returns every test a checked_by in the contract names, sorted and without repeats.

func (*Contract) Ties

func (c *Contract) Ties() []string

Ties returns every place where the contract holds a chart to another entry instead of to a string of its own: `<object id> <key> ... <the entry's id, or the pattern that names it>`, sorted.

A tie is not a promise to a harness, so it is not in the lock: the name an object is rendered under is the same whether the contract writes it out or takes it from an entry. But it is what makes a rename of the entry reach the chart. TestTies holds the checked-in contract to the list of its ties, so one that is replaced by a literal fails there and not at the next rename.

func (*Contract) Validate

func (c *Contract) Validate() []string

Validate returns what is wrong with the contract as a document, whatever the code says: a missing version, an entry without an id or a checked_by, an id used twice, a label that is neither closed nor open, a reason partition that does not cover its label's closed set exactly once, a chart container that refers to an entry the contract lacks.

type EnvoyStat

type EnvoyStat struct {
	ID                string    `json:"id"`
	StatPrefix        string    `json:"stat_prefix"`
	Stat              string    `json:"stat"`
	StoredNamePattern string    `json:"stored_name_pattern"`
	Notes             string    `json:"notes"`
	CheckedBy         CheckedBy `json:"checked_by"`
}

EnvoyStat is an Envoy stat whose prefix the agent chooses.

type Label

type Label struct {
	Name   string            `json:"name"`
	Values []string          `json:"values"`
	Open   bool              `json:"open"`
	When   map[string]string `json:"when"`
}

Label is one attribute of a Metric: a closed set of Values, or Open.

Every series carries the label, unless When is set: then exactly the series whose other labels have the values When gives carry it, and no other does.

func (Label) On

func (l Label) On(s map[string]string) bool

On reports whether a series with these attributes carries the label.

type Lock

type Lock struct {
	Version  int               `json:"version"`
	Promises map[string]string `json:"promises"`
}

Lock is external-harness.lock.yaml: for the version it was written for, the name of every promise the contract made and a digest of what was promised.

func ParseLock

func ParseLock(data []byte) (*Lock, error)

ParseLock reads a lock. An unknown key or a promise listed twice is an error.

type LogLine

type LogLine struct {
	ID            string    `json:"id"`
	Component     string    `json:"component"`
	Marker        string    `json:"marker"`
	Fields        []string  `json:"fields"`
	TimeFields    []string  `json:"time_fields"`
	Notes         string    `json:"notes"`
	CapPerWindow  int       `json:"cap_per_window"`
	WindowSeconds int       `json:"window_seconds"`
	CheckedBy     CheckedBy `json:"checked_by"`
}

LogLine is a marker-prefixed, one-JSON-object log line.

func (LogLine) CheckFields

func (l LogLine) CheckFields(tb testing.TB, keys []string)

CheckFields compares the keys of one real log line (in the order the product wrote them) with the entry's field list.

type Metric

type Metric struct {
	ID         string    `json:"id"`
	Component  string    `json:"component"`
	OTelName   string    `json:"otel_name"`
	StoredName string    `json:"stored_name"`
	Type       string    `json:"type"`
	Labels     []Label   `json:"labels"`
	Notes      string    `json:"notes"`
	CheckedBy  CheckedBy `json:"checked_by"`
}

Metric is one instrument a harness queries.

func (Metric) CheckMetric

func (m Metric) CheckMetric(tb testing.TB, registeredType string, series []Series)

CheckMetric compares what an instrument really emits with its contract entry: the name it is registered with, the name a store holds for it, its type, and for every series its label names and, for a closed label, its values. series must hold every series the instrument can emit: the closed sets are compared in both directions, so a value the code emits and the contract lacks fails as surely as one the contract promises and the code never emits.

registeredType is the type of the instrument found under the contract's otel_name, or "" when no instrument has that name.

func (Metric) Label

func (m Metric) Label(name string) (Label, bool)

Label returns the metric's label called name.

func (Metric) LabelNames

func (m Metric) LabelNames() []string

LabelNames returns the metric's label names, sorted.

type Name

type Name struct {
	ID        string    `json:"id"`
	Value     string    `json:"value"`
	CheckedBy CheckedBy `json:"checked_by"`
}

Name is one string a harness writes into a manifest or a URL.

type NotContract

type NotContract struct {
	Name string `json:"name"`
	What string `json:"what"`
}

NotContract names something a harness uses that the product does not emit.

type Object

type Object struct {
	ID   string `json:"id"`
	Kind string `json:"kind"`
	// Name is the object's name, or NameFrom is the id of the `names` entry
	// whose value it is: an object the chart names after something the code
	// names too is held to that entry, not to a second copy of the string.
	Name          string            `json:"name"`
	NameFrom      string            `json:"name_from"`
	Namespace     string            `json:"namespace"`
	PodLabels     map[string]string `json:"pod_labels"`
	Containers    []Container       `json:"containers"`
	RollingUpdate *RollingUpdate    `json:"rolling_update"`
	// HostPaths are patterns, `<id>` standing for the value of a `names` entry:
	// the pod has a hostPath volume whose path ends with each.
	HostPaths []string `json:"host_paths"`
	// Webhooks maps the name of a webhook of an admission configuration to the
	// labels it selects by.
	Webhooks map[string]WebhookSelector `json:"webhooks"`
	// ContractVersionAnnotation is the id of the `names` entry whose value is
	// the key of an annotation on the object's OWN metadata, and the value of
	// that annotation is this contract's `version`: where a harness reads which
	// contract a deployed mesh satisfies. Never on the object's pod template,
	// where a version bump would replace every pod.
	ContractVersionAnnotation string `json:"contract_version_annotation"`
	// contains filtered or unexported fields
}

Object is one rendered object. Only what is set is checked.

type ReasonClasses

type ReasonClasses struct {
	ID        string              `json:"id"`
	Metric    string              `json:"metric"`
	Label     string              `json:"label"`
	Classes   map[string][]string `json:"classes"`
	CheckedBy CheckedBy           `json:"checked_by"`
}

ReasonClasses partitions a closed label set into the classes a harness grades differently.

type Render

type Render struct {
	ID        string            `json:"id"`
	Chart     string            `json:"chart"`
	Release   string            `json:"release"`
	Namespace string            `json:"namespace"`
	Set       map[string]string `json:"set"`
	Objects   []Object          `json:"objects"`
	CheckedBy CheckedBy         `json:"checked_by"`
}

Render is one `helm template` of a chart in this repository and the objects of that render a harness addresses.

func (Render) Check

func (r Render) Check(render []byte) []string

Check compares the render (the output of `helm` run with r.HelmArgs) with the objects the contract lists, and returns what differs. It never returns any part of the render other than the names of objects and containers, pod labels, the names of environment variables, the keys of the resource attributes one sets, and the names of command-line flags: a chart can generate key material at render time.

func (Render) HelmArgs

func (r Render) HelmArgs(chartPath string) []string

HelmArgs is the `helm` command line that produces the render from the packaged chart at chartPath. The --set pairs are sorted, so it is the same command every time.

type ResourceAttribute

type ResourceAttribute struct {
	ID         string    `json:"id"`
	Attribute  string    `json:"attribute"`
	Value      string    `json:"value"`
	Components []string  `json:"components"`
	Notes      string    `json:"notes"`
	CheckedBy  CheckedBy `json:"checked_by"`
}

ResourceAttribute is an OpenTelemetry resource attribute a pipeline may turn into a label.

type RollingUpdate

type RollingUpdate struct {
	MaxSurge       string `json:"maxSurge"`
	MaxUnavailable string `json:"maxUnavailable"`
}

RollingUpdate is a workload's rolling-update strategy, values as written.

type Series

type Series map[string]string

Series is one data point of an instrument, as a test collected it: its attributes.

type WebhookSelector

type WebhookSelector struct {
	Namespaces string `json:"namespaces"`
	Objects    string `json:"objects"`
}

WebhookSelector says which label a webhook selects by, and with which of its two selectors: each is the id of a `names` entry (and, once linked, that entry's value), a key of the selector's matchLabels with the value "true". The two are not interchangeable: one selects the namespaces whose pods the webhook sees, the other the pods themselves.

Directories

Path Synopsis
cmd
chartcheck command
Command chartcheck renders one chart the way the external-harness contract says (test/harnesscontract/external-harness.yaml, `charts`) and compares the render with the objects the contract lists.
Command chartcheck renders one chart the way the external-harness contract says (test/harnesscontract/external-harness.yaml, `charts`) and compares the render with the objects the contract lists.

Jump to

Keyboard shortcuts

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