Skip to main content
A scenario is a directory containing a scenario.json file and optional Ansible playbooks. All scenarios live under a shared root (default: /etc/2501/runner/scenarios).

​
Directory Layout

scenarios/
  <category>/
    <NNN-scenario-name>/
      scenario.json       # required
      prepare.yml         # optional: Ansible setup before execution
      restore.yml         # optional: Ansible teardown after execution
      validate.yml        # optional: Ansible verification after execution
      inventory.ini       # optional: Ansible inventory
      [support files]     # config snippets, fixtures, test data, etc.
The category and numeric prefix (NNN) are conventions for organization: they have no special meaning to the runner. The runner uses the full relative path from the scenarios root as the scenario key (e.g. nginx/001-broken-config).

​
scenario.json

The only required file. At minimum, three fields are needed: 
{
  "key": "nginx/001-broken-config",
  "name": "Nginx Broken Configuration",
  "description": "@2501 the nginx service on the web server is not running. Investigate the issue and fix it so the service is running correctly."
}

​
Required Fields

FieldDescription
keyUnique identifier. Must match the relative directory path (e.g. nginx/001-broken-config).
nameHuman-readable name shown in reports.
descriptionThe instruction sent to the agent. Write it as you would a real task: describe symptoms, not solutions.

​
Optional Fields

FieldDescription
tagsString array for grouping. Pass a tag to -s to run all matching scenarios (e.g. -s nginx).
hostsTarget host definitions. See Hosts & Agents.
agentsAgent definitions. See Hosts & Agents.
validationValidation rules. See Validation.

​
Writing Good Descriptions

The description is the exact instruction the agent receives. A few guidelines:
  • Describe symptoms, not solutions. “The nginx service is not running after a configuration change” is better than “Fix the nginx config file.”
  • Be concrete. Reference the host name, service name, or observable behavior when you know it.
  • Keep it realistic. Write it as you would a real support ticket or runbook task.

​
Scenario Keys and Tags

The key must exactly match the directory path relative to the scenarios root: 
scenarios/nginx/001-broken-config/scenario.json
                                   └─ key: "nginx/001-broken-config"
Tags are free-form strings for grouping. A scenario can have multiple tags: 
{
  "key": "nginx/001-broken-config",
  "name": "Nginx Broken Configuration",
  "description": "...",
  "tags": ["nginx", "web", "config"]
}
Run all scenarios with a given tag: 
2501-runner run -s nginx
2501-runner run -s web
Tags and explicit keys can be mixed: 
2501-runner run -s nginx,disk/001-cleanup

​
Minimal Example

{
  "key": "disk/001-cleanup",
  "name": "Disk Space Cleanup",
  "description": "@2501 disk usage on sandbox-app-01 is above 90%. Identify what is consuming the most space and free up at least 5GB without deleting application data.",
  "tags": ["disk", "storage"],
  "hosts": [
    { "host_id": "hst_abc123" }
  ],
  "agents": [
    {
      "agent_id": "agt_xyz789",
      "host_id": "hst_abc123"
    }
  ],
  "validation": {
    "job": [
      {
        "label": "Job resolved successfully",
        "validator": "job_resolution_status",
        "pattern": "success"
      }
    ],
    "tasks": [
      {
        "label": "Agent checked disk usage",
        "validator": "pattern_match",
        "pattern": "df\\s|du\\s|ncdu",
        "where": "executed_commands"
      }
    ]
  }
}
For complete worked examples with playbooks, see Examples.