AI-Assisted Authoring

SnapBench documentation is designed to work seamlessly with Large Language Models (LLMs) like Claude, ChatGPT, or Gemini. You can use AI assistants to generate complete scenario and component JSON files.

How It Works

1. Provide context - Share the relevant documentation pages with your AI assistant
2. Describe your need - Explain what scenario or component you want to create
3. Review and import - Copy the generated JSON and import it into SnapBench
4. Test and refine - Run the scenario and adjust as needed

Reference Documents

Download these guides and provide them to your AI assistant:

Download Component Designer Guide Download Scenario Designer Guide

Document	Purpose	When to Use
Component Designer Guide	Component JSON structure	Creating reusable catalog components
Scenario Designer Guide	Complete scenario structure	Creating full scenarios with instructions

Example Prompts

Creating a Component

I need to create a SnapBench catalog component for Elasticsearch.

Requirements:
- Use the official Elasticsearch Docker image
- Expose port 9200 for the REST API
- Include a terminal tab for debugging
- Add HTTP readiness check on /_cluster/health

Please generate the component JSON following the SnapBench component format.

Creating a Scenario

Create a SnapBench scenario that teaches Redis basics.

The scenario should:
- Use Redis 7 with a terminal for redis-cli
- Have 3-4 instruction steps covering: connection, basic commands (SET/GET), and data structures (lists, hashes)
- Include tab navigation links in the instructions
- Set TTL to 30 minutes

Please generate the complete scenario JSON.

Creating a Multi-Component Scenario

Create a SnapBench scenario for learning Kafka with Python.

Components needed:
- Apache Kafka (KRaft mode, no Zookeeper)
- Python workbench with kafka-python library

Instructions should cover:
1. Create a topic
2. Write a Python producer script
3. Write a Python consumer script
4. Test the full pipeline

Include pre-loaded Python scripts in the workbench. Generate the complete scenario JSON.

Recommended Workflow

1. Generate

Paste the relevant documentation into your AI assistant's context, then describe what you need. Be specific about:

• Components to include
• Learning objectives
• Specific configurations (ports, credentials, etc.)
• Number and focus of instruction steps

2. Import

Copy the generated JSON and import it into SnapBench:

• Components: Catalog > Import Component
• Scenarios: Tracks > Select Track > Import Scenario

3. Test

Run the scenario to verify:

• All components start correctly
• Readiness checks pass
• Inter-component connectivity works
• Instructions are clear and accurate

4. Refine

Common adjustments after testing:

• Fix port configurations
• Adjust resource allocations
• Clarify instruction wording
• Add missing environment variables

Tips for Better Results

Be Specific

Good prompt

"Create a PostgreSQL component using version 16, with username 'app' and password 'secret123', database named 'mydb', exposing port 5432 with a TCP readiness check."

Vague prompt

"Create a PostgreSQL component."

Provide Examples

If you have existing scenarios that work well, share them as examples:

Here's an example of a working scenario in our system:
[paste JSON]

Please create a similar scenario but for MongoDB instead of PostgreSQL.

Iterate

Don't expect perfection on the first try. Use follow-up prompts:

• "The Kafka component isn't connecting. Add the KAFKA_ADVERTISED_LISTENERS environment variable."
• "Add a second terminal tab for the consumer."
• "Make the instructions more beginner-friendly."

Scenario Generation Guide

Below is a comprehensive reference document you can copy and paste to your AI assistant. It contains the complete JSON structure and best practices for scenario generation.

Click to expand the Scenario Generation Guide

# SnapBench Scenario Generation Guide

You are helping create scenarios for SnapBench, a platform for interactive Kubernetes-based labs.

## JSON Structure

A scenario export has this structure:

{
  "scenario": {
    "name": "Scenario Name",
    "description": "Brief description of what participants will learn"
  },
  "spec": {
    "ttlMinutes": 60,
    "displayMode": "canvas",
    "components": [...],
    "instructions": [...],
    "nodePositions": [...]
  },
  "secrets": []
}

## Components

Components are the infrastructure pieces (databases, message brokers, apps) that run in the lab.

### Component Structure

{
  "id": "unique-lowercase-id",
  "kind": "DisplayName",
  "label": "template-label",
  "deploymentType": "docker|helm|compose",

  // Docker-specific
  "image": "image:tag",
  "command": ["/bin/bash", "-c"],
  "args": ["command to run"],
  "env": {"KEY": "value"},

  // Common fields
  "resources": {
    "cpuM": 500,
    "memMi": 512
  },
  "tabs": [...],
  "dependsOn": ["other-component-id"],
  "readinessCheck": {...}
}

