diff --git a/website/docs/litmusctl/create-chaos-experiment.md b/website/docs/litmusctl/create-chaos-experiment.md index 6899b2c9..e87fb13f 100644 --- a/website/docs/litmusctl/create-chaos-experiment.md +++ b/website/docs/litmusctl/create-chaos-experiment.md @@ -4,7 +4,188 @@ title: Create Chaos Experiment sidebar_label: Create Chaos Experiment --- +# Create a Chaos Experiment (litmusctl) -This guide demonstrates how to create and run chaos experiments using litmusctl. You can create experiments using manifest files and manage them through the command line interface. +This document explains how to create and manage Chaos Experiments using `litmusctl`. -Follow this [guide](https://github.com/litmuschaos/litmusctl/blob/master/Usage_0.23.0.md#steps-to-create-a-chaos-experiment) to create Chaos Experiment. +> **Prerequisite:** You should have a configured `litmusctl` account. See `litmusctl config set-account` to add an account. + +--- + +## litmusctl quick syntax + +```shell +litmusctl [command] [TYPE] [flags] +``` + +- **command**: what you want to perform (`connect`, `create`, `get`, `run`, `describe`, `delete`, etc.) +- **TYPE**: the resource type (e.g., `chaos-infra`, `project`, `chaos-experiment`) +- **flags**: additional information for the command (for example `--project-id`, `--chaos-infra-id`, `--endpoint`, `--non-interactive`) + +`litmusctl` uses a config file at `${HOME}/.litmusconfig` by default. You can override this with `--config `. + +If required flags are not provided, `litmusctl` will prompt you interactively unless you use `--non-interactive`. + +--- + +## 1. Setup account (if not already done) + +```shell +# interactive (recommended) +litmusctl config set-account + +# non-interactive (example) +litmusctl config set-account --endpoint="https://preview.litmuschaos.io" --username="admin" --password="PASSWORD" +``` + +After running, verify using: + +```shell +litmusctl config view +``` + +--- + +## 2. Get project and chaos-infra IDs + +You will need `project-id` and `chaos-infra-id` to create an experiment. + +```shell +litmusctl get projects +# Note the PROJECT ID you want to use. + +litmusctl get chaos-infra --project-id "" +# Note the CHAOS INFRA ID from the output. +``` + +--- + +## 3. Create a Chaos Experiment from a manifest + +You can create a Chaos Experiment by passing a YAML manifest: + +```shell +litmusctl create chaos-experiment -f custom-chaos-experiment.yml --project-id "" --chaos-infra-id "" +``` + +If creation is successful, you will receive confirmation and the created experiment ID. + +**Example:** +```text +🚀 Chaos Experiment/experiment-1 successfully created 🎉 +``` + +--- + +## 4. Save a Chaos Experiment (store manifest in Litmus) + +If you want to save an experiment manifest in the project: + +```shell +litmusctl save chaos-experiment -f custom-litmus-experiment.yaml --project-id "" +``` + +--- + +## 5. Run a Chaos Experiment + +You can run a previously created experiment by ID: + +```shell +litmusctl run chaos-experiment --project-id "" --chaos-experiment-id "" +``` + +If the command prompts for values, provide the requested `project-id` and `experiment-id`. + +--- + +## 6. Verify the experiment & runs + +- To list all experiments in a project: +```shell +litmusctl get chaos-experiment --project-id "" +``` + +- To list runs for a project: +```shell +litmusctl get chaos-experiment-runs --project-id "" +``` + +- To list runs for a specific experiment: +```shell +litmusctl get chaos-experiment-runs --project-id "" --experiment-id "" +``` + +- To describe a specific experiment: +```shell +litmusctl describe chaos-experiment --project-id "" +# Or use interactive mode: `litmusctl describe chaos-experiment` +``` + +--- + +## 7. Delete an experiment + +```shell +litmusctl delete chaos-experiment --project-id "" +# or interactive: litmusctl delete chaos-experiment +``` + +--- + +## Useful extra commands + +```shell +# View config file +litmusctl config view + +# List accounts in config +litmusctl config get-accounts + +# Switch current account (interactive) +litmusctl config use-account + +# Create a project (interactive) +litmusctl create project +``` + +--- + +## Flags (summary) + +| Flag | Type | Description | +|----------|---------|-------------| +| `--config` | string | path to config file (default: $HOME/.litmusctl) | +| `--cacert` | string | custom CA certificate for communicating with portal | +| `--skipSSL` | bool | skip TLS/SSL verification | +| `--help` / `-h` | | show command help | + +Use `litmusctl --help` or `litmusctl --help` for more details. + +--- + +## Notes & troubleshooting + +- **Interactive vs non-interactive:** For scripts, prefer `--non-interactive` and pass required flags; otherwise `litmusctl` prompts for missing values. +- **Project & infra IDs** are required for many operations — use `litmusctl get projects` and `litmusctl get chaos-infra` to retrieve them. +- **Permissions:** Ensure the account has sufficient permissions to create/run experiments (cluster vs namespace mode). +- **Preview:** After creating/running experiments, verify status in ChaosCenter UI (Targets → Chaos Infrastructures / Experiments). + +--- + +## Example flow (compact) + +```shell +# set account +litmusctl config set-account --endpoint="https://preview.litmuschaos.io" --username="admin" --password="PASSWORD" + +# get project id and infra id +litmusctl get projects +litmusctl get chaos-infra --project-id "" + +# create from manifest +litmusctl create chaos-experiment -f custom-chaos-experiment.yml --project-id "" --chaos-infra-id "" + +# list runs +litmusctl get chaos-experiment-runs --project-id "" +```