Manage Trial Tenants¶

How to create and delete fully-configured trial tenants using the admin trials commands and a TOML manifest file.

What is a trial manifest?¶

A trial manifest is a TOML file that describes the complete state of a trial tenant: customer identity, IAM configuration, IoT model, firmware, parts, devices, events, cybersecurity projects, and users.

Use the committed trial-manifest.sample.toml in the repository root as your starting point. Copy it, rename it for the customer (e.g. acme-trial.toml), and fill in the values.

Create a trial¶

1. Prepare the manifest¶

Copy the sample and customise every section:

cp trial-manifest.sample.toml acme-trial.toml

Key things to check:

• [trial] — unique code (uppercase, short) and display name
• [model] / [firmware] — names must not already exist in PMS unless you intend to reuse them (the CLI will warn and skip)
• [[parts]] — family must already exist in PMS; assign_model = true links the part to the trial model
• [[devices]] — serial numbers to provision; name is the display label in Fleet Manager
• [[events]] — attached to device serial numbers after provisioning; kind is public or internal
• [[cybersec_projects]] — existing security projects to clone under the new model's root project
• [[users]] — looked up by email; must already exist on the platform
• [teams.*] — IAM role actions and policy resources applied per team

2. Dry-run first¶

Always preview before creating:

tlm-cli admin trials create acme-trial.toml --dry-run

This prints what would be created for each section without making any API calls.

3. Create the trial¶

tlm-cli admin trials create acme-trial.toml

The command works through the manifest in this order:

1. Customer — reuses existing if the code is already taken (asks for confirmation)
2. IAM role actions and policy resources per team
3. IoT model
4. Firmware linked to the model
5. Parts and sub-parts, with model assigned per part where assign_model = true
6. Device provisioning, with model assigned per device
7. Events attached to devices
8. Fleet Manager claim for each device
9. Users moved to the new customer
10. Cybersecurity project clones moved under the model's root project

Each step is idempotent where possible: already-existing resources are skipped with a warning rather than causing an error.

4. Activate devices (manual — DAVE admin required)¶

After the trial is created, claimed devices are registered in the platform but not yet active. For each device to connect and be visible as online, a DAVE admin must manually instantiate a ToloMEO Virtual Device (TVD) using the certificates of the claimed device.

This step is outside the CLI and must be coordinated with the DAVE team before handing the trial over to the customer.

Delete a trial¶

1. Dry-run first¶

tlm-cli admin trials delete acme-trial.toml --dry-run

This shows the devices, users, parts, model, and firmware that would be removed.

2. Delete the trial¶

tlm-cli admin trials delete acme-trial.toml

The command always shows a preview and asks for confirmation before proceeding. Deletion runs in reverse creation order:

1. Unclaim devices from Fleet Manager
2. Unprovision devices (removes IoT things and PMS device records)
3. Delete parts (sub-parts first, then parents)
4. Delete firmware, then IoT model
5. Delete customer (cascades to IAM tenant, teams, and users)