Update reconfigure documentation
@@ -3,6 +3,8 @@ Each plan can specify lifecycle event handlers, or hooks, to perform certain act
To define a hook, simply create a bash file of the same name in `/my_plan_name/hooks/`, for example, `/postgresql/hooks/health-check`.
+When applying a new configuration, modification to the `run` or `post-run` hooks will restart the service.
+
> **Important** You cannot block the thread in a hook unless it is in the `run` hook. Never call `hab` or `sleep` in a hook that is not the `run` hook.
# Related article: Runtime settings
@@ -15,7 +17,6 @@ To define a hook, simply create a bash file of the same name in `/my_plan_name/h
* [health-check](#health-check)
* [init](#init)
* [install](#install)
-* [reload](#reload)
* [reconfigure](#reconfigure)
* [suitability](#suitability)
* [run](#run)
@@ -30,7 +31,7 @@ This hook is run whenever a configuration file that is not related to a user or
###health-check
File location: `<plan>/hooks/health-check`
-This hook is run when the Chef Habitat HTTP API receives a request at `/health`.
+This hook is run periodically on a configurable interval.
The `health-check` script must return a valid exit code from the list below.
@@ -76,15 +77,14 @@ The exit code returned from an `install` hook will be "remembered". If a previou
An `install` hook, unlike other hooks, will not have access to any census data exposed via binds or the `svc` namespace. Also, configuration in `svc_config_path` is not accesible to an `install` hook. If an `install` hook needs to utilize templated configuration files, templates located in the `svc_config_install_path` may be referenced. This location will contain rendered templates in a package's `config_install` folder. Finally, any configuration updates made during a service's runtime that would alter an `install` hook or any configuration template in `svc_config_install_path` will not cause a service to reload.
-###reload
-File location: `<plan>/hooks/reload`
-
-For processes that can update their configuration without requiring a restart a `reload` hook can be written. This hook will execute instead of the default behaviour of restarting the process. `{{pkg.svc_pid_file}}` can be used to get a handle on the `PID` of the service.
-
###reconfigure
File location: `<plan>/hooks/reconfigure`
-This hook is run when service configuration has changed due to updates coming from the gossip protocol or from the `user.toml` file. Before the `reconfigure` hook the config files are re-rendered and the process is either restarted or the `reload` hook is called if present.
+A `reconfigure` hook can be written for processes that can respond to changes in `<plan>/config` without requiring a restart. This hook will execute **instead** of the default behaviour of restarting the process. `{{pkg.svc_pid_file}}` can be used to get a handle on the `PID` of the service.
+
+The `reconfigure` hook is not necessarily run on every change to `<plan>/config`. The `reconfigure` hook will not be run if the service restarts before the `reconfigure` hook has run. The restart is considered sufficient for reconfiguring the service. For example, when applying a configuration that changes both the `run` hook and `<plan>/config`, the change to the `run` hook will trigger a restart and therefore the `reconfigure` hook will not be run.
+
+Habitat does not support changing the `PID` of the underlying process in any lifecycle hook. If part of a service's reconfiguration relies on changing the `PID`, you should not provide a `reconfigure` hook and rely on the default behaviour of restarting the service.
###suitability
File location: `<plan>/hooks/suitability`
