Getting Your First Workflow

Your Fuzzball cluster hosts a list of prebuilt Fuzzfile templates in the Workflow Catalog. These templates create the YAML files that define workflows, and they are a quick way to start running work on Fuzzball. Detailed information on developing Fuzzfiles and a complete syntax guide are presented elsewhere.

The workflow in this tutorial prints one integer per second, counting from 1 to 300. It is deliberately simple: it produces output you can retrieve through Fuzzball logging, and its five-minute runtime leaves time to interact with it while it runs. For workflows that solve real problems, see the Workflow Examples section.

Select the tab below for your environment: the web UI or the CLI.

select

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

web UI

You can use the Workflow Catalog to start quickly with a basic Fuzzball example. The Workflow Catalog has templates that create Fuzzfiles automatically from a workflow template and user-provided parameters. This tutorial uses the Printer template to create a Fuzzfile and run a simple workflow.

In the Workflow Catalog use the search bar to locate the example named “Printer Example”.

Fuzzball Printer example in Workflow Catalog

You can see details about the workflow template by clicking on the description box. The Configure panel on the right gives you access to parameters that you can change before rendering the Fuzzfile from the template. Related parameters are grouped into collapsible sections such as CONTAINER and EXECUTION, each labeled with the number of fields it holds. The Printer template allows you to change the container that is used to run the printer job, and the number of seconds that the job runs. Other templates may allow you to change the commands that are run, the resources that are used, and so on.

You can render the workflow template with the parameters you select and open the resulting Fuzzfile in the workflow editor (OPEN IN EDITOR), or run it directly (RUN).

Printer template Configure panel for editing inputs

For now, select RUN without changing any defaults. A Fuzzfile will be rendered behind the scenes and checked for valid syntax, and you will be taken straight to the new workflow’s status page, where you can watch it begin to run.

Printer start workflow from catalog

If you followed the instructions on this page, the Printer Example workflow will now be running on your cluster. See the next page for information about running workflows using the Workflow editor, and stopping running workflows.

CLI

Building your Fuzzfile outside of the web UI requires only a text editor. First, create a new directory to experiment in:

$ mkdir ~/fb-work

$ cd ~/fb-work

Now copy the contents of printer.fz shown below into a file of that name, using the text editor of your choice.

version: v4
jobs:
  printer:
    image:
      uri: docker://docker.io/alpine:latest
    policy:
      timeout:
        execute: 6m0s
    script: |
      #!/bin/sh
      for i in $(seq 1 300); do echo $i; sleep 1; done
    resource:
      cpu:
        cores: 1
      memory:
        size: 1GB

The .fz file extension is not necessary. Fuzzfiles also commonly carry .yml or .yaml extensions since they are written in YAML.

Fuzzball will automatically check and validate your Fuzzfile for syntax errors when you submit the workflow, but you can do so manually with the following command:

$ fuzzball workflow validate ./printer.fz
"./printer.fz" has been validated.

A Fuzzfile with syntax errors returns an error naming the line and the offending field. For example, if you change the jobs: key to jerbs: and validate again:

$ fuzzball workflow validate ./printer.fz
while parsing workflow: yaml: unmarshal errors:
  line 2: field jerbs not found in type api.WorkflowDefinition

Explanation of the Example Fuzzfile

If you want detailed information about the sections in this Fuzzfile, expand the section below. Feel free to skip it for now if you are just trying to learn how to submit your workflows with Fuzzball.

Default version: New workflows created in the web UI, and templates rendered from the Workflow Catalog, use version: v4. The example Fuzzfile above uses v4 syntax. For the storage-related changes that came with v4, see the V4 Storage Breaking Changes guide.

CLICK TO EXPAND: Section-by-section walkthrough ↕

Whether you used the Workflow Catalog to create your Fuzzfile behind the scenes, or you copied the example from the text, you should have ended up with a Fuzzfile that looked like the following. (If you used the Workflow Catalog to create this Fuzzfile automatically it will not be visible to you until you run the workflow in the next step.)

version: v4
jobs:
  printer:
    image:
      uri: docker://docker.io/alpine:latest
    policy:
      timeout:
        execute: 6m0s
    script: |
      #!/bin/sh
      for i in $(seq 1 300); do echo $i; sleep 1; done
    resource:
      cpu:
        cores: 1
      memory:
        size: 1GB

You might find it useful to start with this Fuzzfile and edit it to suit your needs. Each Fuzzfile section is explained in turn below.

The order of sections at the same level of indentation is arbitrary, but the indentation of a Fuzzfile (or any YAML file) will cause a syntax error if it is not correct.

version: v4
jobs:

The first line specifies that the workflow uses version 4 (v4) Fuzzfile syntax, and the second line starts the “jobs” section where any jobs that compose the workflow will be specified.

  printer:
    image:
      uri: docker://docker.io/alpine:latest

This starts the section associated with the job called “printer” (which is the only job in this Fuzzfile), and states that the job should run in the latest alpine container obtained from Docker Hub. (See the documentation on container URLs for more info about specifying containers.)

    policy:
      timeout:
        execute: 6m0s

The policy section states that the job should time out (be canceled) if it runs longer than the time allotted.

    script: |
      #!/bin/sh
      for i in $(seq 1 300); do echo $i; sleep 1; done

This section specifies the script that should run in the job (within the given container). In this example the script runs a loop with 300 iterations. Within each cycle of the loop, echo the current iteration, and wait (sleep) for one second. So this workflow just counts seconds from 1 to 300 (a total of five minutes).

    resource:
      cpu:
        cores: 1
      memory:
        size: 1GB

The final section specifies the computational resources that the job needs. In this case the job requires 1 core and 1GB memory.