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 by merges: a merge that is not cleared for the reasons at a path does not overwrite it, and reports what it withheld. 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.

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

      --context string   The context to use for this command
      --debug            Debug output
      --space string     space ID to perform command on

cub unit set-guard