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.

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-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
  • cel-validate: Validate resources using CEL expressions

Examples: 

  # Use set-image to update container image in a deployment
  cub function do \
    --space my-space \
    --where "Slug = 'my-deployment'" \
    set-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'" \
    --output-only \
    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 \
    --output-jq '.[].Value'

  # Filter deployments with more than 1 replica
  cub function do \
    --space my-space \
    where-filter apps/v1/Deployment 'spec.replicas > 1' \
    --quiet \
    --output-jq '.[].Passed' \
    --jq '.[].UnitID'

  # Set best-practice pod fields, other than for probes, to default values in all units in all spaces
  cub function do \
    --space "*" \
    -- \
    set-pod-defaults --pod-security=true --automount-service-account-token=true --security-context=true --resources=true --probes=false

  # Validate deployment replicas using CEL
  cub function do --space my-space \
    cel-validate 'r.kind != "Deployment" || r.spec.replicas > 1' \
    --quiet \
    --output-jq '.[].Passed' \
    --jq '.[].UnitID'

cub function do <function> [<arg1> ...] [flags]

Options

      --change-desc string      change description
      --changeset string        changeset to associate units with
      --data-only               show config data without other response details
      --display-mutations       display resource mutations
      --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)
      --jq string               jq expression, suppressing default output
      --json                    JSON output, suppressing default output
      --livestate-type string   Invoke the function on the live state and use the flag value as the toolchain type for live state.
      --output-jq string        apply jq to output JSON
      --output-json             show output as raw JSON
      --output-only             show output without other response details
      --output-values-only      show output values (from functions returning AttributeValueList) without other response details
      --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)
      --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)
      --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, 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
      --yaml                    YAML output, suppressing default output
      --yq string               yq expression, suppressing default output

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