Fuzzball Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage
  2. /
  3. Fuzzball in 15 Minutes
  4. /
  5. Getting Your First Workflow

Getting Your First Workflow

Your Fuzzball cluster hosts a list of prebuilt Fuzzfile templates in the Workflow Catalog. These template workflows allow you to automatically create the YAML files (Fuzzfiles) that define workflows and they are a great way to get up and running with Fuzzball quickly. Detailed information on developing Fuzzfiles and a complete syntax guide are presented elsewhere.

The workflow used to complete this tutorial runs for 5 minutes and prints an integer from 1 to 300 once per second. In the real world, this workflow is completely useless. But it serves as a useful demonstration for this tutorial since it produces output that can be gathered via Fuzzball logging and runs for 5 minutes allowing time for user interaction. More useful “real world” examples can be obtained in the Workflow Examples section.

For now, simply select one of the tabs below to see instructions specific for your environment.

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

We can use the Workflow Catalog to get up and running quickly with a basic Fuzzball example. The Workflow Catalog has templates that create Fuzzfiles automatically from a workflow template and user-provided parameters. In this tutorial, we will use the Printer template to create a Fuzzfile and run a simple workflow.

Select the Workflow Catalog option in the menu on the left and note the example named Printer.

Fuzzball Printer example in Workflow Catalog

Clicking on the “View details” button at the bottom of the Printer selection will show you a template used to create the printer workflow Fuzzfile, as well as the inputs that can be changed by the user. The values in the YAML template that are surrounded by double curly braces and preceded by a dot (e.g. {{.Container}}) are inputs that you can change before rendering the finished Fuzzfile.

Printer details

You can choose to either open the template in the Workflow Editor, or simply Run the Application using the respective buttons at bottom of the page. For the purposes of this tutorial, select “Run Application”. Either way, a dialog box like the following will open allowing you to edit the inputs before creating the final Fuzzfile.

Printer template dialog box to edit inputs

The printer template allows you to change the container that is used to run the printer job, or edit 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, etc.

For now, just select Validate without changing any defaults. The message at the bottom indicates that the Fuzzfile has been automatically rendered (behind the scenes) and checked for valid syntax.

Fuzzball Printer example in Workflow Catalog

That’s it! At this point a valid Fuzzfile for the printer workflow has been saved behind the scenes and is ready to be submitted by clicking the “Continue” button. We’ll look at submitting the workflow in the next section on Starting and Stopping Your New Workflow.

Building your Fuzzfile outside of the GUI is simply a matter of using a text editor. First, let’s create a new directory to experiment in:

$ mkdir ~/fb-work

$ cd !$

Now either copy and paste the contents of printer.fz described here into the appropriately named file using the text editor of your choice, or download the file and place it in the directory you just created.

version: v1
jobs:
  printer:
    image:
      uri: docker://docker.io/alpine:latest
    policy:
      timeout:
        execute: 6m0s
    command:
      - /bin/sh
      - '-c'
      - 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 will return an error similar to this:

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

(Optional) explanation of example Fuzzfile

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

Whether you used the Workflow Catalog to automatically 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: v1
jobs:
  printer:
    image:
      uri: docker://docker.io/alpine:latest
    policy:
      timeout:
        execute: 6m0s
    command:
      - /bin/sh
      - '-c'
      - 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. Therefore, a brief explanation is provided. We will explain each Fuzzfile section in turn.

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: v1
jobs:

The first line specifies that we are using version 1 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 timeout (be canceled) if it runs longer than the time allotted.

    command:
      - /bin/sh
      - '-c'
      - for i in $(seq 1 300); do echo $i; sleep 1; done

This section specifies the command(s) that should run in the job (within the given container). It is broken into parts that will be concatenated into a single command at runtime. Using the /bin/sh '-c' syntax, we can submit more than one command as a single string to the shell interpreter.

The actual commands in this example specify to run 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.

gdoc_arrow_left_alt Logging In and Selecting Your Account Starting and Stopping Your New Workflow gdoc_arrow_right_alt