Skip to content

cub function exec

cub function exec

Invoke a list of functions

Synopsis

Invoke functions on units. Functions can be used to modify, validate, or query unit configurations.

To display a list of supported functions, run: 

  cub function list

To display usage details of a specific function, run: 

  cub function explain --toolchain TOOLCHAIN_TYPE FUNCTION_NAME

Example Functions:

  • set-container-image: Update container image in a deployment
  • set-int-path: Set an integer value at a specific path in the configuration
  • get-replicas: Get the number of replicas for deployments
  • set-replicas: Set the number of replicas for deployments
  • where-filter: Filter units based on a condition
  • vet-cel: Validate resources using CEL expressions

The syntax is the same as the cub function do command line, but without "cub function do" and without flags. An argument that holds whitespace is quoted with ' or ". A quote opens at the start of an argument, or straight after the = of a --name=value argument, and closes at the same character followed by whitespace or the end of the line; a quote anywhere else is part of the argument. Inside a quoted argument, write the quote that whitespace follows with a backslash before it.

Like do, exec accepts any kind of function and applies no kind restriction to the list, which is the point of it: one request can inspect, mutate, and validate. For a single invocation, prefer cub function get, set or vet.

Example: 

  cub function exec --space my-space functions.txt --where "Slug = 'mydeployment'"

Where functions.txt contains: 

set-replicas 3
set-container-image nginx nginx:v234
set-namespace myns
vet-cel "r.kind != 'Deployment' || r.spec.replicas > 1"

cub function exec file [flags]

Options

      --change-desc string            change description
      --changeset string              changeset to associate units with
      --clearance stringArray         class of guarded reason this change is cleared for, as KEY, KEY=VALUE[;VALUE...], KEY!=VALUE[;VALUE...], or !KEY to refuse any path carrying KEY (repeatable). A guarded path this does not cover is not written, and the withheld change is reported as a conflict
      --dry-run                       dry run mode: execute functions but skip updating configuration data
      --filter string                 Filter entity to apply to the list. Specify as 'space/filter' for cross-space filters or just 'filter' for current space. Supports both slugs and UUIDs. The filter will be combined with any --where clause using AND logic. Examples: "production-filters/security-check", "my-filter-uuid", "validation-rules"
      --guard stringArray             reason to record on the paths this change writes, as KEY=VALUE (repeatable). A later operation must be cleared for it before overwriting those paths, this one included, so --clearance has to cover it. Adds and overwrites only; retiring a guard is cub unit set-guard --remove-guard
  -h, --help                          help for exec
      --include-conflicts             pass each unit's outstanding merge conflicts to the functions, for functions that reason about them (e.g. vet-no-merge-conflicts)
      --include-hidden string[="*"]   Also select hidden entities, to list or to act on: those hidden for the given HiddenReasons, comma-separated, as in --include-hidden=BackingUnit, or for any reason when given no value or "*". ConfigHub/YAML Units, which hold the configuration of other entities, are hidden with the reason BackingUnit. A --where naming entities by Slug or ID selects them whether hidden or not
      --include-link-findings         pass what the resolves of each unit's links could not do to the functions, for functions that reason about it (e.g. vet-no-link-findings)
      --invocation strings            execute invocations by UUID, slug, or space/slug (can be repeated or comma-separated)
      --other-data-source string      additional data source to pass to functions (e.g., LastReleasedRevisionNum); defaults to the sources each function expects
  -o, --output string                 Output format. One of: json, yaml, name, wide, mutations, jq=<expr>, yq=<expr>, custom-columns=<spec>
  -O, --output-file string            Write payload to FILE. Accepts {space}, {unit}, {section} placeholders.
      --protect                       record the paths this change writes as protected local overrides, so a later merge from upstream does not overwrite them; by default a change claims nothing and each path keeps the protection it already has
      --quiet                         No default output.
      --resource string               the one resource to operate on, as <kind>/<name> or <kind>/<namespace>/<name>, such as Deployment/backend. The kind is matched in any case and takes kubectl's .group suffix (Ingress.networking.k8s.io) when the kind alone is ambiguous. It has to match exactly one resource among the units --space, --variant and --where select, so a name held in several namespaces needs its namespace
      --resource-type string          resource-type filter
      --revision string               target a specific revision (format: unit-slug/revision-number, e.g. mydeployment/3)
      --show string                   Select which part of the function response to display. One of: output, values, data
      --timeout string                completion timeout as a duration with units, such as 10s or 2m (default "10m0s")
      --toolchain string              Toolchain type for the function invocations (default "Kubernetes/YAML")
      --trigger strings               execute triggers by UUID, slug, or space/slug (can be repeated or comma-separated)
      --unit strings                  target specific units by slug or UUID (can be repeated or comma-separated)
      --update-validation-results     update ValidationErrors and ValidationWarnings on units based on trigger results (requires --trigger)
      --verbose                       Detailed output, additive with default output
      --wait                          wait for completion (default true)
      --where string                  Filter expression using SQL-inspired syntax. Supports conjunctions with AND. String operators: =, !=, <, >, <=, >=, LIKE, NOT LIKE, ILIKE, ~~, !~~, ~, ~*, !~, !~*. Pattern matching with LIKE/ILIKE uses % and _ wildcards. Regex operators (~, ~*, !~, !~*) support POSIX regular expressions. A related entity is referenced by prefix, as in "UpstreamUnit.Slug = 'base'"; when the reference names a list, a * segment matches any element, as in "FromLink.*.Slug = 'upgrade-app'". Examples: "Slug LIKE 'app-%'", "DisplayName ILIKE '%backend%'", "Slug ~ '^[a-z]+-[0-9]+$'"
      --where-data string             where data filter
      --where-resource string         filter which resources the function operates on
      --worker string                 worker to execute the function

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
      --executor-space string   Space ID or slug whose executor to use for builtin functions (org-level only)
      --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