diff options
| -rw-r--r-- | HOOKS.md | 70 |
1 files changed, 70 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). |