Document how to create new checks

2 files changed, 36 insertions, 0 deletions

diff --git a/roles/openshift_health_checker/HOWTO_CHECKS.md b/roles/openshift_health_checker/HOWTO_CHECKS.md
new file mode 100644
index 000000000..1573c14da
--- /dev/null
+++ b/roles/openshift_health_checker/HOWTO_CHECKS.md
@@ -0,0 +1,34 @@
+# OpenShift health checks
+
+This Ansible role contains health checks to diagnose problems in OpenShift
+environments.
+
+Checks are typically implemented as two parts:
+
+1. a Python module in [openshift_checks/](openshift_checks), with a class that
+   inherits from `OpenShiftCheck`.
+2. a custom Ansible module in [library/](library), for cases when the modules
+   shipped with Ansible do not provide the required functionality.
+
+The checks are called from an Ansible playbooks via the `openshift_health_check`
+action plugin. See
+[playbooks/byo/openshift-preflight/check.yml](../../playbooks/byo/openshift-preflight/check.yml)
+for an example.
+
+The action plugin dynamically discovers all checks and executes only those
+selected in the play.
+
+Checks can determine when they are active by implementing the method
+`is_active`. Inactive checks are skipped. This is similar to the `when`
+instruction in Ansible plays.
+
+Checks may have tags, which are a way to group related checks together. For
+instance, to run all preflight checks, pass in the group `'@preflight'` to
+`openshift_health_check`.
+
+Groups are automatically computed from tags.
+
+Groups and individual check names can be used together in the argument list to
+`openshift_health_check`.
+
+Look at existing checks for the implementation details.
diff --git a/roles/openshift_health_checker/README.md b/roles/openshift_health_checker/README.md
index 745e45b50..4ab5f1f7b 100644
--- a/roles/openshift_health_checker/README.md
+++ b/roles/openshift_health_checker/README.md
@@ -4,6 +4,8 @@ OpenShift Health Checker
 This role detects common problems with OpenShift installations or with
 environments prior to install.
 
+For more information about creating new checks, see [HOWTO_CHECKS.md](HOWTO_CHECKS.md).
+
 Requirements
 ------------