Creating New Templates
You can create your own templates in the workflow catalog that you or your colleagues can use to render fuzzfiles and run workflows.
Begin by navigating to the workflow catalog and selecting “Create Template”.


From here you can populate all of the fields. Enter a Name, Category, and Description, then
supply the Template itself – a normal Fuzzfile with variables inserted using double curly braces
and a dot (i.e. {{.VariableName}}).
You might find it easy to create a fuzzfile using the Workflow Editor, and then replace specific values with variables.
The templating feature in the workflow catalog is implemented using Go text/template and slim-sprig. The latter allows you to do more complex operations like creating conditional logic!
Once you have your template specified, you can add inputs for all of your variables with ADD INPUT. Then save your template with SAVE at the top right of the page (DISCARD abandons it).
Name, Description, Category, and Template are all required. If any of them is empty, or an input’s variable name is invalid, saving is rejected: the editor lists the fields to fix and shows the specific problem next to each one.

Now you are ready to test your new template! Find it in the workflow catalog and interact with it as described in the previous two sections.


To create a template in the workflow catalog using the CLI, you’ll need to manually author both a template file and a values file.
Authoring the template file.
The template file is a YAML file with the syntax of a
fuzzfile that also includes
placeholders for values you want users to customize. These placeholders use the syntax
{{.VariableName}}, where VariableName is a unique identifier for each parameterized value.
The templating feature in the workflow catalog is implemented using the Go text/template and slim-sprig. The latter allows you to do more complex operations like creating conditional logic!
Here’s an example template file for a simple “Hello World” workflow:
version: v4
jobs:
helloworld:
image:
uri: {{.ContainerUri}}
policy:
timeout:
execute: {{.Timeout}}
script: |
#!/bin/sh
{{.Script}}
resource:
cpu:
cores: {{.Cores}}
affinity: NUMA
memory:
size: {{.Memory}}
A user rendering the template needs to know what each variable accepts and what it controls. The values file carries that information: it names every variable, describes it, and gives it a type and a default.
Authoring the values file.
The values file must define all variables used in your template. Here is an example corresponding to the “Hello World” template above:
values:
- name: ContainerUri
display_name: URI for the docker image to use for this workflow
string_value: docker://alpine:latest
- name: Timeout
display_name: How long to wait for the workflow job to complete
string_value: 5m0s
- name: Cores
display_name: How many CPU cores to allocate for the workflow job
uint_value: 1
- name: Memory
display_name: How much memory to allocate for the workflow job
string_value: 1GiB
- name: Script
display_name: Script to run for the 'hello world' job
string_value: echo "Hello, world! Hostname ${HOSTNAME}"
Each entry for a variable has the following attributes:
- name: The variable name (without the dot prefix used in the template)
- display_name: A user-friendly explanation of what the variable does
- Value type: One of the following, depending on the data type:
string_value: For text values, durations, sizes, etc.uint_value: For unsigned integers (whole numbers)bool_value: For true/false values
The value type is indicated by the key name. The value of the key is the default value for the variable.
Adding the template to the catalog.
Once you’ve created both files, add the template to the workflow catalog using the create
command:
$ fuzzball workflow catalog create <TEMPLATE_FILE> <VALUES_FILE> [flags]For example:
$ fuzzball workflow catalog create hello-world-template.yaml hello-world-values.yaml \
--name "Hello World" \
--description "A simple Hello World example" \
--category "EXAMPLES"
Application created with ID: 00000000-0000-0000-0000-000000000000Confirm the template is in the catalog with fuzzball workflow catalog list.
When defining template inputs in your values file, you can use several different value types depending on what kind of data the template parameter represents. Each input declares exactly one type; the key name selects the type and its value supplies the default.
The basic value types are:
string_value: For text values, durations, sizes, etc.uint_value: For unsigned integers (whole numbers)bool_value: For true/false values
The Hello World example in the CLI tab above uses string_value and uint_value. There is no
decimal type – express fractional values as a string_value and quote them in the template if
needed.
A secret input is declared with secret_value, whose reference sub-field holds a
secret://<scope>/<name> URI. Leave the reference empty to declare the input without pinning a
secret:
values:
- name: ApiToken
display_name: API token for the upstream service
secret_value:
reference: ""
A user fills it from the secret picker in the web UI or by typing a reference at the CLI prompt. An empty reference is also how an input is made optional – see Optional Template Inputs.
For workflow templates that include volume definitions, you can use volume_value to let users
select a volume. This type supports v4 volume semantics with structured fields:
values:
- name: DataVolume
display_name: Persistent data volume for analysis results
volume_value:
storage_provisioner_name: shared-nfs
volume_name: analysis-data
volume_value supports these fields:
storage_provisioner_name: The name of the storage provisioner to use (corresponds to theuse:field in workflow volume definitions)volume_name: The name of a persistent volume (corresponds to thename:field in workflow volume definitions)reference: Legacy v1/v3 volume URI format (volume://<scope>/<class>[/<name>]) – retained for backward compatibility with older catalog data
New templates should use thestorage_provisioner_nameandvolume_namefields rather than the legacyreferenceformat. The structured fields align with v4 volume semantics and provide better clarity. See Storage Volumes and Workflows for details on v4 volume configuration.
Whichever form the values file uses, a volume_value input substitutes a single
volume://<scope>/<provisioner>/<volume> URI into the template, not the individual fields. Consume
it through a volume’s reference field, as shown under
Optional Template Inputs. To parameterize use: and
name: separately, declare two string_value inputs instead, as the next example does.
Here’s an example template that parameterizes a volume’s provisioner and name as two separate
string_value inputs:
Template file (data-processor-template.yaml):
version: v4
volumes:
output:
use: {{.OutputProvisioner}}
name: {{.OutputVolume}}
jobs:
process:
image:
uri: {{.ContainerUri}}
mounts:
/output:
volume: output
script: |
#!/bin/sh
{{- .ProcessingScript | nindent 6}}
resource:
cpu:
cores: {{.Cores}}
affinity: NUMA
memory:
size: {{.Memory}}
Values file (data-processor-values.yaml):
values:
- name: ContainerUri
display_name: Container image for data processing
string_value: docker://alpine:latest
- name: OutputProvisioner
display_name: Storage provisioner for output volume
string_value: shared-nfs
- name: OutputVolume
display_name: Name of persistent output volume
string_value: my-results
- name: Cores
display_name: CPU cores to allocate
uint_value: 2
- name: Memory
display_name: Memory to allocate
string_value: 4GiB
- name: ProcessingScript
display_name: Processing script to execute
string_value: |
echo "Processing data..."
date > /output/timestamp.txt
A multi-linestring_valuesubstituted into a YAML block scalar must be piped throughnindent <n>, as{{- .ProcessingScript | nindent 6}}is above. Gotext/templatedoes not re-indent interpolated text, so without it every line after the first lands at column 0 and the rendered Fuzzfile is invalid YAML.fuzzball workflow catalog renderstill exits 0 and prints the broken file; the failure surfaces later, atcatalog start.
A template can name a persistent volume but cannot create one. The volume must exist before a rendered workflow runs, so say which volume an input expects in its
display_name. See Storage Volumes and Workflows.A structured
volume_valuedefault is used only when the consumer accepts the prompt default. The CLI shows it as blank and cannot supply the structured fields itself, so for templates aimed at CLI users prefer the two-string_valuepattern shown above.
If you are maintaining older catalog templates that use the v1/v3 volume URI format, you may see:
values:
- name: DataVolume
display_name: Data volume
volume_value:
reference: volume://group/shared/analysis-data
This legacy reference format continues to work for backward compatibility, but new templates
should use the structured storage_provisioner_name and volume_name fields instead.
Add a display_category field to an input to group it with other inputs under a named heading in
the web UI. Categories change only the layout of the Configure panel; they do not change what
a user supplies, the order of substitution, or the rendered Fuzzfile.
Set display_category on each input in the values file. Inputs that share a value are grouped
together:
values:
- name: ContainerUri
display_name: URI for the docker image to use for this workflow
display_category: Container
string_value: docker://alpine:latest
- name: Cores
display_name: How many CPU cores to allocate for the workflow job
display_category: Resources
uint_value: 1
- name: Memory
display_name: How much memory to allocate for the workflow job
display_category: Resources
string_value: 1GiB
- name: Timeout
display_name: How long to wait for the workflow job to complete
display_category: Execution
string_value: 5m0s
- name: Script
display_name: Script to run for the 'hello world' job
display_category: Commands
string_value: echo "Hello, world! Hostname ${HOSTNAME}"
This values file groups the five inputs under Container, Resources, Execution, and
Commands. display_category is optional: an input that omits it renders above the
collapsible sections rather than inside any of them.
Two conventions are worth holding to across a set of templates:
- Group the inputs a user configures in one sitting – all resource limits, all volume settings – under one category, so the panel opens on a coherent set of fields
- Reuse category names across the templates you own, so a user who has configured one of them recognizes the layout of the next
For how categories render at run time, see template value categories.
When creating templates, you can declare secret and volume inputs as optional. A user who does not need the secret or volume then renders the template without supplying one.
To create a template that supports optional secret or volume inputs, declare the inputs in your
values file with an empty secret_value: {} or volume_value: {} entry, then structure your
template workflow to handle the case where the input is left empty at render time.
Write the empty declaration assecret_value: {}orvolume_value: {}, including the braces. A baresecret_value:with nothing after it is YAMLnull, which leaves the input with no type at all; the template can then never be rendered (“unknown template value type”). The braces declare a secret or volume input whose default is unset.
Rendering substitutes the reference the user selected – secret://<scope>/<name> for a secret
input, volume://<scope>/<provisioner>/<volume> for a volume input – or an empty string when the
input was left unset. Wrap the parts of the workflow that consume the reference in a conditional so
the empty case produces a valid fuzzfile.
Secret references are consumed by the workflow fields that accept them: a job’s image.secret and
image.decryption-secret, the secret field of a volume’s ingress source or egress destination,
and a KEY=secret://... entry in a job’s env list. Here’s a template that authenticates its
request only when the user supplies a token:
version: v4
jobs:
fetch-data:
image:
uri: {{.ContainerUri}}
{{- if .ApiToken}}
env:
- API_TOKEN={{.ApiToken}}
{{- end}}
script: |
#!/bin/sh
{{- if .ApiToken}}
curl -H "Authorization: Bearer $API_TOKEN" {{.ApiEndpoint}}
{{- else}}
curl {{.ApiEndpoint}}
{{- end}}
When ApiToken is supplied, its value is a secret reference (secret://<scope>/<name>), so
API_TOKEN={{.ApiToken}} becomes an environment-variable secret that Fuzzball resolves into the
job’s API_TOKEN variable. When it is left blank, the {{if .ApiToken}} guard omits the env
block entirely and the request runs without authentication.
Environment-variable secrets accept onlyuser-scoped secrets of type “value”. A user who picks agroup-scoped secret, or a secret of another type, getsonly user secret scope is allowed with environment variable secretswhen the workflow is submitted. Say so in the input’sdisplay_name, or consume the reference throughimage.secretor a volume’s ingress or egresssecretfield, which accept every scope.
The corresponding values file:
values:
- name: ContainerUri
display_name: Container image to use
string_value: docker://alpine:latest
- name: ApiEndpoint
display_name: API endpoint to fetch data from
string_value: https://api.example.com/data
- name: ApiToken
display_name: Optional user-scoped API token secret (leave blank for public endpoints)
secret_value: {}
A volume input supplies a reference for an entry in the workflow’s top-level volumes section; the
job mounts it by name through mounts. Both the volume declaration and the mount must be inside the
conditional, since a mount that names an undeclared volume is invalid:
version: v4
{{- if .InputVolume}}
volumes:
input-data:
reference: {{.InputVolume}}
{{- end}}
jobs:
process-data:
image:
uri: {{.ContainerUri}}
{{- if .InputVolume}}
mounts:
/data/input:
volume: input-data
{{- end}}
script: |
#!/bin/sh
{{- if .InputVolume}}
process-files /data/input/*
{{- else}}
echo "No input data provided, using defaults"
process-defaults
{{- end}}
When InputVolume is supplied, its value renders to a volume reference that Fuzzball resolves to
the use:/name: of an existing persistent volume, which is then attached through the job’s
mounts: map. When it is left blank, the {{if .InputVolume}} guards omit both the top-level
volumes: entry and the mount, and the job falls back to its default behavior.
The corresponding values file:
values:
- name: ContainerUri
display_name: Container image to use
string_value: docker://myapp:latest
- name: InputVolume
display_name: Optional input data volume (leave blank to use defaults)
volume_value: {}
A volume input substitutes a volume://<scope>/<provisioner>/<volume> URI, so the volume entry
consumes it through the legacy reference field rather than the preferred use/name pair.
Fuzzball converts reference to use/name when the workflow runs. See
volumes in the Fuzzfile syntax reference.
The conditionals in the examples above ({{if .Var}}) come from Go text/template. Rendering
accepts an empty secret or volume reference, so a conditional can include or omit the parts of
the workflow that consume one. Every {{if}}
needs its matching {{end}} – an unclosed conditional fails the render with
unexpected EOF.
When designing templates with optional inputs:
- Empty values are valid: An empty secret or volume reference does not cause validation errors during rendering. A non-empty reference is still format-checked, so a malformed reference is still rejected
- Conditional logic handles presence: Use Go template conditionals to include or exclude workflow sections based on whether optional inputs are provided
- Guard every use of the reference: The rendered fuzzfile must be valid in both branches. A field left holding an empty reference, or a mount naming a volume that was not declared, fails when the workflow is submitted
- Default behavior: Structure your template to provide sensible default behavior when optional inputs are omitted