> For the complete documentation index, see [llms.txt](https://docs.steadybit.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.steadybit.com/use-steadybit/experiments/design.md).

# Design

To start and eventually run a Chaos Engineering experiment, you first need to design it. That includes defining, e.g., where to run it (environment), what actions to perform (attacks, checks, load tests), and what should be attacked (targets).

## Basic Elements

An experiment generally consists of the following elements:

* **Name**: Giving your experiment a meaningful name makes it easier to find it again. You can change it at any time.
* **Team**: Each experiment is associated with a team. If you are a member of multiple teams, you can see and change your current team in the left-hand navigation sidebar. Once created, you can't change the experiment's team.
* **Environment**: An experiment always runs in one specific environment of your system landscape. This environment spans a set of targets you want to address in an experiment, such as containers and JVM applications in a Development stage. How the [environments are configured and assigned to your team](/install-and-configure/manage-environments.md) is up to your admin.
* **Variables**: A variable allows you to reference a value in your experiment's configuration to have a single source of truth. Steadybit supports different scopes (e.g., experiment variables or environment variables). Learn more in the [variables section](/use-steadybit/experiments/variables.md).
* **Hypothesis**: The hypothesis should answer the question of the expected outcome. In addition, you can describe the steady state, the turbulent condition, and the expected behavior. See this example of a hypothesis: 'When requests to the recommendation service exceed 1000ms, the catalog responds using an empty recommendation list.'
* **Tags**: Besides the hypothesis, tags can be applied to an experiment as useful metadata. Tags are not only listed in the experiments overview; you can also use them to search for specific experiments. In the experiment list, the ten most-used tags are listed right below the search bar (where you also find the full list of tags), giving you quick access.
* **Actions**: Performed when running the experiment, sequentially or in parallel. An action can be either
  * an **attack** to inject a fault into your system
  * a **check** to validate your expectation in your system or observability tooling
  * a **load test** to inject load into your system and validate functionality.

The team influences the experiment in the following aspects:

1. **Short Handle:** Each experiment gets a unique key with a team prefix (e.g., `SRE-23`), which is used, e.g., to trigger an experiment via the [API](/integrate-with-steadybit/api.md).
2. **Run/Edit Permissions:** Only team members are allowed to edit or run an experiment.
3. **Environment and Action Permissions:** A team's permission determines which environments (a set of targets or infrastructure components you can attack) and actions are eligible for an experiment.

## Create New Experiment

In general, you have three options to get started:

![Approaches to create an experiment](https://853194531-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZLJS2c8EXBcu8PiwteIJ%2Fuploads%2Fgit-blob-b4510b52f0ae9d9f3ec43a6022b5c81bc651b9a1%2FnewExperiment.png?alt=media)

* **From scratch**: in case you already have an experiment in mind
* **From template**: benefit from existing templates and adapt them to your context in a wizard
* **Upload** a YAML- or JSON-based file containing an exported experiment

### From Scratch

When creating an experiment from scratch, you land directly into our timeline-based experiment editor. If your team can access only one environment, it is selected automatically. Otherwise, you have to define which environment you want to experiment in. In addition, you can specify the experiment's name and hypothesis at any point you like.

After that, you can add all actions (attacks, checks, and load tests) to your experiment by dragging and dropping. When you place actions in the same horizontal lane, they are performed sequentially; placing them below each other results in a parallel run. Choose actions with the desired effect to perform your overall experiment.

![Create Experiment - Drag'n Drop Editor](https://853194531-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZLJS2c8EXBcu8PiwteIJ%2Fuploads%2Fgit-blob-e85e9df3086fdc577e90a06c962f7221a75f5f84%2Fcreate-experiment-blank.png?alt=media)

Once you've dropped the action or selected it later, you can define its configuration on the right-hand side.

#### Revealing a Step's Intention

When designing and running experiments as a team, it is a best practice to reveal every step's intention by renaming it. Click a step's label in the sidebar to rename it, so others can understand it at a glance.

![Create Experiment - Rename Steps in the Editor](https://853194531-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZLJS2c8EXBcu8PiwteIJ%2Fuploads%2Fgit-blob-cd271677071d319d3753c079dc62bcf79b15d88f%2Fcreate-experiment-blank-step-label.png?alt=media)

#### Target Selection

![Create Experiment - Target Selection in the Editor](https://853194531-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZLJS2c8EXBcu8PiwteIJ%2Fuploads%2Fgit-blob-e0876293801085473675fa21e7f5b15423ef4966%2Fcreate-experiment-blank-target-selection.png?alt=media)

You can now select the targets you want from your environment, via a target query referencing [discovered attributes](/concepts/discovery.md). Since these attribute values are always discovered live, some can change from one moment to the next. So, it is wise to choose stable attributes. Good examples are labels, namespaces, or symbolic names, whereas a unique identifier of a target (like the container ID) is usually a bad idea. When you run the experiment, these attributes are resolved into a concrete set of targets under attack. You can preview matching targets using the 'show targets' button next to the query.

#### Limiting Targets via Blast Radius

Furthermore, you can randomly limit your targets, so that only a subset of your target selection is attacked rather than all of it at once. You can choose between the basic blast radius, a simple randomizer across all target selections, and the advanced blast radius, allowing you to group your targets on a given attribute hierarchically.

**Basic Blast Radius**

The basic blast radius simply randomizes all selected targets and limits the subset by a percentage or a fixed number. The total number of attacked targets is shown at the top of the sidebar.

![Create Experiment - Limiting Targets in the Editor via Basic Blast Radius](https://853194531-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZLJS2c8EXBcu8PiwteIJ%2Fuploads%2Fgit-blob-c2ea16994da962fc2d3e592d728039c780fb39c4%2Fcreate-experiment-blank-limit-targets-basic-blast-radius.png?alt=media)

**Advanced Blast Radius**

The advanced blast radius allows you to hierarchically group your targets on a given attribute and attack only a subset of the groups. This is perfect whenever you need to add context to the randomization to express a more realistic blast radius.

Some common examples for this are

* attacking a random Kubernetes deployment in a cluster
* attacking a random Kubernetes pod of a specific deployment
* attacking one random service's components, but all in a random availability zone

The screenshot below shows an example where we group containers first on the label `k8s.label.domain`, and afterwards — within each group — on the availability zone. We will select 50% of the service groups and one availability zone.

![Create Experiment - Limiting Targets in the Editor via Advanced Blast Radius](https://853194531-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZLJS2c8EXBcu8PiwteIJ%2Fuploads%2Fgit-blob-21f4082e0733cce2d8e99bec4caf8bbf2dd9a0e5%2Fcreate-experiment-blank-limit-targets-advanced-blast-radius.png?alt=media)

So, in this example, we may attack all containers in, e.g.,

1. `k8s.label.domain` = `shop-inventory`, `shop-gateway`, `shop-products` and `aws.zone` = `eu-central-1a` *or*
2. `k8s.label.domain` = `shop-inventory`, `shop-gateway`, `shop-products` and `aws.zone` = `us-east-1a` *or*
3. `k8s.label.domain` = `shop-checkout`, `shop-orders`, `shop-products` and `aws.zone` = `eu-central-1b` *or*
4. ...

This lets you simulate a random zone becoming unavailable across random services (e.g. case 1, `eu-central-1a`), while leaving some domains unaffected (in case 1, `k8s.label.domain` = `shop-inventory`, because no containers of it run in `eu-central-1a`). The values actually picked are shown in the [run modal](/use-steadybit/experiments/run.md#advanced-blast-radius).

{% hint style="info" %}
A percentage limit can easily result in no targets while running the experiment. This can happen when specifying a low percentage or having a low number of targets in a group.

Steadybit rounds mathematically, so, for example, `20% of 2 targets` results in `0 targets`, which stops the experiment run. This is not validated when designing the experiment in case of the advanced blast radius.
{% endhint %}

In case you use a variable, template placeholder, or the API, you need to define the unit of the radius limit, like `50%` for percentage and `1#` for an absolute number.

#### Action and Attack Settings

Depending on the action chosen, you can configure different settings for the step. For instance, the 'fill memory' attack lets you configure how much memory to fill, the 'stop container' attack lets you configure whether the termination is graceful, and the 'HTTP check' lets you configure the expected success rate.

![Action Settings Example of 'Stress CPU'](https://853194531-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZLJS2c8EXBcu8PiwteIJ%2Fuploads%2Fgit-blob-df064537eb74691426d1347e6e79b049985362ad%2Fcreate-experiment-blank-action-settings.png?alt=media)

**Continue on Any Failures or Errors**

By default, a failed/errored step causes the entire experiment run to fail/error immediately. All steps have a configuration to continue an experiment run even when a failure or error occurred in the step's execution. Once activated, the step is still marked as a failure/error, but the experiment continues running and may still eventually end in `COMPLETED`. This is further described in the [experiment run state documentation](/use-steadybit/experiments/run.md#state-propagation).

Continue with these steps until you've designed your experiment. A reasonable experiment could easily look like the one below. Once you have saved it, you are ready to [run it](/use-steadybit/experiments/run.md) to learn how your system behaves.

![Create Experiment - Example in the Editor](https://853194531-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZLJS2c8EXBcu8PiwteIJ%2Fuploads%2Fgit-blob-6663fa6ceb62d8bee5d21456a2e0d3ecd8f75d1a%2Fcreate-experiment-blank-example.png?alt=media)

### From Template

A second option for creating a new experiment is using an existing template. This approach is best when you want to learn from others' experiences and apply them to your context via a step-by-step wizard. You can browse all available templates, or use our search to find one by the template's **tags**, by the **targets** or **actions** used in the experiment, or by free-text search.

![Create Experiment - Browse and Search Templates](https://853194531-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZLJS2c8EXBcu8PiwteIJ%2Fuploads%2Fgit-blob-7ddf669d098ad6ffcbc8342c8ffdabf992bb9cff%2Fcreate-experiment-template.png?alt=media)

Once you've decided to use an experiment template, you are guided step-by-step through applying it to your context. The first step asks you to select the environment where you eventually want to run your experiment. If the experiment template references any [variables](/use-steadybit/experiments/variables.md) (via the `{{variable}}` syntax), they are also listed so you can decide how each one should be resolved:

* **Provide a value** — the variable is created as an [environment variable](/use-steadybit/experiments/variables.md#environment) on the selected environment and shared with all experiments using that environment. You only need to provide values for variables that don't exist on the environment yet; existing ones are reused automatically.
* **Leave the value empty** — the variable falls back to an [experiment variable](/use-steadybit/experiments/variables.md#experiment). It then shows up in the created experiment, where you provide its value in the experiment variable's dropdown in the editor's subheader.

If you create the experiment within a [service](/use-steadybit/services.md), any variable already defined as a [service variable](/use-steadybit/experiments/variables.md#service) is resolved from the service, so you don't need to specify it as an environment or experiment variable.

![Create Experiment - Use Template: Environment](https://853194531-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZLJS2c8EXBcu8PiwteIJ%2Fuploads%2Fgit-blob-9bddf3c8670ebfc0edac7f2909bab0c78aac3671%2Fcreate-experiment-template-wizard1.png?alt=media)

The subsequent steps depend on the selected experiment template and will guide you step-by-step to a ready-to-be-executed experiment. Each step asks for one specific value (e.g., a Kubernetes deployment) to adapt the template's experiment to your context.

![Create Experiment - Use Template: Further Steps](https://853194531-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZLJS2c8EXBcu8PiwteIJ%2Fuploads%2Fgit-blob-371a4bbb6444982dde46acd086df0ba92547b4cb%2Fcreate-experiment-template-wizard2.png?alt=media)

Eventually, you end up in the experiment editor, where you can adjust the experiment or [run it](/use-steadybit/experiments/run.md) to learn how your system behaves.

![Create Experiment - Use Template: Further Steps](https://853194531-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZLJS2c8EXBcu8PiwteIJ%2Fuploads%2Fgit-blob-1533e94607a67540acd4e3d1441d5de41ee71192%2Fcreate-experiment-template-wizard3.png?alt=media)

### Via File Upload

The third option for creating a new experiment is to upload a YAML- or JSON-based experiment file. Once you've uploaded the file, the experiment is created in the defined team. Please note that when the experiment file references an explicit team and environment (e.g., `team: "ADM"` or `environment: "Online shop"`), they have to exist. If you want to be flexible, you can use the variable `{{teamKey}}` to apply it to the current team and `{{environmentName}}` to apply it to the team's first environment.

## Action and Template Documentation

Within the experiment editor, you can read the full documentation of an action or a template by clicking the individual step. It covers the exact details, the use cases, and all of the parameters.

![Experiment Editor - Action Documentation](https://853194531-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZLJS2c8EXBcu8PiwteIJ%2Fuploads%2Fgit-blob-58495ff47da995eae647c6ce0e29c4dad50a18ca%2Fexperiment-action-documentation.png?alt=media)

The documentation of a template is coming from the [experiment template's description](/install-and-configure/manage-experiment-templates.md#template-description). The documentation of an action is provided via the [Hub Connection](/integrate-with-steadybit/hubs.md), and can also be provided for your own custom actions.

## Supported Actions

Check out our [Reliability Hub](https://hub.steadybit.com/actions) to learn about actions you can leverage with Steadybit or learn more about the [concept of an action](/concepts/actions.md).