cub function do
cub function do
Invoke one function
Synopsis
Invoke a function on units in a space, or across all spaces without --space.
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
# Name the resource rather than the unit, in the base variant of the web component.
# --resource finds the one unit holding that Deployment and runs on that resource alone.
cub function do --variant web/base --resource Deployment/backend set-replicas 3
# 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='.Output[].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, 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 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)
--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
- cub function - Function commands