Merge pull request #13 from northpowered/5-mkdocs-documentation

5 mkdocs documentation

.github/workflows/docker-image.yml

@@ -45,4 +45,4 @@ jobs:
         context: .
         push: ${{ github.event_name != 'pull_request' }}
         tags: ${{ steps.meta.outputs.tags }}
-        labels: ${{ steps.meta.outputs.labels }}
+        labels: ${{ steps.meta.outputs.labels }}

.github/workflows/documetation-deployment.yml

@@ -0,0 +1,17 @@
+name: Documentation deployment
+
+on:
+  push:
+    branches:
+      - master 
+      - main
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.10
+      - run: pip install mkdocs-material 
+      - run: mkdocs gh-deploy --force

README.md

@@ -1,5 +1,5 @@
 [![CodeFactor](https://www.codefactor.io/repository/github/northpowered/simplesla/badge)](https://www.codefactor.io/repository/github/northpowered/simplesla)
-
+[![Docker Image CI/CD](https://github.com/northpowered/SimpleSLA/actions/workflows/docker-image.yml/badge.svg)](https://github.com/northpowered/SimpleSLA/actions/workflows/docker-image.yml)
 # SimpleSLA
 
 Easy SLA control system for distribiuted networks
@@ -29,6 +29,12 @@ TODO:
   - Tests
 
 ## Usage
+
+### Running from source
+> pip install -r requirements.txt
+
+> python3 main.py  -c config.yml
+### In CLI mode
 ```bash
 python3 main.py -c CONFIG
 
@@ -42,31 +48,21 @@ optional arguments:
                         Logging path {stdout,FILE}
   --version             show programs version number and exit
 ```
+### Using docker image
+> docker pull ghcr.io/northpowered/simple-sla:latest
 
+> docker run --name simple-sla ghcr.io/northpowered/simple-sla:latest
 ## SLA statuses
 
-| Status      | Int value   | Reccomended color | Description |
+| Status      | Int value   | Recommended color | Description |
 | ----------- | ----------- |------------------ |------------ |
 | NoData      | 0           | Black             | No recieved data or parcing error |
 | Normal      | 1           | Green             | Target is available and RTT less then policy |
 | Warning     | 2           | Yellow            | Target is available and RTT bigger then policy |
 | Error       | 3           | Red               | Target is unavailable |
 | OutOfService| 4           | Green             | Target is available and policy was not defined |
 
-### Install:
-
-```bash
-    pip install -r requirements.txt
-    python3 main.py  -c config.yml
-```
-### Docker
-
-```bash
-    docker build -t simplesla:yourtag .
-    docker run -p "8800:8800" simplesla:yourtag
-```
-
-### Configuration
+## Configuration
 
 All config is represented in YAML format
 

docker-compose.yml

@@ -5,9 +5,9 @@ networks:
     driver: bridge
 
 services:
-  sla-simplesla:
-    image: "simplesla:latest"
-    container_name: sla-simplesla
+  simple-sla:
+    image: "ghcr.io/northpowered/simple-sla:latest"
+    container_name: simple-sla
     restart: always
     environment:
       - SSLA_LL=INFO

docs/configuration/examples.md

@@ -0,0 +1,63 @@
+# Examples
+
+## Typical full config file
+
+```yaml
+Server:
+  bind_address: '0.0.0.0'
+  port: 8800
+  refresh_time: 2
+
+Global:
+  unit: 'ms'
+
+Local:
+  src_addr: '0.0.0.0' 
+  timeout: 1
+  ttl: 64
+  size: 56
+
+Devices:
+  - name: 'RT_1'
+    type: 'cisco'
+    transport: 'telnet'
+    address: '192.168.0.1'
+    username: 'user'
+    password: 'password'
+    port: 23
+  - name: 'RT_2'
+    type: 'juniper'
+    transport: 'ssh'
+    address: '192.168.0.9'
+    username: 'user'
+    password: 'password'
+    port: 22
+
+
+Policies:
+  - name: mypolicy
+    max_rtt: 0.9
+
+ServicesGroups:
+  - name: mygroup
+    device: 'RT_1'
+    services:
+      - name: serv1
+        target: '10.26.6.3'
+        delay: 3
+        policy: mypolicy
+      - name: serv2
+        target: '10.26.6.9'
+        delay: 8
+
+Services:
+  - name: 'service01'
+    device: 'simplesla-local'
+    target: '192.168.0.24'
+    delay: 16
+  - name: 'service02'
+    device: 'RT_2'
+    target: '16.2.6.9'
+    delay: 5
+    policy: mypolicy
+```

docs/configuration/index.md

@@ -0,0 +1,144 @@
+# Configuration structure
+
+All configuration options defined in one YAML file, ex `config.yaml`, that has some sections, represented below.
+
+## *Server*
+
+Settings for a HTTP server of Prometheus endpoint 
+
+```yaml
+Server:
+  bind_address: '0.0.0.0'
+  port: 8800
+  refresh_time: 20
+```
+**`bind address`** - Ipv4 or DSN for binding http server with metrics
+
+**`port`** - Port for http server
+
+**`refresh_time`** (seconds) - Time of updating data in prometheus endpoint. This is independent from collectors of these metrics
+
+## *Global*
+
+Global settings for metric collectors
+
+```yaml
+Global:
+  unit: 'ms'
+```
+**`unit`** - Unit of Round-Trip-Time (RTT) in collected metrics
+
+## *Local*
+
+Settings of `simplesla-local` device for ICMP checks
+
+```yaml
+Local:
+  src_addr: '0.0.0.0' 
+  timeout: 1
+  ttl: 64
+  size: 56
+```
+**`src_addr`** - Source address for ICMP requests from SimpleSLA
+
+**`timeout`** (seconds) - Timeout for ICMP requests
+
+**`ttl`** - TTL for outgoing packets
+
+**`size`** (bytes) - Payload size of ICMP packets
+
+## *Devices*
+
+List of registered devices
+
+```yaml
+Devices:
+  - name: 'my_device'
+    type: 'cisco'
+    transport: 'ssh'
+    address: '192.168.0.1'
+    username: 'user'
+    password: 'password'
+    port: 22
+```
+**`name`** - Unique name of device, using in metric`s labels
+
+**`type`** - Type of device, see full list of supported devices [here](../supported_devices.md)
+
+**`transport`** - protocol to connect to the device, `ssh` and `telnet` are supported now
+
+**`address`** - IPv4 or DSN of the device
+
+**`username`** - Username to login to the device
+
+**`password`** - Password for the account
+
+**`port`** - Port number for connection
+
+## *Policies*
+
+List of policies to define status of service
+
+```yaml
+Policies:
+  - name: mypolicy
+    max_rtt: 0.15
+```
+
+**`name`** - Unique name of the policy
+
+**`max_rtt`** - Max value of RTT to change service status
+
+## *Services*
+
+List of single services for metric collection
+
+```yaml
+Services:
+  - name: 'my_service01'
+    device: 'simplesla-local'
+    target: '192.168.0.10'
+    delay: 3
+    policy: mypolicy
+  - name: 'my_service02'
+    device: 'my_device'
+    target: '10.35.45.91'
+    delay: 7
+```
+
+**`name`** - Unique name of the service, using on metric`s labels
+
+**`device`** - Name of the source device. Device MUST be defined in [Devices](index.md#devices) section
+
+**`target`** - IPv4 or DSN as a destionation for checks
+
+**`delay`** (seconds) - Pause between checking sessions
+
+**`policy`** (*OPTIONAL*) - If using, MUST be defined in [Policies](index.md#policies) section
+
+## *ServicesGroups*
+
+```yaml
+ServicesGroups:
+  - name: mygroup
+    device: 'my_device'
+    delay: 3
+    policy: mypolicy
+    services:
+      - name: serv1
+        target: '10.71.206.2'
+        policy: mypolicy
+      - name: serv2
+        target: '10.71.206.75'
+        delay: 3
+```
+
+**`name`** - Unique name of service group
+
+**`device`** - Device for all sub services
+
+**`delay`** (seconds) - Delay for all sub services
+
+**`policy`** - Policy for all sub services
+
+**`services`** - List of sub services. `delay` and `policy` can be overwritten

docs/how_it_works.md

@@ -0,0 +1,22 @@
+# How it works
+
+![Schema](img/simplesla.svg)
+
+SimpleSLA can handle ICMP checks and provide them to Prometheus with HTTP exporter. There are two ways to collect metrics: 
+* Local device
+* Remote device
+
+## Local device
+SimpleSLA creates local device by default and without any need to define it through config file. Local device has default name **`simplesla-local`** and that\`s the ability to ping with ICMP packets right from the server or local PC with deployed SimpleSLA
+
+Configuration of `simplesla-local` are described [here](configuration/index.md#local)
+
+## Remote device
+SimpleSLA can connect to other devices and collect RTT to some destinations, that cannot be reachable right from SimpleSLA.
+
+These some steps of check algorithm:
+1. Connect to device
+2. Send `ping` command in appropriate format
+3. Recieve raw output
+4. Parse raw output to some value
+5. Push the value as a metric in `Metric collector`