cub function do

Invoke one function

Synopsis

Invoke a function on units in a space, or across all spaces if the selected space is "*".

This is the mixed escape hatch: it accepts any kind of function. Prefer the verb that matches the kind -- cub function set for mutating functions, cub function get for non-mutating ones, cub function vet for validating ones. Those reject a function of the wrong kind before invoking anything, so a misremembered name is an error rather than an unintended write. Reach for do only when a single command must invoke functions of more than one kind.

Function argument values may be simply listed in order so long as no optional parameters are skipped. Parameters may be specified out of order using the "--parameter-name=value" syntax. These are not cub flags, so specify "--" before the function name if using that syntax for function arguments.

To display a list of supported functions for each ToolchainType, 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
get-yq: Read a value with a yq expression
where-filter: Filter units based on a condition
vet-cel: Validate resources using CEL expressions

Examples:

  # Use set-container-image to update container image in a deployment
  cub function do \
    --space my-space \
    --where "Slug = 'my-deployment'" \
    set-container-image nginx nginx:mainline-otel \
    --wait

  # Read the container image with get-yq. Non-mutating, so cub function get
  # would be the better verb; do accepts it too.
  cub function do \
    --space my-space \
    --where "Slug = 'my-deployment'" \
    --show output \
    get-yq '.spec.template.spec.containers[0].image'

  # Use set-int-path to update replica count for a deployment
  # There's also set-replicas function to do the same
  cub function do \
    --space my-space \
    --where "Slug = 'headlamp'" \
    set-int-path apps/v1/Deployment spec.replicas 2 \
    --wait

  # Get replica counts
  cub function do \
    --space my-space \
    get-replicas \
    --quiet \
    --show output -o jq='.[].Value'

  # Filter deployments with more than 1 replica
  cub function do \
    --space my-space \
    where-filter apps/v1/Deployment 'spec.replicas > 1' \
    --quiet \
    --show output -o jq='. as $e | .Output[] | select(.Passed == true) | {space: $e.SpaceSlug, unit: $e.UnitSlug}'

  # Validate deployment replicas using CEL
  cub function do --space my-space \
    vet-cel 'r.kind != "Deployment" || r.spec.replicas > 1' \
    --quiet \
    --show output -o jq='. as $e | .Output[] | select(.Passed == true) | {space: $e.SpaceSlug, unit: $e.UnitSlug}'

cub function do <function> [<arg1> ...] [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. Adds and overwrites only; retiring a guard is cub unit set-guard --remove-guard
  -h, --help                       help for do
      --include-conflicts          pass each unit's outstanding merge conflicts to the functions, for functions that reason about them (e.g. vet-no-merge-conflicts)
      --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)
  -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-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-apply-gates         update ApplyGates 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

      --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 ID to perform command on

cub function do

cub function do

Synopsis

Options

Options inherited from parent commands

SEE ALSO