Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

m-agent User Docs #185

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added website/docs/assets/m-agent-design.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
42 changes: 42 additions & 0 deletions website/docs/m-agent/installation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
id: installation
title: Install m-agent
sidebar_label: Installation
---

---

## Pre-Requisites
1. Linux OS
2. systemd
3. Experiment specific third-party binaries (to be listed in the experiment docs)

## Installation
To install m-agent in your target machine, you can execute the following commands in the target machine:
```
$ curl -fsSL -o get_m-agent.sh https://raw.githubusercontent.com/litmuschaos/m-agent/master/scripts/install.sh
$ chmod 700 get_m-agent.sh
$ ./get_m-agent.sh
```
You can specify any particular m-agent version for installation:
```
$ ./get_m-agent.sh --version <VERSION>
```
By default, `41365` port is utilized by m-agent. You can specify a custom port at which m-agent should listen for client messages:
```
$ ./get_m-agent.sh --port <PORT>
```
Finally, you can specify if the installation can take place without using sudo, if it is not present:
```
$ ./get_m-agent.sh --no-sudo
```

To confirm whether the installation was successful or not, you can firstly check if the m-agent service is in an `active` state:
```
systemctl status m-agent
```

Then, you can confirm if the m-agent binary is correctly setup and working:
```
m-agent -help
```
34 changes: 34 additions & 0 deletions website/docs/m-agent/overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
id: overview
title: m-agent
sidebar_label: Overview
---

---

Machine Agent, a.k.a. m-agent is a lightweight, platform-generic daemon agent that can remotely inject faults into machine scoped resources as part of the LitmusChaos Experiments.

## Why do you need m-agent?
In the context of machine-scoped chaos experiments for LitmusChaos, despite using various cloud platform specific VM agents for the execution of the chaos, there have been several limitations such as:
- Inflexible APIs for remote execution of bash commands, which translates to poor chaos orchestration and chaos rollback abilities.
- Individual experiment codebase for each cloud platform, which is difficult to maintain.
- Lack of observability of resources in the target machine during the chaos injection.
- Limited scope for Litmus probes as they can’t be executed within the target machine.

To address these issues, m-agent has been introduced. m-agent provides many advantages over the current approach, such as:
- Enhanced OS resource state monitoring in the target machine
- Ability to run Litmus probes natively within the target machine
- Establishes the basis for injecting application-level chaos in further iterations
- Introduces error classification for simplifying the process of their mitigation

## How does m-agent work?
m-agent is essentially a web server which lies within the target machine, where it performs different actions on behalf of the experiment pod, that lies in the execution plane. These actions include, but are not limited to:
- Check Steady State
- Inject Chaos
- Execute Litmus Probe
- Revert Chaos
- Check Liveness

The experiment pod and m-agent communicate with each other using the [websocket](https://en.wikipedia.org/wiki/WebSocket) protocol.
<img src={require("../assets/m-agent-design.png").default} alt="m-agent design summary" />

14 changes: 14 additions & 0 deletions website/docs/m-agent/uninstallation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
---
id: uninstallation
title: Uninstall m-agent
sidebar_label: Uninstallation
---

---

If you wish to uninstall m-agent, you can execute the following commands in the target machine:
```
$ curl -fsSL -o remove_m-agent.sh https://raw.githubusercontent.com/litmuschaos/m-agent/master/scripts/uninstall.sh
$ chmod 700 remove_m-agent.sh
$ ./remove_m-agent.sh
```
35 changes: 35 additions & 0 deletions website/docs/m-agent/usage.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
---
id: usage
title: m-agent Usage
sidebar_label: Usage
---

Upon installing m-agent, you can use it to generate a token for your Chaos Experiment. It will require you to specify an expiry duration for your token. Tokens are valid from a minimum duration of 1 minute to a maximum of 30 days. The token can be generated in two modes:

1. Interactive Mode
2. Non-Interactive Mode

To generate a token in interactive mode, use the -get-token boolean flag, which will prompt you to select the expiry duration for the token:
```
m-agent -get-token
```

The non-interactive mode can be used to generate token with more flexibility in terms of its expiry duration. Use the -token-expiry-duration flag along with the -get-token flag to use this mode. -token-expiry-duration is a string flag which expects the expiry duration of the token to be specified in the form of a numeric value suffixed with a single alphabet out of 'm' or 'M', 'h' or 'H', and 'd' or 'D' denoting minutes, hours, and days respectively.

For minutes, the corresponding value must lie in between 1 and 60, inclusively. For hours, the corresponding value must lie in the range of 1 to 24, inclusively. Lastly, for days, the corresponding value must lie between 1 to 30, inclusively.

As an instance, to create a token with a validity of 30 minutes, one can use the following command:
neelanjan00 marked this conversation as resolved.
Show resolved Hide resolved
```
m-agent -get-token -token-expiry-duration 30m
```

Similarly, a token valid for 15 days from the time of creation can be specified as:
```
m-agent -get-token -token-expiry-duration 15D
```

You can also update the port at which m-agent should listen for the client messages:
```
sudo m-agent -updated-port <NEW_PORT>
sudo systemctl restart m-agent
```
10 changes: 10 additions & 0 deletions website/sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -165,6 +165,16 @@ module.exports = {
]
},

// m-agent
{
"m-agent": [
'm-agent/overview',
'm-agent/installation',
'm-agent/usage',
'm-agent/uninstallation'
]
},

// Integrations
{
Integrations: ['integrations/prometheus', 'integrations/grafana']
Expand Down