Skip to content

cub function do

cub function do

Invoke one function

Synopsis

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

Functions can be used to modify, validate, or inspect unit configurations. Use cub function set, cub function vet, or cub function get to validate that the invoked functions perform the desired type of operation.

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
  • 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

  # Use yq function to get container image from a deployment
  cub function do \
    --space my-space \
    --where "Slug = 'my-deployment'" \
    --show output \
    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-celexpr '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
      --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"
  -h, --help                       help for do
      --invocation strings         execute invocations by UUID, slug, or space/slug (can be repeated or comma-separated)
      --livestate-type string      Invoke the function on the live state and use the flag value as the toolchain type for live state.
      --other-data-source string   additional data source to pass to functions (e.g., LiveRevisionNum)
  -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.
      --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. 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

SEE ALSO