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.

select

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

web UI

Main Workflow Catalog page

Once you identify an interesting template, click on the template’s kebab menu to either select “View details” to see more information, or “Run” to launch the workflow directly from the main page. If you select “View details” you can see the template along with the user-supplied inputs.

Hello World example in Workflow Catalog

In the “Hello World” example above, we can see the actual template that is used to construct the Fuzzfile on the right. Inputs are surrounded by double curly braces and preceded by a dot (e.g. {{.ContainerUri}}). These inputs are listed with short explanations on the left side of the screen.

From here, you can choose either “Render Fuzzfile and Edit” or “Render Fuzzfile and Run”. Either way, a dialog box opens allowing you to provide new values for the inputs or accept the defaults.

If you selected “Render Fuzzfile and Run” you can then make any desired changes to the input values and select “Run”. This will create a Fuzzfile behind the scenes based on the input you selected and validate it for accuracy. Then you can press “Start Workflow” to run the workflow based on the Fuzzfile.

Workflow names are optional — Fuzzball uses the template name if you don’t specify one. Providing a descriptive name can help you manage workflows, especially when running multiple instances of the same template.

Press Continue to run workflow

If you selected “Render Fuzzfile and Edit”, the steps will be the same except you click “Edit” to load the Fuzzfile into the Workflow Editor instead of directly running it.

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.

CLI

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

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

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

$ fuzzball workflow catalog render 7f8e322c-8d03-579c-a41b-f6257949dd17
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:
      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 7f8e322c-8d03-579c-a41b-f6257949dd17
# Copyright 2025 CIQ, Inc. All rights reserved.
version: v4
jobs:
  helloworld:
    image:
      uri: "docker://alpine:latest"
    policy:
      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 7f8e322c-8d03-579c-a41b-f6257949dd17

$ fuzzball workflow catalog render --values values.yaml --values Cores=2 7f8e322c-8d03-579c-a41b-f6257949dd17

The equivalent of selecting “Render Fuzzfile and Run” in the web UI would be to save the rendered Fuzzfile and submit it.

$ fuzzball workflow catalog render --values values.yaml 7f8e322c-8d03-579c-a41b-f6257949dd17 > hello.fz

$ fuzzball workflow start hello.fz
71553f7c-92c7-4576-abd2-fe8e4b6bea97

Providing a workflow name is optional; if you omit one, Fuzzball uses the template name.

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 the blank entry at the top of 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__

The braces matter. A bare secret_value: with nothing after it is YAML null, which strips the input’s type and makes the render fail with unknown template value type. Write secret_value: {} to declare a secret input with no reference selected.

Template Input Types

Workflow catalog templates can use various input types to customize fuzzfile generation. Most templates use basic types like strings, numbers, and booleans, but some templates may include volume configuration inputs.

Volume Inputs

Some templates allow you to specify storage volumes using structured volume inputs. These inputs correspond to v4 volume semantics and let you configure:

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.

Persistent volumes referenced in templates must already exist before you can run the resulting workflow. You can create persistent volumes using fuzzball volume create, the web UI, or the API. See Storage Volumes and Workflows for details on volume creation and usage.

Template Value Categories

Templates can group their input fields into categories using the display_category field on each value. This grouping only affects how inputs are presented in the web UI when you run a template. See Organizing Template Values with Categories for how template authors define categories.

In the Web UI

When you select “Run” or “Render Fuzzfile and Run” from a template’s details page, the “Run Template” dialog displays each category as its own collapsible section, labeled with the category name and the number of fields it contains. Values that do not define a display_category are shown directly, above the collapsible sections.

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

If a template does not define a display_category for any of its values, all inputs are shown directly without collapsible sections.

In the CLI

When rendering templates via the CLI (using fuzzball workflow catalog render), categories do not affect the interactive prompts or the values file format. All template values are prompted in the order they are defined, regardless of category assignment.

Some older templates may use legacy volume URI references (format: volume://<scope>/<class>[/<name>]). These continue to work for backward compatibility, but newer templates use the structured provisioner and volume name fields described above.