Merge ~gabrielcocenza/juju-lint:subordinate-docs into juju-lint:master

[Gabriel Cocenza]

Update documentation

Co-authored-by: Arif Ali <email address hidden>

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

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

Unmerged commits

305a860... by Gabriel Cocenza on 2022-05-31

Update documentation

Co-authored-by: Arif Ali <email address hidden>

8419d92... by Gabriel Cocenza on 2022-05-18

check if subordinate units are related with other apps in the bundle.

- added new rules (check-relations and enforce-juju-info) into the
  subordinate rules file.
- added nrpe in the conftest to test subordinate relation rules.
- added description for tests that were missing and failing lint.

diff --git a/README.md b/README.md
index a99f87c..8a0ba50 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,11 @@
-= Juju Lint =
+# Juju Lint
 
-== Introduction ==
+## Install
+```shell
+sudo snap install juju-lint --classic
+```
+
+## Introduction
 
 This is intended to be run against a yaml or json dump of Juju status, a YAML
 dump of a juju bundle, or a remote cloud or clouds via SSH.
@@ -39,7 +44,7 @@ To use a different rules file:
 
 For all other options, consult `juju-lint --help`
 
-== Example ==
+## Example
 
 A typical use case is linting an openstack cloud:
 
@@ -49,56 +54,32 @@ A typical use case is linting an openstack cloud:
         -t openstack juju-status.json
     juju-lint -c /snap/juju-lint/current/contrib/openstack-focal-ovn.yaml \
         -t openstack bundle.yaml
-
-== Rules File ==
+## Rules File
 
 For an example of a rules file, see `example-lint-rules.yaml`.
 
 Supported top-level options for your rules file:
 
- 1. `subordinates` - required subordinates.
+ 1. [subordinates](docs/subordinates.md) - required subordinates.
  2. `known charms` - all primary charms should be in this list.
  3. `operations [mandatory|optional|subordinate]`
  4. `openstack [mandatory|optional|subordinate]`
  5. `config` - application configuration auditing
  6. `[openstack|kubernetes] config` - config auditing for specific cloud types.
- 7. `space checks` - enforce/ignore checks for relation binding space
+ 7. [space checks](docs/space-checks.md) - enforce/ignore checks for relation binding space
     mismatches.
  8. `!include <relative path>` - Extension to yaml to include files.
 
-=== Space checks ===
-
-All relations defined within a bundle, except for cross-model relationships,
-will be checked for mismatches of their space bindings.
-
-By default, mismatches are logged as warnings as they are not necessarily
-critical problems.  If applications can route to each other despite the
-mismatch, there may be no real issue here, and it may be appropriate to ignore
-certain issues.  On the other hand, these mismatches may cause problems ranging
-from impaired throughput due to using suboptimal interfaces to breakages due to
-not being able to route between the related units.
-
-The following options are available to either log such mismatches as errors or
-to ignore them entirely:
-
- 1. `enforce endpoints` - A list of <charm>:<endpoint> strings.  If a mismatch
-    matches one of these endpoints, it will be flagged as an error.
- 2. `enforce relations` - A list of two-item <charm>:<endpoint> string lists,
-    representing the two linked endpoints of a relation.  If a mismatch
-    matches one of these relations, it will be flagged as an error.
- 1. `ignore endpoints` - A list of <charm>:<endpoint> strings.  If a mismatch
-    matches one of these endpoints, it will be ignored.
- 1. `ignore relations` - A list of two-item <charm>:<endpoint> string lists,
-    representing the two linked endpoints of a relation.  If a mismatch
-    matches one of these relations, it will be ignored.
+There are some rules files that are ready to be used and they can be found at:
 
-In the case of a mismatch matching both enforce and ignore rules, the enforce
-rule will "win" and it will be flagged as an error.
+```
+/snap/juju-lint/current/contrib/
+```
 
-Note that all the above checks use charm names rather than application names
-in their endpoint strings.
+## Documentation
+Documentation is available at the [docs](docs) folder.
 
-== License ==
+## License
 
 Copyright 2020 Canonical Limited.
 License granted by Canonical Limited.
diff --git a/docs/space-checks.md b/docs/space-checks.md
 new file mode 100644
