Add example scheduled certificate check

Additional certificate expiration check playbooks:
  - one that that uploads the generated reports to a location in the masters
  - one that uses custom report paths with timestamps

OpenShift Job and ScheduledJob examples that use these playbooks
run from a container to check cluster certificates from within
the cluster itself.

5 files changed, 305 insertions, 0 deletions

diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 000000000..0e412244d
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,93 @@
+# openshift-ansible usage examples
+
+The primary use of `openshift-ansible` is to install, configure and upgrade OpenShift clusters.
+
+This is typically done by direct invocation of Ansible tools like `ansible-playbook`. This use case is covered in detail in the [OpenShift advanced installation documentation](https://docs.openshift.org/latest/install_config/install/advanced_install.html)
+
+For OpenShift Container Platform there's also an installation utility that wraps `openshift-ansible`. This usage case is covered in the [Quick Installation](https://docs.openshift.com/container-platform/latest/install_config/install/quick_install.html) section of the documentation.
+
+The usage examples below cover use cases other than install/configure/upgrade.
+
+## Container image
+
+The examples below run [openshift-ansible in a container](../README_CONTAINER_IMAGE.md) to perform certificate expiration checks on an OpenShift cluster from pods running on the cluster itself.
+
+You can find more details about the certificate expiration check roles and example playbooks in [the openshift_certificate_expiry role's README](../roles/openshift_certificate_expiry/README.md).
+
+### Job to upload certificate expiration reports
+
+The example `Job` in [certificate-check-upload.yaml](certificate-check-upload.yaml) executes a [Job](https://docs.openshift.org/latest/dev_guide/jobs.html) that checks the expiration dates of the internal certificates of the cluster and uploads HTML and JSON reports to `/etc/origin/certificate_expiration_report` in the masters.
+
+This example uses the [`easy-mode-upload.yaml`](../playbooks/certificate_expiry/easy-mode-upload.yaml) example playbook, which generates reports and uploads them to the masters. The playbook can be customized via environment variables to control the length of the warning period (`CERT_EXPIRY_WARN_DAYS`) and the location in the masters where the reports are uploaded (`COPY_TO_PATH`).
+
+The job expects the inventory to be provided via the *hosts* key of a [ConfigMap](https://docs.openshift.org/latest/dev_guide/configmaps.html) named *inventory*, and the passwordless ssh key that allows connecting to the hosts to be availalbe as *ssh-privatekey* from a [Secret](https://docs.openshift.org/latest/dev_guide/secrets.html) named *sshkey*, so these are created first:
+
+    oc new-project certcheck
+    oc create configmap inventory --from-file=hosts=/etc/ansible/hosts
+    oc secrets new-sshauth sshkey --ssh-privatekey=$HOME/.ssh/id_rsa
+
+Note that `inventory`, `hosts`, `sshkey` and `ssh-privatekey` are referenced by name from the provided example Job definition. If you use different names for the objects/attributes you will have to adjust the Job accordingly.
+
+To create the Job:
+
+    oc create -f examples/certificate-check-upload.yaml
+
+### Scheduled job for certificate expiration report upload
+
+**Note**: This example uses the [ScheduledJob](https://docs.openshift.com/container-platform/3.4/dev_guide/scheduled_jobs.html) object, which has been renamed to [CronJob](https://docs.openshift.org/latest/dev_guide/cron_jobs.html) upstream and is still a Technology Preview subject to further change.
+
+The example `ScheduledJob` in [scheduled-certcheck-upload.yaml](scheduled-certcheck-upload.yaml) does the same as the `Job` example above, but it is scheduled to automatically run every first day of the month (see the `spec.schedule` value in the example).
+
+The job definition is the same and it expects the same configuration: we provide the inventory and ssh key via a ConfigMap and a Secret respectively:
+
+    oc new-project certcheck
+    oc create configmap inventory --from-file=hosts=/etc/ansible/hosts
+    oc secrets new-sshauth sshkey --ssh-privatekey=$HOME/.ssh/id_rsa
+
+And then we create the ScheduledJob:
+
+    oc create -f examples/scheduled-certcheck-upload.yaml
+
+### Job and ScheduledJob to check certificates using volumes
+
+There are two additional examples:
+
+ - A `Job` [certificate-check-volume.yaml](certificate-check-volume.yaml)
+ - A `ScheduledJob` [scheduled-certcheck-upload.yaml](scheduled-certcheck-upload.yaml)
+
+These perform the same work as the two examples above, but instead of uploading the generated reports to the masters they store them in a custom path within the container that is expected to be backed by a [PersistentVolumeClaim](https://docs.openshift.org/latest/dev_guide/persistent_volumes.html), so that the reports are actually written to storage external to the container.
+
+These examples assume that there is an existing `PersistentVolumeClaim` called `certcheck-reports` and they use the  [`html_and_json_timestamp.yaml`](../playbooks/certificate_expiry/html_and_json_timestamp.yaml) example playbook to write timestamped reports into it.
+
+You can later access the reports from another pod that mounts the same volume, or externally via direct access to the backend storage behind the matching `PersistentVolume`.
+
+To run these examples we prepare the inventory and ssh keys as in the other examples:
+
+    oc new-project certcheck
+    oc create configmap inventory --from-file=hosts=/etc/ansible/hosts
+    oc secrets new-sshauth sshkey --ssh-privatekey=$HOME/.ssh/id_rsa
+
+Additionally we allocate a `PersistentVolumeClaim` to store the reports:
+
+	oc create -f - <<PVC
+	---
+	apiVersion: v1
+	kind: PersistentVolumeClaim
+	metadata:
+	  name: certcheck-reports
+	spec:
+	  accessModes:
+		- ReadWriteOnce
+	  resources:
+		requests:
+		  storage: 1Gi
+	PVC
+
+With that we can run the `Job` once:
+
+    oc create -f examples/certificate-check-volume.yaml
+
+or schedule it to run periodically as a `ScheduledJob`:
+
+    oc create -f examples/scheduled-certcheck-volume.yaml
+
diff --git a/examples/certificate-check-upload.yaml b/examples/certificate-check-upload.yaml
new file mode 100644
index 000000000..b10a0b614
--- /dev/null
+++ b/examples/certificate-check-upload.yaml
@@ -0,0 +1,47 @@
+# An example Job to run a certificate check of OpenShift's internal
+# certificate status from within OpenShift.
+#
+# The generated reports are uploaded to a location in the master
+# hosts, using the playbook 'easy-mode-upload.yaml'.
+#
+# This example uses the openshift/openshift-ansible container image.
+# (see README_CONTAINER_IMAGE.md in the top level dir for more details).
+#
+# The following objects are xpected to be configured before the creation
+# of this Job:
+#   - A ConfigMap named 'inventory' with a key named 'hosts' that
+#     contains the the Ansible inventory file
+#   - A Secret named 'sshkey' with a key named 'ssh-privatekey
+#     that contains the ssh key to connect to the hosts
+# (see examples/README.md for more details)
+---
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: certificate-check
+spec:
+  containers:
+  - name: openshift-ansible
+    image: openshift/openshift-ansible
+    env:
+    - name: PLAYBOOK_FILE
+      value: playbooks/certificate_expiry/easy-mode-upload.yaml
+    - name: INVENTORY_FILE
+      value: /tmp/inventory/hosts       # from configmap vol below
+    - name: ANSIBLE_PRIVATE_KEY_FILE    # from secret vol below
+      value: /opt/app-root/src/.ssh/id_rsa/ssh-privatekey
+    - name: CERT_EXPIRY_WARN_DAYS
+      value: "45"      # must be a string, don't forget the quotes
+    volumeMounts:
+    - name: sshkey
+      mountPath: /opt/app-root/src/.ssh/id_rsa
+    - name: inventory
+      mountPath: /tmp/inventory
+  volumes:
+  - name: sshkey
+    secret:
+      secretName: sshkey
+  - name: inventory
+    configMap:
+      name: inventory
+  restartPolicy: Never
diff --git a/examples/certificate-check-volume.yaml b/examples/certificate-check-volume.yaml
new file mode 100644
index 000000000..c19dc1f88
--- /dev/null
+++ b/examples/certificate-check-volume.yaml
@@ -0,0 +1,54 @@
+# An example Job to run a certificate check of OpenShift's internal
+# certificate status from within OpenShift.
+#
+# The generated reports are stored in a Persistent Volume using
+# the playbook 'html_and_json_timestamp.yaml'.
+#
+# This example uses the openshift/openshift-ansible container image.
+# (see README_CONTAINER_IMAGE.md in the top level dir for more details).
+#
+# The following objects are xpected to be configured before the creation
+# of this Job:
+#   - A ConfigMap named 'inventory' with a key named 'hosts' that
+#     contains the the Ansible inventory file
+#   - A Secret named 'sshkey' with a key named 'ssh-privatekey
+#     that contains the ssh key to connect to the hosts
+#   - A PersistentVolumeClaim named 'certcheck-reports' where the
+#     generated reports are going to be stored
+# (see examples/README.md for more details)
+---
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: certificate-check
+spec:
+  containers:
+  - name: openshift-ansible
+    image: openshift/openshift-ansible
+    env:
+    - name: PLAYBOOK_FILE
+      value: playbooks/certificate_expiry/html_and_json_timestamp.yaml
+    - name: INVENTORY_FILE
+      value: /tmp/inventory/hosts       # from configmap vol below
+    - name: ANSIBLE_PRIVATE_KEY_FILE    # from secret vol below
+      value: /opt/app-root/src/.ssh/id_rsa/ssh-privatekey
+    - name: CERT_EXPIRY_WARN_DAYS
+      value: "45"      # must be a string, don't forget the quotes
+    volumeMounts:
+    - name: sshkey
+      mountPath: /opt/app-root/src/.ssh/id_rsa
+    - name: inventory
+      mountPath: /tmp/inventory
+    - name: reports
+      mountPath: /var/lib/certcheck
+  volumes:
+  - name: sshkey
+    secret:
+      secretName: sshkey
+  - name: inventory
+    configMap:
+      name: inventory
+  - name: reports
+    persistentVolumeClaim:
+      claimName: certcheck-reports
+  restartPolicy: Never
diff --git a/examples/scheduled-certcheck-upload.yaml b/examples/scheduled-certcheck-upload.yaml
new file mode 100644
index 000000000..b0a97361b
--- /dev/null
+++ b/examples/scheduled-certcheck-upload.yaml
@@ -0,0 +1,53 @@
+# An example ScheduledJob to run a regular check of OpenShift's internal
+# certificate status.
+#
+# Each job will upload new reports to a directory in the master hosts
+#
+# The Job specification is the same as 'certificate-check-upload.yaml'
+# and the expected pre-configuration is equivalent.
+# See that Job example and examples/README.md for more details.
+#
+# NOTE: ScheduledJob has been renamed to CronJob in upstream k8s recently. At
+# some point (OpenShift 3.6+) this will have to be renamed to "kind: CronJob"
+# and once the API stabilizes the apiVersion will have to be updated too.
+---
+apiVersion: batch/v2alpha1
+kind: ScheduledJob
+metadata:
+  name: certificate-check
+  labels:
+    app: certcheck
+spec:
+  schedule: "0 0 1 * *"      # every 1st day of the month at midnight
+  jobTemplate:
+    metadata:
+      labels:
+        app: certcheck
+    spec:
+      template:
+        spec:
+          containers:
+          - name: openshift-ansible
+            image: openshift/openshift-ansible
+            env:
+            - name: PLAYBOOK_FILE
+              value: playbooks/certificate_expiry/easy-mode-upload.yaml
+            - name: INVENTORY_FILE
+              value: /tmp/inventory/hosts       # from configmap vol below
+            - name: ANSIBLE_PRIVATE_KEY_FILE    # from secret vol below
+              value: /opt/app-root/src/.ssh/id_rsa/ssh-privatekey
+            - name: CERT_EXPIRY_WARN_DAYS
+              value: "45"      # must be a string, don't forget the quotes
+            volumeMounts:
+            - name: sshkey
+              mountPath: /opt/app-root/src/.ssh/id_rsa
+            - name: inventory
+              mountPath: /tmp/inventory
+          volumes:
+          - name: sshkey
+            secret:
+              secretName: sshkey
+          - name: inventory
+            configMap:
+              name: inventory
+          restartPolicy: Never
diff --git a/examples/scheduled-certcheck-volume.yaml b/examples/scheduled-certcheck-volume.yaml
new file mode 100644
index 000000000..74cdc9e7f
--- /dev/null
+++ b/examples/scheduled-certcheck-volume.yaml
@@ -0,0 +1,58 @@
+# An example ScheduledJob to run a regular check of OpenShift's internal
+# certificate status.
+#
+# Each job will add a new pair of reports to the configured Persistent Volume
+#
+# The Job specification is the same as 'certificate-check-volume.yaml'
+# and the expected pre-configuration is equivalent.
+# See that Job example and examples/README.md for more details.
+#
+# NOTE: ScheduledJob has been renamed to CronJob in upstream k8s recently. At
+# some point (OpenShift 3.6+) this will have to be renamed to "kind: CronJob"
+# and once the API stabilizes the apiVersion will have to be updated too.
+---
+apiVersion: batch/v2alpha1
+kind: ScheduledJob
+metadata:
+  name: certificate-check
+  labels:
+    app: certcheck
+spec:
+  schedule: "0 0 1 * *"      # every 1st day of the month at midnight
+  jobTemplate:
+    metadata:
+      labels:
+        app: certcheck
+    spec:
+      template:
+        spec:
+          containers:
+          - name: openshift-ansible
+            image: openshift/openshift-ansible
+            env:
+            - name: PLAYBOOK_FILE
+              value: playbooks/certificate_expiry/html_and_json_timestamp.yaml
+            - name: INVENTORY_FILE
+              value: /tmp/inventory/hosts       # from configmap vol below
+            - name: ANSIBLE_PRIVATE_KEY_FILE    # from secret vol below
+              value: /opt/app-root/src/.ssh/id_rsa/ssh-privatekey
+            - name: CERT_EXPIRY_WARN_DAYS
+              value: "45"      # must be a string, don't forget the quotes
+            volumeMounts:
+            - name: sshkey
+              mountPath: /opt/app-root/src/.ssh/id_rsa
+            - name: inventory
+              mountPath: /tmp/inventory
+            - name: reports
+              mountPath: /var/lib/certcheck
+          volumes:
+          - name: sshkey
+            secret:
+              secretName: sshkey
+          - name: inventory
+            configMap:
+              name: inventory
+          - name: reports
+            persistentVolumeClaim:
+              claimName: certcheck-reports
+          restartPolicy: Never