### Exposed Ports (CRITICAL for Docker)

For Docker components, you MUST define `expose` to create a Kubernetes Service:

{
  "expose": [
    {"name": "http", "port": 8080}
  ]
}

Without this, other components cannot reach this component by its label.

### Web UI Configuration

To expose a web UI, you need THREE things:

1. `expose` - Creates the Kubernetes Service
2. `ui` - Creates the Ingress for external access
3. `tabs` with `type: "web"` - Creates the clickable tab

{
  "expose": [{"name": "http", "port": 3000}],
  "ui": [{"path": "/", "servicePort": 3000}],
  "tabs": [{"type": "web", "label": "Dashboard", "port": 3000, "path": "/"}]
}

### Readiness Check

TCP check (databases, message brokers):
{
  "readinessCheck": {
    "enabled": true,
    "type": "tcp",
    "tcpSocket": { "port": 5432 },
    "initialDelaySeconds": 10,
    "periodSeconds": 5,
    "timeoutSeconds": 3
  }
}

HTTP check (web services):
{
  "readinessCheck": {
    "enabled": true,
    "type": "http",
    "httpGet": { "port": 8080, "path": "/health" },
    "initialDelaySeconds": 15,
    "periodSeconds": 5,
    "timeoutSeconds": 3
  }
}

### Interactive Containers

For containers where participants run commands interactively:

{
  "args": ["sleep", "infinity"],
  "tabs": [{"type": "terminal", "label": "Terminal", "workingDir": "/sb"}]
}

Do NOT set `command` - leave it undefined to allow interactive use.

### Files

Mount files into the container at `/sb/`:

{
  "files": [
    {"name": "script.py", "content": "print('Hello')"}
  ]
}

## Instructions

{
  "title": "Step Title",
  "markdown": "# Heading\n\nContent with **formatting**."
}

### Tab Navigation Links

[Link text](tab:componentLabel) - opens first tab
[Link text](tab:componentLabel:1) - opens second tab (index 1)

### Code Blocks

Terminal commands: ```bash
Code snippets: ```sql, ```python, ```json

## Common Patterns

### Kafka (KRaft mode)
{
  "image": "apache/kafka:3.7.0",
  "env": {
    "KAFKA_NODE_ID": "1",
    "KAFKA_PROCESS_ROLES": "broker,controller",
    "KAFKA_LISTENERS": "PLAINTEXT://:9092,CONTROLLER://:9093",
    "KAFKA_ADVERTISED_LISTENERS": "PLAINTEXT://kafka:9092",
    "KAFKA_CONTROLLER_LISTENER_NAMES": "CONTROLLER",
    "KAFKA_LISTENER_SECURITY_PROTOCOL_MAP": "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT",
    "KAFKA_CONTROLLER_QUORUM_VOTERS": "1@localhost:9093",
    "KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR": "1",
    "CLUSTER_ID": "MkU3OEVBNTcwNTJENDM2Qk"
  },
  "expose": [{"name": "broker", "port": 9092}]
}

### PostgreSQL (Docker)
{
  "image": "postgres:16-alpine",
  "env": {
    "POSTGRES_USER": "postgres",
    "POSTGRES_PASSWORD": "postgres",
    "POSTGRES_DB": "demo"
  },
  "expose": [{"name": "postgres", "port": 5432}],
  "readinessCheck": {
    "enabled": true,
    "type": "tcp",
    "tcpSocket": { "port": 5432 }
  }
}

### Python Workbench
{
  "image": "python:3.11-slim",
  "args": ["sleep", "infinity"],
  "tabs": [{"type": "terminal", "label": "Python", "workingDir": "/sb"}],
  "files": [{"name": "script.py", "content": "..."}]
}

## Guidelines

1. Total resources should stay under 2000m CPU and 4Gi memory
2. Set TTL: 30-60 min for simple labs, 90-120 min for complex ones
3. Include readiness checks for databases and services
4. Use dependsOn for proper startup order
5. Position nodes logically (left-to-right data flow)

Troubleshooting AI-Generated Scenarios

Issue	Likely Cause	Fix
Component unreachable	Missing expose field	Add expose with the correct port
Web UI not accessible	Missing ui or tabs[type:web]	Add both ui and web tab
Readiness check fails	Wrong port format	Use tcpSocket: {port: X} or httpGet: {port: X, path: "/"}
Container exits immediately	Missing sleep infinity	Add args: ["sleep", "infinity"] for interactive containers
Files not found	Wrong path	Files are mounted at /sb/filename

Next Steps

• Try generating a simple single-component scenario first
• Graduate to multi-component scenarios with dependencies
• Create reusable catalog components for your organization