Scenario Structure

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

Field	Description
`key`	Unique identifier. Must match the relative directory path (e.g. `nginx/001-broken-config`).
`name`	Human-readable name shown in reports.
`description`	The instruction sent to the agent. Write it as you would a real task: describe symptoms, not solutions.

Optional Fields

Field	Description
`tags`	String array for grouping. Pass a tag to `-s` to run all matching scenarios (e.g. `-s nginx`).
`hosts`	Target host definitions. See Hosts & Agents.
`agents`	Agent definitions. See Hosts & Agents.
`validation`	Validation 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.

Getting Started

Deployment

Core Concepts

Configure

Scenario Runner

CLI

Scenario Structure

Directory Layout

scenario.json

Required Fields

Optional Fields

Writing Good Descriptions

Scenario Keys and Tags

Minimal Example

​Directory Layout

​scenario.json

​Required Fields

​Optional Fields

​Writing Good Descriptions

​Scenario Keys and Tags

​Minimal Example

Directory Layout

scenario.json

Required Fields

Optional Fields

Writing Good Descriptions

Scenario Keys and Tags

Minimal Example