|
|
@@ -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).
|
Steve Milner