Fuzzball Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

Fuzzfiles From Existing Templates

The Workflow Catalog is prepopulated with a set of official CIQ templates based on common applications and workflows. If you use a shared group, you may also see templates created by other users within your group.

Please select either the web UI or CLI tab to see the appropriate instructions for your environment.

Select Workflows in the left navigation and open the Catalog tab. The page lists the templates available to you.

Main Workflow Catalog page

Once you identify an interesting template, click within the template description box to open its detail page. Cards in the Featured carousel also carry their own RUN button, so you can launch one of those directly from the main page.

Hello World example in Workflow Catalog

The detail page shows the template’s Configure panel on the right. Make any desired changes to the input values there – inputs are grouped into collapsible sections, each labeled with its category name and the number of fields it holds – then choose either RUN or OPEN IN EDITOR.

If you select RUN, Fuzzball renders the Fuzzfile behind the scenes, validates it, launches the workflow, and opens the new workflow’s status page.

Workflow names are optional – fill in Run Name at the top of the Configure panel to set one. A run launched with Run Name blank has no name and is listed by its ID, so a descriptive name is worth setting, especially when you launch the same template more than once.

Hello World workflow running after launch from the catalog

If you select OPEN IN EDITOR, the Workflow Editor opens with a Fuzzfile built from the template and the values you supplied.

Workflow Catalog Fuzzfile opened in Workflow Editor

From there, you can inspect and further refine the resulting Fuzzfile, and launch a workflow based on the Fuzzfile when you are ready. See the Workflow Editor section for more details.

You can render a Fuzzfile from a workflow template and values with the Fuzzball CLI. First you need to identify the template like so:

$ fuzzball workflow catalog list --name 'Hello, World'
ID                                   | NAME
7f8e322c-8d03-579c-a41b-f6257949dd17 | Hello, World

The ID above is an example value. Template IDs are specific to a cluster and to the catalog repository the template came from, so yours will differ.

Every command that takes a template – get, bundle, render, start, copy, update, enable, disable, delete – also accepts its name, which is what the examples below use. A name has to identify one template on the cluster: if two catalog repositories publish templates of the same name, the command reports the name as ambiguous and you pass the ID instead.

Then you can render a Fuzzfile from that template. You can provide the values for the template interactively like so:

