Creator Documentation

Get Started

For a detailed tutorial check Get Started. In short:

• Add a Github repository to your Killercoda profile
• Every push into the repository and specified branch will update the Killercoda scenarios
• Write for example JSON, Markdown and Bash. See examples further below

Environments

For faster load times and higher availability use smaller memory/GB images whenever possible!

K8s Environments Release Cycles

The Kubernetes environments are kept up to date frequently, check X and Discord for notifications.

Creators should make sure their scenarios work on new Kubernetes versions.
The rapid images can be used to test next Kubernetes versions in advance. Make sure to switch back to the default images once these have been updated, so that you'll get time for testing during the next version update.

Verification Scripts

Verification scripts validate whether a user has completed a step correctly. When the user clicks the CHECK button, the script runs automatically. It passes if it exits with code 0.

{
  "steps": [
    {
      "title": "Create a pod",
      "text": "step1/text.md",
      "verify": "step1/verify.sh"
    }
  ]
}

See examples here and here

Scenario Examples

Find more examples in our Github Repository or in action here

Here we spin up a simple scenario based on Ubuntu 24.04. (Github)

{
  "title": "Ubuntu simple",
  "backend": {
    "imageid": "ubuntu"
  }
}

Here we create a more complex scenario based on Kubernetes. (Github)

{
  "title": "Kubernetes 2node multi-step verification",
  "details": {
    "intro": {
      "text": "intro.md"
    },
    "steps": [
      {
        "title": "Create a pod",
        "text": "step1/text.md",
        "verify": "step1/verify.sh"
      },
      {
        "title": "Delete a pod",
        "text": "step2/text.md",
        "verify": "step2/verify.sh"
      }
    ],
    "finish": {
      "text": "finish.md"
    }
  },
  "backend": {
    "imageid": "kubernetes-kubeadm-2nodes"
  }
}

Visual Editor (IDE)

Every environment has Theia installed, a full-blown in-browser IDE.
Read more about the implementation in our article.

Creators can select the Theia IDE to be shown by default instead of just a simple terminal:

{
  "title": "Use Theia by default",
  "backend": {
    "imageid": "ubuntu"
  },
  "interface": {
    "layout": "ide"
  }
}

Scenario Groups

It's possible to group scenarios together.

Find examples in our Github Repository or in action here

The simplest way of grouping scenarios is by putting them into the same subdirectory.

For more complex structures a structure.json file can be created to:

• Control sort order
• Reference scenarios from different groups or directories
• Override scenario attributes like title or description
• Exclude some directories

Once a structure.json is available, only the information from that file will be used. Any scenario or directory that exists outside the structure.json will be ignored.

See our example repository here with structure.json  here and here.

Assets & Images

Upload Assets

Upload files into the scenario environment on start. Place files in an assets directory and configure targets in index.json:

"assets": {
  "host01": [
    {"file": "conf.yaml", "target": "~/", "chmod": "+w"},
    {"file": "run.sh", "target": "/my/location", "chmod": "+x"},
    {"file": "**/*.*", "target": "/all"}
  ]
}

See the full example in action and on Github

Display Images in Markdown

Place image files next to your markdown file and reference them with relative paths:

![My image](./image.png)

![From subdirectory](./assets/image1.png)

<img src="./image2.png" width="100px">

See the full example in action and on Github

Custom Code Markdown Actions

Check the scenario examples about code blocks and actions here and here

Single line code blocks are automatically copyable per click:

`copy me`

But it can be disabled:

`copying disabled`{{}}

The user can also execute a command per click:

`ls -lh`{{exec}}

Also possible to send a Ctrl+c before running a command:

`whoami`{{exec interrupt}}

It's also possible to let the user copy or execute multiline code blocks:

```
kubectl get pod
kubectl get ns
```{{copy}}

```
cd /tmp
sh run.sh
```{{exec}}

Network Traffic into Environments

To access HTTP services running inside environments, a user can select the item from the terminal nav on top right:

NOTE: the services should be accessible via HTTP and not HTTPS.

Check the scenario examples about network traffic here and here

Creators can include special variables in the scenario markdown to make this easier for the user:

{{TRAFFIC_SELECTOR}}

{{TRAFFIC_HOST1_80}}

{{TRAFFIC_HOST2_4444}}

{{TRAFFIC_HOSTX_Y}}

[click here]({{TRAFFIC_HOST1_8080}})

Creators can generate URLs in bash scripts by using file /etc/killercoda/host:

sed 's/PORT/80/g' /etc/killercoda/host

Data Security

All Killercoda environments are ephemeral and isolated from each other. Access URLs are public and not password protected, though they contain unique IDs that make them practically impossible to guess. We strongly suggest to never use any production secrets or credentials inside Killercoda environments.

We also provide public Docker mirror cache proxies. Pulled images may be cached and become publicly available. If you don't want that, configure Docker/Podman in your scenarios to not use our default mirrors.

Read more on our Security page.

Host Addresses

The IP addresses of hosts inside environments never change. Every host can reach any other on:

For a two node Kubernetes environment this for example means:

Foreground and Background Scripts

It's possible to run commands or scripts once a user opens a scenario. This allows to setup whatever is needed before the user starts problem solving or learning.

It's not possible to pre-execute code even before a user opens a scenario.

When using foreground scripts, all commands will be shown to the user in the terminal. When using background scripts, the user won't see the executed commands.

You can setup a foreground script which waits for the background script to finish, like done here.

Every step can have a foreground and background script, like shown here.

In case of errors, the background scripts used in the "intro" section will be able to be inspected in the Creator Debug Section. Here are stdout, stderr and error details listed.

Scenario Lifetimes and Limitations

Scenarios can be used for a maximum of 1 hour with FREE and 4 hours with paid memberships. The time limit depends on the users and not the creators membership level. If the time is close to end a message will be shown to the user making aware of this.

When the scenario time limit is reached, the user will need to reload the browser tab to get access to a new environment.

Users can use/start as many scenarios as they wish, but only ever one concurrent scenario on FREE and three concurrent scenarios on paid memberships.

Activity

Get insights into the usage of your scenarios (total or scenario level) for the last 6 months.

Scenario Ratings

Users can rate your scenarios after completing them. Ratings are only visible to you as the creator and provide a way to receive feedback and improve your content.

You can filter ratings by time period and sort by best or worst score. Use lower ratings and their comments to identify areas for improvement. After making updates, check back later and filter by "1 week" to see if recent ratings reflect the changes.