Creating and Launching Formations¶

Intermediate 15 minutes

Overview¶

Formations are cloud-agnostic IaC recipes that describe infrastructure for cloud services. When you launch a formation, RosettaHub creates a session with running machines. In this tutorial you will browse images, launch machines, and manage formations and sessions through their lifecycle.

Prerequisites¶

[ ] Completed Getting Started with the CLI
[ ] At least one cloud key available (rh key ls)
[ ] Default cloud and region configured (rh settings)

Steps¶

Step 1: Browse Available Images¶

List images you can launch from:

rh image ls
rh image ls -s     # images shared with you
rh image ls -p     # public images
rh image ls -a     # all images (private + shared + public)

Note the image UID of an image you want to launch.

Step 2: Quick Launch with `image launch`¶

The fastest way to get a machine running — creates a formation and launches it in one command:

rh image launch <imageUid> --label "My Workspace" --key <keySetUid>

Wait until the machine is ready:

rh image launch <imageUid> -l "My Workspace" -k <keySetUid> -g

Available options:

Option	Description	Default
`-l`, `--label`	Session label (required)	—
`-k`, `--key`	Cloud key UID	—
`-s`, `--ssl`	SSL certificate UID	—
`-az`, `--availabilityzone`	Target zone	auto
`-cap`, `--capacity-id`	Instance type	default
`-n`, `--instances`	Number of instances	`1`
`-g`, `--wait-until-running`	Block until ready	`false`

Step 3: List Formations¶

rh formation ls
rh formation ls -a                    # all formations
rh formation ls -c aws -r us-east-1   # filter by cloud and region
rh formation ls -t machine            # filter by category

Step 4: Launch an Existing Formation¶

Launch a formation by its UID. The launch clones the formation and creates a new session:

rh formation launch <formationUid> --label "Dev Session"

Wait until the machine is running:

rh formation launch <formationUid> -l "Dev Session" -g

Pass parameters and attach storage:

rh formation launch <formationUid> \
  -l "Dev Session" \
  -p param1=value1 \
  -p param2=value2 \
  -w <workingStorageUid> \
  -g

Step 5: Create a Machine Formation¶

Create a new machine formation from scratch:

rh formation create-machine --label "GPU Server" --image <imageUid> --key <keyUid>

Other formation types:

rh formation create-spark ...         # Spark cluster
rh formation create-emr ...           # EMR cluster
rh formation create-hpc ...           # HPC cluster
rh formation create-virtual-lab ...   # Virtual lab

Step 6: Manage Sessions¶

Sessions represent running instances of formations. List your sessions:

rh session ls
rh session ls -a    # all sessions

Stop a running session:

rh session stop <sessionUid>

Start a stopped session:

rh session start <sessionUid>

Delete a session:

rh session delete <sessionUid>

Open a session in the browser:

rh session browse <sessionUid>

Step 7: Configure a Formation¶

Modify settings on an existing formation:

rh formation configure <formationUid>
rh formation configure-machine <formationUid>
rh formation configure-network <formationUid>
rh formation configure-lifecycle <formationUid>

Clone an existing formation:

rh formation clone <formationUid>

Share a formation with others:

rh formation share <formationUid>

Remove sharing:

rh formation unshare <formationUid>

Step 9: Delete a Formation¶

Permanently remove a formation:

rh formation delete <formationUid>

Use --yes to skip the confirmation prompt:

rh formation delete <formationUid> --yes

Next Steps¶

Working with Keys and Storage — attach storage to your formations
Automation with Cron Jobs — schedule formation operations

Troubleshooting¶

Launch fails with 'no key found'

Ensure you have a cloud key for the target region. Run rh key ls to check.

Session stuck in 'launching' state

Check your cloud account quotas and instance type availability in the target region.

What is the difference between formations and sessions?

A formation is a reusable IaC recipe (template). A session is a running instance created by launching a formation. You can launch the same formation multiple times to create multiple sessions.