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
- func Errorf(tb testing.TB, format string, args ...any)
- func OwnedIDs(renders []Render, ids []string) []string
- func StoredName(otelName, metricType string) string
- type AccessLog
- type CheckedBy
- type Container
- type Contract
- func (c *Contract) AccessLog(tb testing.TB, id string) AccessLog
- func (c *Contract) CheckLock(lock *Lock) []string
- func (c *Contract) CheckLockFile(data []byte) []string
- func (c *Contract) CheckNames(tb testing.TB, target string, code map[string]string, others ...string)
- func (c *Contract) EnvoyStat(tb testing.TB, id string) EnvoyStat
- func (c *Contract) HeldByChartTest(target, name string, ids []string) []string
- func (c *Contract) IDs(target string) []string
- func (c *Contract) Lock() []byte
- func (c *Contract) LogLine(tb testing.TB, id string) LogLine
- func (c *Contract) Metric(tb testing.TB, id string) Metric
- func (c *Contract) Owns(tb testing.TB, target string, ids ...string)
- func (c *Contract) Promises() map[string]string
- func (c *Contract) RendersOf(name string) []Render
- func (c *Contract) ResourceAttribute(tb testing.TB, id string) ResourceAttribute
- func (c *Contract) Targets() []string
- func (c *Contract) Ties() []string
- func (c *Contract) Validate() []string
- type EnvoyStat
- type Label
- type Lock
- type LogLine
- type Metric
- type Name
- type NotContract
- type Object
- type ReasonClasses
- type Render
- type ResourceAttribute
- type RollingUpdate
- type Series
- type WebhookSelector
Constants ¶
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.
const ( TypeCounter = "counter" TypeGauge = "gauge" )
Metric types, as the contract spells them.
const File = "test/harnesscontract/external-harness.yaml"
File is the contract's path in the repository. Failure messages name it.
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.
const ReviewOnly = "review-only"
ReviewOnly is the checked_by of an entry no test in this repository can hold to the code.
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 ¶
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 ¶
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 ¶
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) UnmarshalJSON ¶
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 ¶
Load parses the embedded contract. An unknown key is an error: a misspelt field would otherwise be a check that silently never runs.
func (*Contract) AccessLog ¶
AccessLog returns the access-log entry with the given id, or fails the test.
func (*Contract) CheckLock ¶
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 ¶
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 ¶
EnvoyStat returns the Envoy stat entry with the given id, or fails the test.
func (*Contract) HeldByChartTest ¶
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) Lock ¶
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) Owns ¶
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 ¶
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) 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 ¶
Targets returns every test a checked_by in the contract names, sorted and without repeats.
func (*Contract) Ties ¶
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 ¶
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.
type Lock ¶
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.
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.
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 ¶
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) LabelNames ¶
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 ¶
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 ¶
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.
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"`
}
RollingUpdate is a workload's rolling-update strategy, values as written.
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. |