GitOps schema reference

This page lists every field of the five object kinds that myriarchd reads from a Git repository, the template functions, the limits, and the codes under which validation reports problems. For the ideas behind the objects see the concepts. For the layout of a repository and the rules that apply to all objects see Git as the source of truth.

A test (TestGitOpsSchemaReference in internal/gitops) keeps this page complete: it fails if a field of the Go schema or an issue code of the validation packages is missing from the tables below, or if a table names something that no longer exists.

How to read the tables:

• The first column is the full YAML path, relative to the object. A list is written with [], so spec.waves[].percent is the field percent of every element of spec.waves.
• Type uses these names: string, int, bool, duration (a string in Go syntax such as 30s, 5m or 1h30m), list, map and object. A map of any is free-form: the contents are not checked against a schema.
• Required means the object is invalid without the field. “conditional” is explained in the description.
• Unknown fields are errors (unknown_field), except inside free-form maps.

Common fields

Every object has the same envelope, followed by the spec of its kind.

Fleet

Assigns agents to a blueprint, parameters, a target collector version, an update executor and rollout policies. See Fleets.

A policy name that is not default and does not exist is policy_not_found. If the policy default does not exist, the built-in policy applies (Rollouts).

Blueprint

A layered, parameterized collector configuration. See Blueprints.

The order of precedence for parameter values and the merge rules are explained in Blueprints.

RolloutPolicy

Controls how changes reach the agents of a fleet. See Rollouts.

Negative durations are policy_invalid. The built-in policy used when no default object exists is described in Rollouts.

Executor

Describes an external update path for the executor types webhook and awx. The executors updater and manual need no object. See Executors.

Violations of these rules are missing_field (a required field or block is absent) or executor_invalid (a value is wrong). Which secret names the server may read is decided by its configuration, see Executors.

Inventory

Adds server labels and parameter overrides to agents that match exact attribute values. See Inventory.

Sample agents

Files in samples/agents/*.yaml (or .yml) below the repository path describe example agents. They are not objects of myriarchd. myrctl validate and the server’s validation render every fleet for the sample agents that match it, and myrctl render --sample NAME renders for one of them. A file may contain several documents.

name: linux-edge-01
attributes:
  service.name: otelcol-contrib
  os.type: linux
  host.name: linux-edge-01.example.com
  site.type: edge
  site.id: edge-001
  site.timezone: Europe/Amsterdam
labels: {}

Unknown fields in a sample are unknown_field, a value that is not a scalar is invalid_field. A sample that matches no fleet is the warning sample_unassigned. A sample that matches several fleets of equal highest priority is the warning fleet_ambiguous.

From v0.2.0 on, a sample that is an OpAMP Bridge, because it has the service.name io.opentelemetry.operator-opamp-bridge or the attribute opentelemetry.io/opamp.bridge.mode, is never rendered and does not have to match a fleet. For every matching fleet without spec.bridge.manage it is the warning bridge_selected, with the name of the sample. The quickstart examples contain no Bridge sample.

Selector operators

Used by spec.selector.matchExpressions of a fleet and by wave selectors of a policy.

All conditions of a selector, matchAttributes and matchExpressions together, must hold. An unknown operator, a missing key or missing values are selector_invalid.

Template functions

Templates use the delimiters [[ and ]]. In addition to the functions below, the Go builtins and, or, not, eq, ne, lt, le, gt, ge, len and index are available. The argument that is processed comes last, so pipes work: .params.x | default "y". The rules for evaluation and the limits are in Blueprints.

The output of a function and of a template string is limited to 64 KiB. Further limits (range, compute time and the total amount of text a template may produce) are described in Blueprints.

Limits

myrctl applies the same file, count and node limits. It has no time budget.

Validation and issue codes

myrctl validate [DIR] (the default directory is .) validates the repository exactly as myriarchd does before it applies a revision, and renders every fleet for the matching sample agents. myrctl render prints the rendered configuration of one fleet for one agent. The flags are documented with the commands: myrctl validate and myrctl render.

Exit codes of both commands:

Text output. Each finding is one line: file:line: severity code: message (Object/name, path). A summary line follows, for example OK: 1 Blueprint, 3 Fleet, ...; 4 samples; 0 errors, 0 warnings, or FAILED: ....

JSON output. myrctl validate --output json prints one object with the keys

• valid: true when the exit code is 0,
• errors and warnings: the number of findings of each severity,
• objects: the number of objects per kind, for example {"Fleet": 3},
• samples: the number of sample agents,
• issues: the list of findings (never null).

Each finding has severity, code, message and, where known, file, line, path and object. This output fits annotations in CI systems. myrctl render --output json prints fleet, blueprint, layers, parameters, parameterSources (per parameter one of default, fleet, attribute, inventory or override), hash, config and issues.

myrctl validate --components FILE takes a component list (the format of examples/sim/components-otelcol-contrib-0.162.0.json) and enables the check unknown_component for all sample renderings. Without it, component names are not checked against a collector.

Issue codes. The codes are stable. The server shows the same codes in the UI and the API.