From 4a5f015c0782d41bffa038b538f398773e28351e Mon Sep 17 00:00:00 2001 From: suntiwari3495-arch Date: Fri, 24 Oct 2025 09:10:06 +0000 Subject: [PATCH 1/4] fix/docs: add litmusctl-syntax.md file with comprehensive documentation Signed-off-by: suntiwari3495-arch --- website/docs/litmusctl/litmusctl-syntax.md | 364 +++++++++++++++++++++ 1 file changed, 364 insertions(+) create mode 100644 website/docs/litmusctl/litmusctl-syntax.md diff --git a/website/docs/litmusctl/litmusctl-syntax.md b/website/docs/litmusctl/litmusctl-syntax.md new file mode 100644 index 00000000..8682bce7 --- /dev/null +++ b/website/docs/litmusctl/litmusctl-syntax.md @@ -0,0 +1,364 @@ +# Litmusctl Syntax + +## Overview + +`litmusctl` is a command-line tool for managing LitmusChaos infrastructure plane. It follows a structured syntax pattern that makes it intuitive to use for various chaos engineering operations. + +## Basic Syntax + +```bash +litmusctl [command] [TYPE] [flags] +``` + +### Components + +- **Command**: Specifies the operation you want to perform (e.g., `connect`, `create`, `get`, `config`, `disconnect`, `run`, `update`) +- **Type**: Refers to the resource type you're operating on (e.g., `chaos-infra`, `project`, `chaos-experiment`, `chaos-environment`) +- **Flags**: Additional parameters that provide specific information for the operation (e.g., `--project-id`, `--non-interactive`, `--config`) + +## Available Commands + +### 1. `config` - Configuration Management + +Manage litmusctl accounts and configuration settings. + +#### Subcommands + +**Set Account** +```bash +litmusctl config set-account +``` +Configure a new ChaosCenter account with endpoint, username, and password. + +**Use Account** +```bash +litmusctl config use-account --endpoint="" --username="" +``` +Switch between multiple configured accounts. + +**Get Accounts** +```bash +litmusctl config get-accounts +``` +List all configured accounts in `.litmusconfig`. + +**View Configuration** +```bash +litmusctl config view +``` +Display current `.litmusconfig` settings. + +--- + +### 2. `connect` - Connect Resources + +Establish connections to chaos resources. + +**Connect Chaos Infrastructure** +```bash +litmusctl connect chaos-infra +``` + +**Flags:** +- `--project-id`: Specify the project ID +- `--environment-id`: Specify the environment ID +- `--non-interactive`: Enable non-interactive mode (all required information must be provided via flags) +- `--installation-mode`: Installation mode (`cluster` or `namespace`) +- `--chaos-infra-name`: Name for the chaos infrastructure +- `--chaos-infra-description`: Description for the chaos infrastructure +- `--platform-name`: Platform name (AWS, GKE, Openshift, Rancher, Others) +- `--namespace`: Kubernetes namespace for installation +- `--service-account`: Service account name +- `--skip-ssl`: Skip SSL/TLS verification (true/false) +- `--node-selector`: Node selector for deployments + +**Example (Non-interactive mode):** +```bash +litmusctl connect chaos-infra \ + --project-id="" \ + --environment-id="" \ + --chaos-infra-name="my-chaos-infra" \ + --installation-mode="cluster" \ + --non-interactive +``` + +--- + +### 3. `disconnect` - Disconnect Resources + +Disconnect chaos resources from ChaosCenter. + +**Disconnect Chaos Infrastructure** +```bash +litmusctl disconnect chaos-infra --project-id="" +``` + +**Example:** +```bash +litmusctl disconnect chaos-infra 13dsf3d1-5324-54af-4g23-5331g5v2364f --project-id="50addd40-8767-448c-a91a-5071543a2d8e" +``` + +--- + +### 4. `create` - Create Resources + +Create new projects, experiments, and environments. + +**Create Project** +```bash +litmusctl create project --name="" +``` + +**Create Chaos Environment** +```bash +litmusctl create chaos-environment +``` +You will be prompted for: +- Project ID +- Environment Name +- Environment Type (Production/Non-Production) + +**Create Chaos Experiment** +```bash +litmusctl create chaos-experiment -f --project-id="" --chaos-infra-id="" +``` + +**Flags:** +- `-f`: Path to experiment manifest file +- `--project-id`: Target project ID +- `--chaos-infra-id`: Target chaos infrastructure ID + +**Example:** +```bash +litmusctl create chaos-experiment \ + -f custom-chaos-experiment.yml \ + --project-id="eb7fc0a0-5878-4454-a9db-b67d283713bc" \ + --chaos-infra-id="e7eb0386-085c-49c2-b550-8d85b58fd" +``` + +--- + +### 5. `get` - Retrieve Information + +Query and list various resources. + +**Get Projects** +```bash +litmusctl get projects +``` +Lists all projects accessible to the user with their IDs, names, and creation timestamps. + +**Get Chaos Infrastructures** +```bash +litmusctl get chaos-infra +``` +You will be prompted for the Project ID. Returns infrastructure ID, name, and status. + +**Get Chaos Environments** +```bash +litmusctl get chaos-environment +``` +Lists chaos environments with their IDs, names, types, and timestamps. + +**Get Chaos Experiments** +```bash +litmusctl get chaos-experiments +``` +Lists chaos experiments within a project. + +--- + +### 6. `run` - Execute Operations + +Execute chaos experiments and other operations. + +**Run Chaos Experiment** +```bash +litmusctl run chaos-experiment +``` +You will be prompted for: +- Project ID +- Chaos Experiment ID + +**Example:** +```bash +litmusctl run chaos-experiment +# Enter the Project ID: eb7fc0a0-5878-4454-a9db-b67d283713bc +# Enter the Chaos Experiment ID: test_exp +``` + +--- + +### 7. `update` - Update Resources + +Modify existing resources and settings. + +**Update Password** +```bash +litmusctl update password +``` +Change the password for your ChaosCenter account. You will be prompted for: +- Username +- Old Password +- New Password +- Confirm Password + +--- + +### 8. `version` - Version Information + +**Check Version** +```bash +litmusctl version +``` +Display the current version of litmusctl. + +--- + +## Global Flags + +These flags can be used with most commands: + +- `--config`: Specify a custom config file path (default: `${HOME}/.litmusconfig`) +- `--help` or `-h`: Display help information for any command + +--- + +## Interactive vs Non-Interactive Mode + +### Interactive Mode +By default, litmusctl operates in interactive mode where it prompts you for required information. + +```bash +litmusctl connect chaos-infra +# Will prompt for all required details +``` + +### Non-Interactive Mode +Use the `--non-interactive` flag along with all required flags to run commands without prompts. + +```bash +litmusctl connect chaos-infra \ + --project-id="" \ + --environment-id="" \ + --chaos-infra-name="my-infra" \ + --non-interactive +``` + +**Note:** Only `litmusctl connect chaos-infra` requires the `--non-interactive` flag. Other commands automatically use non-interactive mode when all required flags are provided. + +--- + +## Configuration File + +litmusctl uses the `.litmusconfig` file to manage multiple accounts: + +- **Default Location:** `${HOME}/.litmusconfig` +- **Custom Location:** Use `--config` flag to specify a different location +- **No Merging:** If `--config` is specified, only that file is loaded (no merging with default config) + +--- + +## Common Workflows + +### Initial Setup +```bash +# 1. Configure your account +litmusctl config set-account + +# 2. View configured accounts +litmusctl config get-accounts + +# 3. Create or select a project +litmusctl create project --name="my-project" +litmusctl get projects +``` + +### Connecting Infrastructure +```bash +# 1. Create an environment (if needed) +litmusctl create chaos-environment + +# 2. Connect chaos infrastructure +litmusctl connect chaos-infra + +# 3. Verify connection +litmusctl get chaos-infra +``` + +### Running Experiments +```bash +# 1. Create experiment +litmusctl create chaos-experiment -f experiment.yml --project-id="" --chaos-infra-id="" + +# 2. Run experiment +litmusctl run chaos-experiment + +# 3. List experiments +litmusctl get chaos-experiments +``` + +--- + +## Examples + +### Example 1: Complete Setup in Non-Interactive Mode +```bash +# Set account +litmusctl config set-account \ + --endpoint="https://chaos.example.com" \ + --username="admin" \ + --password="password" + +# Create project +litmusctl create project --name="production-chaos" + +# Get project ID +litmusctl get projects + +# Connect infrastructure +litmusctl connect chaos-infra \ + --project-id="50addd40-8767-448c-a91a-5071543a2d8e" \ + --environment-id="prod-env" \ + --chaos-infra-name="prod-cluster-1" \ + --installation-mode="cluster" \ + --platform-name="GKE" \ + --namespace="litmus" \ + --non-interactive +``` + +### Example 2: Interactive Workflow +```bash +# Configure account interactively +litmusctl config set-account +# Follow prompts for endpoint, username, password + +# Connect infrastructure interactively +litmusctl connect chaos-infra +# Follow prompts for all required details + +# Create and run experiment interactively +litmusctl create chaos-experiment -f my-experiment.yml +# Follow prompts for project-id and chaos-infra-id + +litmusctl run chaos-experiment +# Follow prompts for project-id and experiment-id +``` + +--- + +## Tips and Best Practices + +1. **Use Descriptive Names:** Give meaningful names to your infrastructure and experiments for easier management +2. **Leverage Non-Interactive Mode:** Use non-interactive mode in CI/CD pipelines and automation scripts +3. **Version Compatibility:** Always check compatibility between litmusctl version and ChaosCenter version +4. **Multiple Accounts:** Use `config get-accounts` and `config use-account` to manage multiple ChaosCenter environments +5. **Namespace Mode vs Cluster Mode:** Choose installation mode based on your RBAC requirements and blast radius preferences + +--- + +## Additional Resources + +- For detailed usage examples, refer to the [litmusctl usage documentation](https://github.com/litmuschaos/litmusctl/blob/master/Usage_0.23.0.md) +- For installation instructions, see the [litmusctl installation guide](https://docs.litmuschaos.io/docs/litmusctl/installation) +- For prerequisites and requirements, check the [litmusctl README](https://github.com/litmuschaos/litmusctl/blob/master/README.md) \ No newline at end of file From 7055d87e7c51166220e5cbe7ec33c070346be850 Mon Sep 17 00:00:00 2001 From: suntiwari3495-arch Date: Fri, 24 Oct 2025 09:11:14 +0000 Subject: [PATCH 2/4] fix line ending Signed-off-by: suntiwari3495-arch --- website/docs/litmusctl/litmusctl-syntax.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/litmusctl/litmusctl-syntax.md b/website/docs/litmusctl/litmusctl-syntax.md index 8682bce7..c2052f29 100644 --- a/website/docs/litmusctl/litmusctl-syntax.md +++ b/website/docs/litmusctl/litmusctl-syntax.md @@ -361,4 +361,4 @@ litmusctl run chaos-experiment - For detailed usage examples, refer to the [litmusctl usage documentation](https://github.com/litmuschaos/litmusctl/blob/master/Usage_0.23.0.md) - For installation instructions, see the [litmusctl installation guide](https://docs.litmuschaos.io/docs/litmusctl/installation) -- For prerequisites and requirements, check the [litmusctl README](https://github.com/litmuschaos/litmusctl/blob/master/README.md) \ No newline at end of file +- For prerequisites and requirements, check the [litmusctl README](https://github.com/litmuschaos/litmusctl/blob/master/README.md) From 29f20e812cac4b3a5e44fc2157f19e3e14d70678 Mon Sep 17 00:00:00 2001 From: suntiwari3495-arch Date: Sat, 25 Oct 2025 13:36:26 +0530 Subject: [PATCH 3/4] Remove tips section and update resource links address the review from maintainer Removed tips and best practices section from litmusctl syntax documentation and updated resource links. Signed-off-by: suntiwari3495-arch --- website/docs/litmusctl/litmusctl-syntax.md | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/website/docs/litmusctl/litmusctl-syntax.md b/website/docs/litmusctl/litmusctl-syntax.md index c2052f29..fba60457 100644 --- a/website/docs/litmusctl/litmusctl-syntax.md +++ b/website/docs/litmusctl/litmusctl-syntax.md @@ -347,18 +347,8 @@ litmusctl run chaos-experiment --- -## Tips and Best Practices - -1. **Use Descriptive Names:** Give meaningful names to your infrastructure and experiments for easier management -2. **Leverage Non-Interactive Mode:** Use non-interactive mode in CI/CD pipelines and automation scripts -3. **Version Compatibility:** Always check compatibility between litmusctl version and ChaosCenter version -4. **Multiple Accounts:** Use `config get-accounts` and `config use-account` to manage multiple ChaosCenter environments -5. **Namespace Mode vs Cluster Mode:** Choose installation mode based on your RBAC requirements and blast radius preferences - ---- - ## Additional Resources -- For detailed usage examples, refer to the [litmusctl usage documentation](https://github.com/litmuschaos/litmusctl/blob/master/Usage_0.23.0.md) -- For installation instructions, see the [litmusctl installation guide](https://docs.litmuschaos.io/docs/litmusctl/installation) -- For prerequisites and requirements, check the [litmusctl README](https://github.com/litmuschaos/litmusctl/blob/master/README.md) +- For detailed usage examples, refer to the [litmusctl usage documentation](/docs/next/litmusctl/litmusctl-usage) +- For installation instructions, see the [litmusctl installation guide](/docs/next/litmusctl/installation) +- [Contribute to litmusctl](https://github.com/litmuschaos/litmusctl) From c2c53481cbf74dcbb7b865fbd28877f41072e3c1 Mon Sep 17 00:00:00 2001 From: suntiwari3495-arch Date: Sat, 25 Oct 2025 13:37:30 +0000 Subject: [PATCH 4/4] add the file path in sidebar.js Signed-off-by: suntiwari3495-arch --- website/sidebars.js | 1 + 1 file changed, 1 insertion(+) diff --git a/website/sidebars.js b/website/sidebars.js index 3c0e9847..753335de 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -149,6 +149,7 @@ module.exports = { collapsible: false, items: [ 'litmusctl/installation', + 'litmusctl/litmusctl-syntax', { type: 'category', label: 'Litmusctl Usage',