Getting Started#

Prerequisites#

Python version 3.9 or higher.
An account on Chameleon Cloud and/or FABRIC.
An allocation on Chameleon Cloud and/or FABRIC.
Vagrant and VirtualBox.

Hint

Starting a new experiment? Check out our [template](pegasus-isi/kiso-experiment-template) for a quick start.

Installation#

pip3 install kiso

Vagrant#

Install Vagrant.
Install VirtualBox.
Install Vagrant dependencies needed by Kiso.

$ pip3 install kiso[vagrant]

Chameleon Cloud#

An account on Chameleon Cloud.
A project allocation on Chameleon Cloud.
Create and download application credentials for the desired Chameleon Cloud site.
Create and download, or Import your SSH key to the desired Chameleon Cloud site.
Install Chameleon dependencies needed by Kiso.

$ pip3 install kiso[chameleon]

FABRIC#

An account on FABRIC.
A project on FABRIC.
Getting started with FABRIC is here.
Install FABRIC dependencies needed by Kiso.

$ pip3 install kiso[fabric]

# On macOS
$ brew install rsync

Caution

Some FABRIC sites assign IPv6 addresses as the management IP. macOS’ rsync implementation fails connecting to these IPv6 address via jump hosts. To fix this, install rsync from Homebrew.

Your First Experiment#

The following example uses Vagrant (no cloud account required) to provision a local VM, install Docker, and run a shell experiment that prints “Hello, world!”.

1. Create experiment.yml

sites:
  - kind: vagrant
    backend: virtualbox
    box: bento/rockylinux-9
    user: vagrant
    resources:
      machines:
        - labels:
            - submit
          backend: virtualbox
          box: bento/rockylinux-9
          user: vagrant
          flavour: "large"
          number: 1
      networks:
        - labels:
            - net
          cidr: "172.16.42.0/16"

software:
  docker:
    labels:
      - submit

experiments:
  - kind: shell
    name: hello-world
    description: Print a message
    scripts:
      - labels:
          - submit
        script: |
          #!/bin/bash
          echo "Hello, world!" > hello.txt
    outputs:
      - labels:
          - submit
        src: hello.txt
        dst: ./

2. Validate the configuration

$ kiso check experiment.yml

3. Provision resources and install software

$ kiso up experiment.yml

4. Run the experiment

$ kiso run experiment.yml

# View the output
cat hello.txt

5. Tear down resources

$ kiso down experiment.yml

CLI Reference#

For full details on each command and its options, see the Command Line Tool reference.

$ kiso --help

 Usage: kiso [OPTIONS] COMMAND [ARGS]...

 🏇 Kiso: Edge to Cloud Workflows: Advancing Workflow Management in the Computing Continuum.

╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --debug/--no-debug                                                                                                  │
│ --help  -h    Show this message and exit.                                                                           │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ check        Check the experiment configuration.                                                                    │
│ down         Destroy the resources provisioned for the experiments.                                                 │
│ run          Run the defined experiments.                                                                           │
│ up           Create the resources needed to run the experiment.                                                     │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

 Check our docs at https://kiso.readthedocs.io/en/v0.1.0a10 for more details.

$ kiso check --help
 _   __ _
| | / /(_)
| |/ /  _  ___   ___
|    \ | |/ __| / _ \
| |\  \| |\__ \| (_) |
\_| \_/|_||___/ \___/  v0.1.0a10


 Usage: kiso check [OPTIONS] [EXPERIMENT_CONFIG]

 Check the experiment configuration.

╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help  -h    Show this message and exit.                                                                           │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

 Check our docs at https://kiso.readthedocs.io/en/v0.1.0a10 for more details.

$ kiso up --help
 _   __ _
| | / /(_)
| |/ /  _  ___   ___
|    \ | |/ __| / _ \
| |\  \| |\__ \| (_) |
\_| \_/|_||___/ \___/  v0.1.0a10


 Usage: kiso up [OPTIONS] [EXPERIMENT_CONFIG]

 Create the resources needed to run the experiment.

╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --force   -f                                                                                                        │
│ --output  -o  DIRECTORY  Environment to use for the experiment.                                                     │
│ --help    -h             Show this message and exit.                                                                │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

 Check our docs at https://kiso.readthedocs.io/en/v0.1.0a10 for more details.

$ kiso run --help
 _   __ _
| | / /(_)
| |/ /  _  ___   ___
|    \ | |/ __| / _ \
| |\  \| |\__ \| (_) |
\_| \_/|_||___/ \___/  v0.1.0a10


 Usage: kiso run [OPTIONS] [EXPERIMENT_CONFIG]

 Run the defined experiments.

╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --force   -f                                                                                                        │
│ --output  -o  DIRECTORY  Environment to use for the experiment.                                                     │
│ --help    -h             Show this message and exit.                                                                │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

 Check our docs at https://kiso.readthedocs.io/en/v0.1.0a10 for more details.

$ kiso down --help
 _   __ _
| | / /(_)
| |/ /  _  ___   ___
|    \ | |/ __| / _ \
| |\  \| |\__ \| (_) |
\_| \_/|_||___/ \___/  v0.1.0a10


 Usage: kiso down [OPTIONS] [EXPERIMENT_CONFIG]

 Destroy the resources provisioned for the experiments.

╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --output  -o  DIRECTORY  Environment to use for the experiment.                                                     │
│ --help    -h             Show this message and exit.                                                                │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

 Check our docs at https://kiso.readthedocs.io/en/v0.1.0a10 for more details.

Getting Started

Contents

Getting Started#

Prerequisites#

Installation#

Vagrant#

Chameleon Cloud#

FABRIC#

Your First Experiment#

CLI Reference#