Skip to content

cub unit blame

cub unit blame

Show what set each field of a unit, when, and why

Synopsis

Show, for every field of a unit's configuration, what set the value that is there: the operation, the revision, who ran it, and the change description they gave it.

Where 'cub unit get -o mutations' shows the mutations grouped by resource and path, this shows the fields, one per line, with the history joined onto each. It is the answer to "who set this, and why" for a value you are looking at.

A value that arrived from upstream is followed to where it was actually set. A field a variant took from its base reads as the base's change, and a field the base took from a rendered chart reads as that chart -- so "did the chart set this, or did we?" is one command rather than three.

A value a link resolved from another unit is followed into that unit the same way, to the field the link read: a needs/provides binding's provided path, or the one upstream path of a TransformPaths link. An Upsert link that copies the upstream's resources is followed as a merge is. A TransformPaths link that reads several paths or uses a getter, and an Upsert or Insert link that runs a transform invocation, computed the value from more than one field, and the walk ends at the link. 'cub unit path' shows the link either way.

Pass --no-upstream to report only this unit's own record, which names the upstream unit without reading it.

Columns: REF the field's short reference: pass it to 'cub unit path' for everything recorded about the field. The same field has the same REF in every revision of the unit and in every variant of it FLAGS one letter for each thing there is to know about the field, explained below PATH the field, in the same path syntax functions and links use SET BY the link, trigger, function, or external source that wrote it, or otherwise the operation that made the revision, such as UpdateUnit USER who made that change; "automation" for one made by no user WHERE the space whose change it was, after following upstream REV that space's revision number WHEN how long ago

-o wide adds VALUE, what is there now; FUNCTION, the function a link or trigger ran; MUT, the mutation number; VIA, the change in this unit that brought a value set upstream, such as the upgrade or the link that resolved it; and CHANGE ORDER, the ChangeOrder that made the change in this unit.

Flags: P protected: a local override, which a merge from upstream leaves alone G guarded: reasons are recorded for the value it holds, and an operation has to be cleared for them before it may overwrite it X conflict: a merge or resolve dropped an upstream change to the field F finding: a link's resolve could not do what it names here E validation error: a validating trigger failed a check that names the field, which blocks a release W validation warning: a validating trigger with --warn failed a check that names the field U an upgrade from upstream brought the value to this unit, through an UpgradeUnit link L another link set the value in this unit, by resolving or merging T a trigger set the value in this unit C the change in this unit was made by a ChangeOrder N not released: the value changed after the unit's last release, or the unit has never been released. Never shown in a space with no release target, which has nothing to release n needed: the value is to come from an upstream unit, through a NeedsProvides link, whether or not a link has bound it yet p provided: the value is offered to downstream units, through NeedsProvides links

U, L, T, C and N are about the change in this unit, which for a value set upstream is the merge that brought it here rather than the change SET BY names. n and p are lowercase because they are informational: they say what part the field plays in NeedsProvides links, not that anything is wrong or pending. --verbose prints the guard reasons, conflicts, findings, failed checks, and needed and provided attributes under each field.

Every toolchain is read: a Kubernetes manifest, and equally an AppConfig JSON, YAML, TOML, INI, Properties, or Env unit, or a ConfigHub one. The unit's data is read in its own format, and array elements are addressed the way that format addresses them -- by merge key where it has them ("?name=server" for a Kubernetes container), by position where it does not.

Use --path to ask about one field, --resource to restrict to one resource, and --verbose to see each change description and the full upstream chain rather than its end. -o json emits one object per field. 'cub variant blame' does the same for every unit of a variant.

Examples: 

  # Every field of a unit, and what set it.
  cub unit blame --space apptique-dev deployment-frontend

  # One field: did the chart set this, our base, or this variant?
  cub unit blame --space apptique-dev deployment-frontend --path spec.replicas

  # Every container image in the unit, with the change descriptions.
  cub unit blame --space apptique-dev deployment-frontend --path image --verbose

  # This unit's own record, without reading upstream.
  cub unit blame --space apptique-dev deployment-frontend --no-upstream

  # With the values, functions, and ChangeOrders.
  cub unit blame --space apptique-dev deployment-frontend -o wide

  # Everything about one field, by the REF blame printed for it.
  cub unit path --space apptique-dev deployment-frontend 3f9a2c1

cub unit blame <unit> [flags]

Options

  -h, --help                 help for blame
      --no-upstream          report this unit's own record without following a merge to where the value was set
  -o, --output string        Output format. One of: json, yaml, name, wide, mutations, jq=<expr>, yq=<expr>, custom-columns=<spec>
      --path string          only fields whose path contains this substring
      --quiet                No default output.
      --resource string      only fields of this resource, as <type>/<name> or <name>
      --select string        Comma-separated list of fields to retrieve and display. Entity IDs and Slug are always included. Example: "DisplayName,CreatedAt,Labels"
      --show-comments        include the comment-carrying pseudo-fields ($comment$...) that hold YAML comments
      --upstream-depth int   how many upstream units to follow before giving up (default 8)
      --verbose              Detailed output, additive with default output

Options inherited from parent commands

      --component string   the Component of --variant, when that names the variant alone; --variant <component>/<variant> says the same in one flag
      --context string     The context to use for this command
      --debug              Debug output
      --space string       space to operate in, by slug or UUID. Omitted, a list or bulk operation spans the organization and a single entity is named as <space>/<slug>; "*" means the same as omitting it
      --variant string     variant to operate in, as <component>/<variant>, or as <variant> with --component: the space naming that Component whose Variant label is <variant>. The same scope as --space, named by what it is rather than by the space's slug; the two cannot be combined

SEE ALSO