Merge ~arif-ali/juju-lint/+git/juju-lint:doc_updates into juju-lint:master

[Arif Ali]

Add more documentation

[🤖 Canonical IS Merge Bot (canonical-is-mergebot)]

This merge proposal is being monitored by mergebot. Change the status to Approved to merge.

[🤖 prod-jenkaas-bootstack (prod-jenkaas-bootstack)]

FAILED: Continuous integration, rev:524b8f859a8e1e523263697a22875da352e36320
https://jenkins.canonical.com/bootstack/job/lp-juju-lint-ci/3/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/bootstack/job/lp-charm-test-unit/304/
    None: https://jenkins.canonical.com/bootstack/job/lp-update-mp/1462/

Click here to trigger a rebuild:
https://jenkins.canonical.com/bootstack/job/lp-juju-lint-ci/3//rebuild

review: Needs Fixing (continuous-integration)

[🤖 prod-jenkaas-bootstack (prod-jenkaas-bootstack)]

FAILED: Continuous integration, rev:524b8f859a8e1e523263697a22875da352e36320
https://jenkins.canonical.com/bootstack/job/lp-juju-lint-ci/4/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/bootstack/job/lp-charm-test-functest/1049/
    None: https://jenkins.canonical.com/bootstack/job/lp-update-mp/1463/

Click here to trigger a rebuild:
https://jenkins.canonical.com/bootstack/job/lp-juju-lint-ci/4//rebuild

review: Needs Fixing (continuous-integration)

Unmerged commits

524b8f8... by Arif Ali on 2020-05-14

Add more documentation

diff --git a/README.md b/README.md
index 534395d..f65bca8 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,8 @@
-= Juju Lint =
+# Juju Lint
 
 /!\ This is alpha software and backwards incompatible changes are expected.
 
-== Introduction ==
+## Introduction
 
 This is intended to be run against a yaml dump of Juju status, which can be
 generated as follows:
@@ -17,7 +17,7 @@ To use a different rules file:
 
     ./juju-lint -c my-rules.yaml status.yaml
 
-== Rules File ==
+## Rules File
 
 For an example of a rules file, see `example-lint-rules.yaml`.
 
@@ -28,7 +28,11 @@ Supported top-level options for your rules file:
  3. `operations [mandatory|optional|subordinate]`
  4. `openstack [mandatory|optional|subordinate]`
 
-== License ==
+## Documentation
+
+Documentation is available [here](docs/index)
+
+## License
 
 Copyright 2018 Canonical Limited.
 License granted by Canonical Limited.
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..dfae29f
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,46 @@
+# Juju Lint
+
+**This is alpha software and backwards incompatible changes are expected.**
+
+## Introduction
+
+This is intended to be run against a yaml dump of Juju status, which can be
+generated as follows:
+
+    juju status --format yaml > status.yaml
+
+Then run `juju-lint` (using a rules file of `lint-rules.yaml`):
+
+    ./juju-lint status.yaml
+
+To use a different rules file:
+
+    ./juju-lint -c my-rules.yaml status.yaml
+
+## Rules File
+
+For an example of a rules file, see `example-lint-rules.yaml`.
+
+Supported top-level options for your rules file:
+
+ 1. [subordinates](subordinates) - required subordinates.
+ 2. [known charms](known_charms) - all primary charms should be in this list.
+ 3. [operations](operations) `[mandatory|optional|subordinate]`
+ 4. [openstack](openstack) `[mandatory|optional|subordinate]`
+
+## License
+
+Copyright 2018 Canonical Limited.
+License granted by Canonical Limited.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License version 3, as
+published by the Free Software Foundation.
+
+This program is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranties of
+MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR
+PURPOSE.  See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <http://www.gnu.org/licenses/>.
diff --git a/docs/known_charms.md b/docs/known_charms.md
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/docs/known_charms.md
diff --git a/docs/openstack.md b/docs/openstack.md
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/docs/openstack.md
diff --git a/docs/operations.md b/docs/operations.md
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/docs/operations.md
diff --git a/docs/subordinates.md b/docs/subordinates.md
new file mode 100644
index 0000000..55a9a82
--- /dev/null
+++ b/docs/subordinates.md
@@ -0,0 +1,91 @@
+# Subordinates
+
+The purpose of the subordinates section is to check which subordinates are available on  each of the deployed applications.
+
+Below is an example of what the subordinates attribute can look like
+
+```yaml
+subordinates:
+ telegraf:
+  where: all except prometheus
+ landscape-client:
+  where: all except landscape-server
+ filebeat:
+  where: all except graylog
+ canonical-livepatch:
+  where: host only
+ nrpe:
+  where: container aware
+  host-suffixes: [host, physical, guest]
+  container-suffixes: [lxd, container]
+  exceptions: [nagios]
+ ntp:
+  where: host only
+ thruk-agent:
+  where: on nagios
+```
+
+In the `where` option we specify generally where to find the subordinates.
+
+In the above example we have 7 subordinates that we are looking at. Below we'll go through each of them, and explain all the options
+
+## all except \<app\>
+
+3 applications have tha same option, i.e. `telegraf`, `landscape-client` and `filebeat`, and these use the `where: all except ...` option. Below is the one from `telegraf`
+
+```yaml
+telegraf:
+ where: all except prometheus
+```
+
+This option is suggesting that we should find the `telagraf` subordinate charm under all the applications except for the `prometheus` applications
+
+## host only
+
+We have one subordinate charm, that is using this option, namely `ntp` as shown below
+
+```yaml
+ntp:
+ where: host only
+```
+
+In this instance the option will check that the `ntp` charm is available on all the hosts that are not containers.
+
+This is useful in this scenario, as running `ntp` on a container does not make sense, as the time for a container is directly taken from the underlying hypervisor. Also in this scenario, the ntp charm will not be able to change the time so wouldn't make sense.
+
+## on \<app\>
+
+We have one subordinate charm, that is using this option, namely `thruk-agent` as shown below
+
+```yaml
+thruk-agent:
+ where: on nagios
+```
+
+This option checks that this particular subordinate charm is on a specific application. So in this scenario, the tool will chck that the `thruk-agent` is only on the `nagios` application
+
+## container aware
+
+We have one subordinate charm in our example that is using this option, namely `nrpe` as shown below
+
+```yaml
+ nrpe:
+  where: container aware
+  host-suffixes: [host, physical, guest]
+  container-suffixes: [lxd, container]
+  exceptions: [nagios]
+```
+
+As can be seen, this specific option has many other variables that we need to look at. The purpose of this option is to check the name of the subordinate charm that is linked, and that `nrpe` is in the name of the subordinate
+
+The `host-suffixes` and `container-suffixes` options are designed to look for the name of the subordinate with the relevant fixes, whether is a physical server, vm or a container. `host-suffixes` currently caters for physical and kvms, and `container-suffixes` for lxc containers. If however if neither of these options are found then the longer option of searching through is used, so could take longer
+
+The final option is `exceptions`, this is where the relevant subordinate will not be present. In the above scenario, we don't run nrpe on the nagios server, as that has the capability of monitoring itself and therefore is not required
+
+## all
+
+This option will suggest that all the applications will have this particular subordinate
+
+## all or nothing
+
+**TODO** not sure what this does