Document ugly things

1 files changed, 24 insertions, 2 deletions

diff --git a/personal_infra/pseudo_resource_exporter.py b/personal_infra/pseudo_resource_exporter.py
index 0753a0d7..793f2b77 100755
--- a/personal_infra/pseudo_resource_exporter.py
+++ b/personal_infra/pseudo_resource_exporter.py
@@ -1,17 +1,37 @@
 #!/usr/bin/env python3
-
 import json
 import pathlib
 
 
+"""
+This is an ugly hack.
+
+Puppet exported resources are very nice to generate monitoring configuration
+along with your Puppet resources. As you define something like an Apache
+virtual host, you can create a Nagios service check for it.
+
+But this requires a PuppetDB, and does not play nice with having no central
+Puppet infra.
+
+With its sibling script up.py, this script takes the JSON files generated by
+that, and manipulates them. This script moves Nagios resources to a specific
+host and does ugly trickery to fool Puppet into accepting that.
+
+This is like exported resources, but you don't need to declare a resource as
+exported.
+"""
+
+
 def load_json(path):
     with open(path) as f:
         return json.load(f)
 
+
 def save_json(r, path):
     with open(path, "w") as f:
         json.dump(r, f)
 
+
 nagios_catalog_file = pathlib.Path("build/puppet/build/output/nagios.h1.int.pdp7.net/catalog.json")
 
 if nagios_catalog_file.exists():
@@ -32,6 +52,7 @@ if nagios_catalog_file.exists():
 nagios_resources = []
 nagios_edge_targets = []
 
+
 def is_nagios_resource(r):
     return r["type"].startswith("Nagios")
 
@@ -39,6 +60,7 @@ def is_nagios_resource(r):
 def is_nagios_edge(e):
     return e["target"].startswith("Nagios")
 
+
 for catalog_file in catalog_files:
     if catalog_file == nagios_catalog_file:
         continue
@@ -48,7 +70,7 @@ for catalog_file in catalog_files:
     nagios_edge_targets += [e["target"] for e in catalog["edges"] if is_nagios_edge(e)]
     catalog["edges"] = [e for e in catalog["edges"] if not is_nagios_edge(e)]
     save_json(catalog, catalog_file)
-    
+
 
 if nagios_catalog_file.exists():
     nagios_contact_position = nagios_catalog["resources"].index(nagios_contact)