summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJason DeTiberus <detiber@gmail.com>2017-01-24 12:38:53 -0500
committerGitHub <noreply@github.com>2017-01-24 12:38:53 -0500
commit46532d49f6960f437458dcd02d2cd8e9459f98a3 (patch)
tree4c640c123204d52259028a08f4e0cb295a36feb5
parent89b4e7070dc57aea6c2e1dc038348142ed4c747a (diff)
parentb96952753d458f8dd903daee218795c22000eb5a (diff)
downloadopenshift-46532d49f6960f437458dcd02d2cd8e9459f98a3.tar.gz
openshift-46532d49f6960f437458dcd02d2cd8e9459f98a3.tar.bz2
openshift-46532d49f6960f437458dcd02d2cd8e9459f98a3.tar.xz
openshift-46532d49f6960f437458dcd02d2cd8e9459f98a3.zip
Merge pull request #3125 from ashcrow/serial-master-upgrade-doc
HOOKS.md added documenting new hooks
-rw-r--r--HOOKS.md70
-rw-r--r--README.md6
2 files changed, 76 insertions, 0 deletions
diff --git a/HOOKS.md b/HOOKS.md
new file mode 100644
index 000000000..9c5f80054
--- /dev/null
+++ b/HOOKS.md
@@ -0,0 +1,70 @@
+# Hooks
+
+The ansible installer allows for operators to execute custom tasks during
+specific operations through a system called hooks. Hooks allow operators to
+provide files defining tasks to execute before and/or after specific areas
+during installations and upgrades. This can be very helpful to validate
+or modify custom infrastructure when installing/upgrading OpenShift.
+
+It is important to remember that when a hook fails the operation fails. This
+means a good hook can run multiple times and provide the same results. A great
+hook is idempotent.
+
+**Note**: There is currently not a standard interface for hooks. In the future
+a standard interface will be defined and any hooks that existed previously will
+need to be updated to meet the new standard.
+
+## Using Hooks
+
+Hooks are defined in the ``hosts`` inventory file under the ``OSEv3:vars``
+section.
+
+Each hook should point to a yaml file which defines Ansible tasks. This file
+will be used as an include meaning that the file can not be a playbook but
+a set of tasks. Best practice suggests using absolute paths to the hook file to avoid any ambiguity.
+
+### Example
+```ini
+[OSEv3:vars]
+# <snip>
+openshift_master_upgrade_pre_hook=/usr/share/custom/pre_master.yml
+openshift_master_upgrade_hook=/usr/share/custom/master.yml
+openshift_master_upgrade_post_hook=/usr/share/custom/post_master.yml
+# <snip>
+```
+
+Hook files must be a yaml formatted file that defines a set of Ansible tasks.
+The file may **not** be a playbook.
+
+### Example
+```yaml
+---
+# Trivial example forcing an operator to ack the start of an upgrade
+# file=/usr/share/custom/pre_master.yml
+
+- name: note the start of a master upgrade
+ debug:
+ msg: "Master upgrade of {{ inventory_hostname }} is about to start"
+
+- name: require an operator agree to start an upgrade
+ pause:
+ prompt: "Hit enter to start the master upgrade"
+```
+
+## Upgrade Hooks
+
+### openshift_master_upgrade_pre_hook
+- Runs **before** each master is upgraded.
+- This hook runs against **each master** in serial.
+- If a task needs to run against a different host, said task will need to use [``delegate_to`` or ``local_action``](http://docs.ansible.com/ansible/playbooks_delegation.html#delegation).
+
+### openshift_master_upgrade_hook
+- Runs **after** each master is upgraded but **before** it's service/system restart.
+- This hook runs against **each master** in serial.
+- If a task needs to run against a different host, said task will need to use [``delegate_to`` or ``local_action``](http://docs.ansible.com/ansible/playbooks_delegation.html#delegation).
+
+
+### openshift_master_upgrade_post_hook
+- Runs **after** each master is upgraded and has had it's service/system restart.
+- This hook runs against **each master** in serial.
+- If a task needs to run against a different host, said task will need to use [``delegate_to`` or ``local_action``](http://docs.ansible.com/ansible/playbooks_delegation.html#delegation).
diff --git a/README.md b/README.md
index def8dfdc5..c3c022e59 100644
--- a/README.md
+++ b/README.md
@@ -74,6 +74,12 @@ you are not running a stable release.
- [OpenShift Enterprise](https://docs.openshift.com/enterprise/latest/install_config/install/advanced_install.html)
- [OpenShift Origin](https://docs.openshift.org/latest/install_config/install/advanced_install.html)
+
+## Installer Hooks
+
+See the [hooks documentation](HOOKS.md).
+
+
## Contributing
See the [contribution guide](CONTRIBUTING.md).