Merge pull request #7 from trento-project/add-docs-back

Add docs back

docs/ci-cd-variables.md

@@ -0,0 +1,14 @@
+## CI/CD Variables expected by Trento GH Action Runner
+
+These are a list of the variables that our GitHub Workflow supports in order
+to make a `trento` deployment.
+
+### Secrets
+
+#### `OBS_USER`
+This the OBS user that will trigger build in `opensuse.build.org`
+`obsuser`
+
+#### `OBS_PASS`
+This is the password for the OBS user that will trigger build in `opensuse.build.org`
+`obspassword`

docs/development/health-aggregation-matrix.md

@@ -0,0 +1,21 @@
+# Node health status aggregation matrix
+
+The following table explains how we determine the aggregated, color-coded, health status of hosts.
+
+| Heartbeat | Config Checks                | Aggregate Result
+|-----------|------------------------------|------------------
+| Ack       | Ran and passed               | Green
+| Timeout   | \                            | Red
+| Ack       | Ran and passed with warnings | Yellow
+| Ack       | Ran and didn't pass          | Red
+| Ack       | Didn't run at all            | Gray *
+| Ack       | Failed to run                | Yellow *
+
+Color codes legend:
+
+- Red: Critical situation, user should immediately act
+- Yellow: User be aware and know what they're doing
+- Green: User can go to sleep fine and dandy
+- Gray: Not enough information is available
+
+> *: maybe allow user to pick the severity level for such case

docs/development/how-to-make-a-release.md