index 0000000..3afdc92
--- /dev/null
+++ b/docs/space-checks.md
@@ -0,0 +1,31 @@
+# Space checks
+
+All relations defined within a bundle, except for cross-model relationships,
+will be checked for mismatches of their space bindings.
+
+By default, mismatches are logged as warnings as they are not necessarily
+critical problems.  If applications can route to each other despite the
+mismatch, there may be no real issue here, and it may be appropriate to ignore
+certain issues.  On the other hand, these mismatches may cause problems ranging
+from impaired throughput due to using suboptimal interfaces to breakages due to
+not being able to route between the related units.
+
+The following options are available to either log such mismatches as errors or
+to ignore them entirely:
+
+ 1. `enforce endpoints` - A list of <charm>:<endpoint> strings.  If a mismatch
+    matches one of these endpoints, it will be flagged as an error.
+ 2. `enforce relations` - A list of two-item <charm>:<endpoint> string lists,
+    representing the two linked endpoints of a relation.  If a mismatch
+    matches one of these relations, it will be flagged as an error.
+ 1. `ignore endpoints` - A list of <charm>:<endpoint> strings.  If a mismatch
+    matches one of these endpoints, it will be ignored.
+ 1. `ignore relations` - A list of two-item <charm>:<endpoint> string lists,
+    representing the two linked endpoints of a relation.  If a mismatch
+    matches one of these relations, it will be ignored.
+
+In the case of a mismatch matching both enforce and ignore rules, the enforce
+rule will "win" and it will be flagged as an error.
+
+Note that all the above checks use charm names rather than application names
+in their endpoint strings.
 \ No newline at end of file
diff --git a/docs/subordinates.md b/docs/subordinates.md
 new file mode 100644
index 0000000..1f0aa4a
--- /dev/null
+++ b/docs/subordinates.md
@@ -0,0 +1,163 @@
+# 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]
+  check-relations: [
+    ["*:nrpe-external-master", "nrpe:nrpe-external-master"],
+    ["nagios:monitors", "nrpe:monitors"],
+  ]
+  enforce-juju-info : true
+ ntp:
+  where: host only
+ thruk-agent:
+  where: on nagios
+ hw-health:
+  where: metal only
+ local-users:
+  where: all or nothing
+```
+
+## where
+
+In the `where` option we specify generally where to find the subordinates.
+
+In the above example we have 9 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.
+
+### metal only
+We have one subordinate charm, that is using this option, namely `hw-health` as shown below
+
+```yaml
+hw-health:
+ where: metal only
+```
+
+In this instance the option will check that the `hw-health` charm is available on all the machines that are running on bare-metal.
+
+This is useful in this scenario, as running `hw-health` on a container or on a vm does not make sense because the charm only work for
+bare-metal installations on specific hardware.
+
+
+### 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]
+  check-relations: [
+    ["*:nrpe-external-master", "nrpe:nrpe-external-master"],
+    ["nagios:monitors", "nrpe:monitors"],
+  ]
+  enforce-juju-info : true
+```
+
+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
+
+Another 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
+
+We have one subordinate charm in our example that is using this option, namely `local-users` as shown below:
+
+```yaml
+local-users:
+ where: all or nothing
+```
+
+This option will check whether if all the applications will have this particular subordinate or none will have it.
+
+## check-relations and enforce-juju-info
+
+Those options are used to check if subordinate units are related with other applications in the bundle. 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]
+  check-relations: [
+    ["*:nrpe-external-master", "nrpe:nrpe-external-master"],
+    ["nagios:monitors", "nrpe:monitors"],
+  ]
+  enforce-juju-info : true
+```
+
+`check-relations` should be passed as a List of Lists. Each element should have this pattern:
+
+```
+[<CHARM>:<INTERFACE>, <SUBORDINATE_CHARM>:<SUBORDINATE_INTERFACE>]
+```
+
+If you want to add a rule that is the same for several charms, you can use `*` instead of making an exhaustive list.
+
+In the example above, the first element is using `*` meaning that it will check for `nrpe-external-master` endpoint on all applications in the bundle. If this endpoint exists in the charm, it will check if it's related to the subordinate.
+
+The second element in the example will check if the app `nagios` is related with `nrpe` using the `monitors` interface.
+
+Nrpe should relate preferably using the `nrpe-external-master` interface in this example, but in some cases that is not possible (e.g: ubuntu with nrpe). If you want to guarantee that a relation is happening you can set `enforce-juju-info` to `true`. This will check if the app is related using the less specific interface `juju-info`.
+
+If `enforce-juju-info` is set to `false` the only relations that will be checked are the ones inside `check-relations`.
+
+**Note:** In case that a charm has a more specific endpoint to relate with the subordinate and it's using `juju-info` an alert will happen.