$ fuzzball workflow catalog render 'Hello, World'
ContainerUri - URI for the docker image to use for this workflow [docker://alpine:latest]:
Timeout - How long to wait for the workflow job to complete [5m0s]: 4m
Cores - How many CPU cores to allocate for the workflow job [1]: 1
Memory - How much memory to allocate for the workflow job [1GiB]: 512MB
Script - Script to run for the 'hello world' job [echo "Hello, world! Hostname ${HOSTNAME}"]:
# Copyright 2025 CIQ, Inc. All rights reserved.
version: v4
jobs:
  helloworld:
    image:
      uri: "docker://alpine:latest"
    policy:
      retry:
        attempts: 1
      timeout:
        execute: "4m"
    command:
      - /bin/sh
      - '-c'
      - echo "Hello, world! Hostname ${HOSTNAME}"
    resource:
      cpu:
        cores: 1
        affinity: NUMA
      memory:
        size: 512MB

Alternatively you can provide values in a yaml format file:

$ cat > values.yaml <<'__EOF__'
values:
  - name: ContainerUri
    string_value: docker://alpine:latest
  - name: Memory
    string_value: 512MB
  - name: Cores
    uint_value: 1
  - name: Timeout
    string_value: 4m
  - name: Script
    string_value: echo "Hello, cruel world from ${HOSTNAME}"
__EOF__

$ fuzzball workflow catalog render --values values.yaml 'Hello, World'
# Copyright 2025 CIQ, Inc. All rights reserved.
version: v4
jobs:
  helloworld:
    image:
      uri: "docker://alpine:latest"
    policy:
      retry:
        attempts: 1
      timeout:
        execute: "4m"
    command:
      - /bin/sh
      - '-c'
      - echo "Hello, cruel world from ${HOSTNAME}"
    resource:
      cpu:
        cores: 1
        affinity: NUMA
      memory:
        size: 512MB

You can also provide values in-line as comma-separated key=value pairs, without writing a file. Each --values argument is either the path to a values file or a list of key=value pairs; the flag may be repeated, the two forms may be mixed, and later values override earlier ones. Values you do not specify keep the template’s defaults. The same --values syntax works with fuzzball workflow catalog start.

$ fuzzball workflow catalog render --values Cores=2,Memory=512MB 'Hello, World'

$ fuzzball workflow catalog render --values values.yaml --values Cores=2 'Hello, World'

The equivalent of clicking RUN in the web UI is fuzzball workflow catalog start, which renders and submits in one step:

$ fuzzball workflow catalog start --values values.yaml 'Hello, World'

To inspect the Fuzzfile before submitting it, render to a file and start that instead:

$ fuzzball workflow catalog render --values values.yaml 'Hello, World' > hello.fz

$ fuzzball workflow start hello.fz
71553f7c-92c7-4576-abd2-fe8e4b6bea97
Providing a workflow name is optional. fuzzball workflow catalog start names the workflow after the template; fuzzball workflow start FUZZFILE names it after the file. Use --name to override either.

Finding Workflows Started From the Catalog

A workflow started from the catalog, with RUN in the web UI or with fuzzball workflow catalog start, records the template it came from: its ID, and its name and template SHA as they were when the workflow was started. A workflow started from a Fuzzfile records none of these, including one rendered with fuzzball workflow catalog render and then started with fuzzball workflow start. The record is only kept for a template you can view.

On a federated deployment, a workflow started through the federate cluster records the template only when it comes from the official catalog. Templates from catalog sources added on the federate cluster are not recorded.

fuzzball workflow describe shows the template in a Started from catalog: row. To list the workflows started from a template, pass its name or ID to --application:

$ fuzzball workflow list --application 'Hello, World'

A name matches the name the template had when each workflow was started, so workflows started from a template that has since been removed are still found. Like --parent, --application searches your full history rather than only the last seven days.

For machine-readable output, fuzzball workflow get -o json and fuzzball workflow list -o json carry the same values as applicationId, applicationName, and applicationTemplateSha.

Optional Inputs

Some templates include secret or volume inputs that are designed to be optional. Empty secret or volume references are accepted during rendering, so template authors can design templates that work with or without certain secrets or volumes. Any conditional logic in the template handles the absence of an optional input appropriately, and fuzzball workflow catalog render renders successfully when optional secret and volume parameters are left empty.

How to leave an input empty depends on how you supply values:

  • Web UI: choose (None), the first entry in the secret or volume picker.
  • Interactive CLI prompts: press Enter without typing anything. This accepts the input’s default, which is empty for an optional input.
  • --values file: give the input an empty secret_value: {} or volume_value: {} entry.
$ cat > values.yaml <<'__EOF__'
values:
  - name: ContainerUri
    string_value: docker://alpine:latest
  - name: ApiToken
    secret_value: {}
__EOF__
Write secret_value: {} rather than a bare secret_value:. A bare key is YAML null, which leaves the value untyped. fuzzball workflow catalog render --values recovers the type from the template’s defaults, but --from-file and direct API callers reject it with unknown template value type.

Template Input Types

Templates declare a type for each input. Most use the basic types – strings, unsigned integers, and booleans – and some also declare secret or volume inputs, which you fill from a picker in the web UI or a reference at the CLI prompt.

Volume Inputs

A volume input holds a reference to one storage volume. It uses v4 volume semantics and carries two fields:

  • Provisioner name (storage_provisioner_name): Which storage provisioner to use (maps to the use: field in the workflow)
  • Volume name (volume_name): The name of a persistent volume (maps to the name: field in the workflow)

When you render a Fuzzfile from a template with volume inputs, you supply one volume per input: pick it from the volume picker in the web UI, or enter its reference (volume://<scope>/<provisioner>/<volume>) at the CLI prompt.

At the CLI prompt you always type a volume://<scope>/<provisioner>/<volume> URI. The CLI fills the input’s legacy reference field and the server maps it onto use: and name: when the workflow runs; the web UI’s volume picker populates the structured fields directly. Older templates may also declare the input itself with a legacy URI reference (volume://<scope>/<class>[/<name>]) rather than the structured fields. Both forms render, so a template you did not write may use either.

A persistent volume named in a template must exist before the rendered workflow runs. Create one with fuzzball volume create, in the web UI, or through the API. See Storage Volumes and Workflows.

Template Value Categories

Template authors can group inputs into categories with the display_category field. Categories change only how the web UI lays out the Configure panel; they do not change what you supply or what the rendered Fuzzfile contains. See template value categories for how authors define them.

Category Display in the Web UI

The Configure panel on a template’s detail page shows each category as its own collapsible section, labeled with the category name and the number of fields it holds. Inputs with no display_category appear above the collapsible sections. A template that sets no categories at all shows every input that way.

For example, a template might group inputs into categories like:

  • Resources: CPU cores and memory allocation
  • Container: Container image URI
  • Execution: Timeout and run-time settings
  • Commands: Custom script content and command-line arguments

Category Display in the CLI

Categories do not affect CLI rendering. fuzzball workflow catalog render prompts for every value in the order the template defines them, and the values file format ignores categories entirely.