@@ -0,0 +1,63 @@
+# How to release a new version of Trento
+
+> Note: this document is a draft!
+
+## Pre-requisites
+
+Install [github-changelog-generator](https://github.com/github-changelog-generator/github-changelog-generator) globally in your dev box:
+```
+gem install github_changelog_generator
+```
+
+## Update the changelog and create a new tag
+
+The automatic changelog generation leverages GitHub labels very heavily to produce a meaningful output following the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) specification, grouping pull requests and issues in sections.
+
+Use the labels as follows:
+- `enhancement` or `addition` items go in the `Added` section;
+- `bug` or `fix` items go in the `Fixed` section;
+- `removal` items go in the `Removed` section;
+- unlabelled pull requests go in the `Other Changes` section;
+- unlabelled closed issues are ignored.
+
+You don't have to label everything: the intent of the changelog is to communicate highlights to end-users, while also being comprehensive; this is why the `Other changes` section catches all the unlabelled items and is rendered last.
+
+Once you do a quick round of issues/PR triaging to apply labels in a meaningful way, follow these steps:
+
+```bash
+# always create a dedicated release branch
+git switch -c release-x.y.z
+
+# x1.y1.z1 is the previous release tag
+github_changelog_generator --since-tag=x1.y1.z1 --future-release=x.y.z
+
+git add CHANGELOG.md
+git commit -m "add x.y.z changelog entry"
+
+# maybe make some other last minute changes
+# [...]
+
+# merge and tag, making sure the tag is on the merge commit
+git switch main
+git merge --no-ff release-x.y.z
+git tag x.y.z
+
+# don't forget to force update the rolling tag!
+git fetch --tags -f
+
+# push directly
+git push --tags origin main
+```
+
+Optionally, open a pull request from the release branch instead of tagging and pushing manually.
+
+## GitHub release
+
+> Note: this step will soon be automated.
+
+Go to the [project releases page](https://github.com/trento-project/trento/releases) and create a new release, then:
+
+- use the just created git tag as the release tag and title;
+- copy-paste the last changelog entry from `CHANGELOG.md` as the release body;
+- hit the green button;
+- profit!

docs/scope.md

@@ -0,0 +1,99 @@
+# Table of contents
+- [About this document](#about-this-document)
+- [Goal](#goal)
+- [Scope](#scope)
+  - [Hosts](#hosts)
+    - [Discovery](#discovery)
+    - [Checks](#checks)
+      - [HA Checker: Scenario SAP HANA Performance Optimized on Azure](#ha-checker-scenario-sap-hana-performance-optimized-on-azure)
+      - [HA Checker: Scenario Pacemaker on Azure](#ha-checker-scenario-pacemaker-on-azure)
+      - [More coming](#more-coming)
+  - [Pacemaker Clusters](#pacemaker-clusters)
+  - [SAP Systems](#sap-systems)
+  - [Agents](#agents)
+
+# About this document
+This document aims to provide information about the current features that `trento`
+tries to cover and its main scope. Further, additional details are provided on
+the functionality of each view.
+
+# Goal
+>Provide simple to use front end for all relevant OS related tasks for SAP
+>workloads
+
+This means that `trento` focuses on the OS-related tasks without stepping into
+specific functionality that is already covered by the relevant application layer,
+centered around SAP workloads and simplicity.
+
+# Scope
+The scope of each component of `trento` is as follows:
+
+## Hosts
+In the hosts overview, the user can get a list of all the hosts that are running
+the trento agent. For each host it will be possible to check basic information
+such as the hostname, its IP address, to what cluster it belongs and a list of
+all the tags that have been set by the discovery mechanisms to classify each
+host accordingly.
+
+When accessing the details of each host, it will be possible to access in-depth
+information about the role each host has in the cluster such as the status of the
+core HDB processes, SAP System ID (SID), etc. Here, the SAP administrator can
+get a list of potential problems and improvements on the configuration of the
+host that the discovery mechanisms have found.
+
+### Discovery
+The discovery mechanisms are the base of the checkers. These implement the code
+in the trento agent to gather information about the nodes, their roles, the
+configuration files that each node uses (depending on their role).
+
+
+### Checks
+Under the checks view it's possible to see a representation on the data collected
+by the agents against predefined values that are provided by our own recommendations
+and our partners such as SAP. The base for the checks are the above described
+[Discovery mechanisms](#discovery)
+
+There are currently 2 checkers supported:
+
+#### HA Checker: Scenario SAP HANA Performance Optimized on Azure
+This checker uses Azure's recommendations to provide an overview of how well
+the deployed SAP HANA cluster meets their indicators. More details about this
+recommendation can be seen [here](https://docs.microsoft.com/en-us/azure/virtual-machines/workloads/sap/high-availability-guide-suse-pacemaker)
+
+#### HA Checker: Scenario Pacemaker on Azure
+This check is also comparing against Azure's recommendations for a Pacemaker
+cluster.
+
+#### More coming
+Additional checkers are being implemented for other cloud providers.
+
+## Pacemaker Clusters
+This view currently allows to check the status of the all the discovered pacemaker clusters,
+including the information of the status of each node and the role associated to
+each node. This view also allows to see the resources, their type and distribution
+within the cluster nodes.
+
+## SAP Systems
+In this view are listed the SAP Systems, usually identified by a SID or
+`SAP System Idenfication` string such as `PRD`, `DEV`, or `QAS`. These are used
+often to identify productive, development and quality assurance systems.
+In this view we get an overview of the distribution of each SID, the number of
+hosts disvered of each of them and additional details.
+
+## Agents
+Though not specifically a view/section, as it is the core component of `trento`,
+it is important to understand what they are.
+
+The agents are the `trento` processes that run in each of the nodes that conform
+a highly available SAP Applications cluster. On each of these, the agents attempt
+to discover the role of the node and run a set of checks which result in the
+recommendations described above in the [Checkers](#checkers).
+The information that is gathered by them is stored through a distributed KV store
+and is made visible on the `trento` web UI through the `trento` web UI component.
+
+The agents implement the core functionality of trento. They are responsible for
+the discovery of all the clustered components that are required in order to run
+highly available SAP Applications. These agents implement discovery for:
+  - Pacemaker
+  - Corosync (soon)
+  - SAP components

docs/trento-architecture.md

@@ -0,0 +1,41 @@
+# Trento Example Deployment Layout
+
+![Trento Architecture](trento-architecture.png)
+
+## Trento Agent
+
+The Trento Agent is to be set up on every node that should be handled by Trento.
+
+The Trento Agent will run several periodic job loops. 
+
+### Discovery Loop
+
+The Discovery loop is happening at a very low frequency and priority and is capturing record-worthy
+Data. At the current implementation, only selected datapoints are regularly updated. 
+There is no conflict-resolution being implemented, the data is unconditionally overwritten.
+
+## Checker Loop
+
+TBD
+
+
+# Nomenclature
+
+Whenever the Trento user is exposed to concepts, the following naming should
+be used consistently in the user visible dialogs, messages and templates. For
+code internal usages the `SAP` prefix should be omitted.
+
+## SAP Host
+
+This is a physical or a virtual server ("node") running a Linux Operating System on which SAP system components are installed and running on (potentially supervised
+by cluster management software like for example pacemaker).
+
+## SAP System
+
+This uses a very traditional multi-tier client server setup:
+
+* Presentation Layer: Web Browser, Dedicated GUI or 3rd Party Application between End-User and Application Servers. Out of control for Trento.
+
+* Application Server Layer: Business applications which the end users interact with (can be written in ABAP programming language, for example)
+
+* Database Server Layer: Contains the customer data and all the ABAP code which is run by the application servers. Most often this is SAP HANA.

packaging/suse/trento-agent.spec

@@ -16,7 +16,7 @@
 #
 
 
-Name:           trento
+Name:           trento-agent
 # Version will be processed via set_version source service
 Version:        0
 Release:        0