cub unit set-guard

Record the reasons a path's value is what it is

Synopsis

Set or remove guards on a unit's path annotations.

A guard names a class of reason a path holds the value it does, so that a later operation can be asked to know about that reason before overwriting it. The key names the class and is the matchable part; the value distinguishes cases within it. Two examples of the shape:

owner=transform-link this field is maintained by a link policy-exception=host-network this value breaks a default policy on purpose

A guard is enforced on every change to the unit's configuration data -- an edit, a function invocation, a trigger, a link, a merge: a change that is not cleared for the reasons at a path does not overwrite it, and reports what it withheld as a conflict. Editing the guards at a path that already carries some needs --clearance for those, on the same rule -- a clearance is the statement that the reasons are understood. Setting the first guard on a path needs none, since there is nothing yet to understand.

A guard may name a path -- or a resource -- the unit does not have. A guard is policy about the configuration rather than a statement about its current contents: guarding spec.template.spec.containers is as much about containers added next year as about the ones there now, and each of those inherits it.

Each --guard takes RESOURCE_TYPE:RESOURCE_NAME:PATH=KEY=VALUE and each --remove-guard takes RESOURCE_TYPE:RESOURCE_NAME:PATH=KEY. Leave PATH empty to guard the resource as a whole. Repeat either flag to edit several paths or resources at once, and combine them to add some guards and retire others in one revision. Setting guards creates a new revision only if they change.

A change can state its own reasons instead, without naming where: cub unit update --guard, cub function do --guard, and the Guards field on a link or a trigger take a bare KEY=VALUE and record it on the paths that change wrote -- the guard analogue of --protect. Use this command to guard a path no change of yours is writing, and to remove a guard, which no change can do.

Examples:

  # Say why this image is what it is: a link maintains it
  cub unit set-guard my-unit \
    --guard "apps/v1/Deployment:default/myapp:spec.template.spec.containers.?name=app.image=owner=transform-link"

  # Record a deliberate policy exception on the pod spec
  cub unit set-guard my-unit \
    --guard "apps/v1/Deployment:default/myapp:spec.template.spec=policy-exception=host-network"

  # Retire a guard whose reason no longer applies, saying the reason is understood
  cub unit set-guard my-unit \
    --remove-guard "apps/v1/Deployment:default/myapp:spec.template.spec=policy-exception" \
    --clearance "policy-exception=host-network"

cub unit set-guard <unit-slug> --guard <spec> [--remove-guard <spec> ...] [flags]

Options

      --clearance stringArray      class of guarded reason this edit is cleared for, as KEY, KEY=VALUE[;VALUE...], KEY!=VALUE[;VALUE...], or !KEY (repeatable). Required to edit a path that already carries guards
      --guard stringArray          guard to set, as RESOURCE_TYPE:RESOURCE_NAME:PATH=KEY=VALUE (repeatable)
  -h, --help                       help for set-guard
  -o, --output string              Output format. One of: json, yaml, name, wide, mutations, jq=<expr>, yq=<expr>, custom-columns=<spec>
      --quiet                      No default output.
      --remove-guard stringArray   guard to remove, as RESOURCE_TYPE:RESOURCE_NAME:PATH=KEY (repeatable)
      --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>
      --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

cub unit set-guard