IMPORTANT: Action required to upgrade safely to Habitat 0.83.0!

A regression was found in the 0.82.0 release of the Supervisor that can cause problems for users when they update their Supervisor to a newer version. The issue has been fixed for the 0.83.0 release of the Supervisor, but users may need to take special steps in order to cleanly transition. Read on for further details.

Am I Affected?

If either of the following scenarios apply to your Habitat Supervisors, then you are affected by this regression.

  • You are running the Supervisor with the --auto-update option.
  • You are using the SIGHUP signal on Linux to cause the Supervisor to restart itself.

If neither of these applies to you, then you are not affected.

If you are affected, read on.

Steps to Take Before 0.83.0 is Released

The 0.83.0 release will be published on Monday, July 29th 2019 at 12:00PM EDT (UTC-04:00). If you are affected by this regression and you are running on a Linux OS, you must take the following steps before then.

If you are currently running with --auto-update on Linux, then you should restart your Supervisors without that option before the 0.83.0 release is published. This will also restart any services the Supervisor is running.

Additionally, do not send a SIGHUP signal to your 0.82.0 Supervisor.

If you are running with --auto-update on Windows, you do not need to restart the Supervisor with this option removed. This is due to differences in how Linux and Windows handle processes. You will still need to take some actions after 0.83.0 is released, however (see below).

Steps to Take After 0.83.0 is Released

If you are running on Linux, once the 0.83.0 release has been published, you should manually install the 0.83.0 Supervisor on disk:

hab pkg install core/hab-sup/0.83.0

On Windows, the --auto-update will still be present and 0.83.0 should be automatically downloaded. However, the Supervisor will continue to run 0.82.0 and may become unresponsive to hab commands.

Regardless of operating system, we will be performing a full restart of the Supervisor. It is therefore advisable to update your Launcher beforehand.

On Linux, you can install the Launcher directly:

hab pkg install core/hab-launcher

On Windows, you should instead update your Habitat Windows Service (as this will bring the new Launcher as a dependency):

hab pkg install core/windows-service
hab pkg exec core/windows-service uninstall
hab pkg exec core/windows-service install

Note that this will overwrite your C:\hab\svc\windows-service\HabService.dll.config file. You will want to make sure that the launcherArgs you used in your previous configuration get written to the new configuration.

With this in place, you should do a complete restart of your Supervisors, adding back the --auto-update option if you wish.

Though all deployments will be unique, the general pattern is as follows:

For Linux:

hab sup term
hab sup run

For Windows (assuming you are running the Supervisor with windows-service):

net stop habitat
net start habitat

This will also restart any services the Supervisors are running.

The 0.83.0 Supervisor can safely operate in --auto-update mode, and can also safely receive the SIGHUP signal.

What to Do if You Encounter the Regression

You will know if you have encountered this regression if your Supervisor appears to become unresponsive following a SIGHUP signal, or after attempting to upgrade the Supervisor to a more recent version. At this point, killing the Supervisor process is required.

On Linux, you can use something like pkill:

sudo pkill -9 hab-sup

Depending on how you are running the Supervisor (e.g., under SystemD or some other process supervision system), you may also need to terminate the hab-launch process, as well as the processes of any Habitat-supervised services that may still be running.

sudo pkill hab-launch
sudo pkill <service binary name>
# etc...

You can then restart the Supervisor normally, ensuring that you remove the --auto-update option until 0.83.0 is released, as detailed above.

On Windows, simply restart the Habitat Windows Service, as detailed above.

Thank you; apologies for any inconvenience this may cause.

What steps are needed if running a Supervisor older than 0.82.0?

@bixu The regression was only present in 0.82.0, so the only problem is going from 0.82.0 to something later. If you were to go from, say, 0.81.0 straight to 0.83.0, there wouldn’t be a problem.

It’s also just dealing with auto-update, so you’d probably be doing something a bit unusual to have auto-update on and also skip a version.

In other words, you’re fine :slight_smile: