Upgrade Supermarket
Upgrade Matrix
If running Supermarket 4.2, you can upgrade directly to the latest releases of Supermarket 5.0. If you are running a release with version less than 4.2 you must perform a stepped upgrade as outlined below.
Running Version | Upgrade Version | Supported Version |
---|---|---|
4.2 | 5.0 | Yes |
< 4.2 | 4.2 | No |
Supported Release
Chef Supermarket uses the PostgreSQL database. PostgreSQL 9.3 is EOL and Private Supermarket users should upgrade to Supermarket 5.0 or above and migrate to PostgreSQL 13.
Chef Software supports Supermarket 5.0 release and later. Earlier releases are not supported. For more information about supported Chef Software see the Supported Versions documentation.
Upgrade a Private Supermarket
Every Private Supermarket installation is unique. These are general steps for upgrading a Private Supermarket.
Stop the Supermarket services:
sudo supermarket-ctl stop
Backup the
/var/opt/supermarket
directory.Download the Chef Supermarket package from Chef Downloads.
Upgrade your system by installing the new package using the appropriate package manager for your distribution:
For Ubuntu:
dpkg -i /path/to/package/supermarket*.deb
For RHEL / CentOS:
rpm -Uvh /path/to/package/supermarket*.rpm
Reconfigure Chef Supermarket server:
sudo supermarket-ctl reconfigure
Once the Private Supermarket upgrade finishes, restart the services that run Chef Supermarket to clear the old installation of Chef Supermarket from the server memory.
systemctl list-units | grep runsvdir
Restart the unit:
systemctl restart UNIT_NAME
This will restart the
runsvdir
,runsv
, andsvlogd
service processes that run Chef Supermarket.
Release Specific Upgrade: Supermarket 5.0 and PostgreSQL 13.4
Supermarket 5.0 upgrades PostgreSQL from 9.3 to 13.4. The 5.0 upgrade process requires a one-time downtime to vacuum, upgrade, and re-index the database.
Supermarket 5.0 Changes
Prepare for the upgrade by following these steps:
- Set the attribute:
default['supermarket']['postgresql']['pg_upgrade_timeout']
insupermarket.rb
to the intended timeout value (in seconds) for the upgrade. Set this value based on the size of your data. - PostgreSQL 13 deprecated the
checkpoint-segments
attribute and we have removed it from the Supermarket configuration. Remove this entry from your configuration:
default['supermarket']['postgresql']['checkpoint_segments']
PostgreSQL 13.4 Upgrade
Each Private Supermarket installation is unique. The PostgreSQL upgrade steps are a general process intended for the internal PostgreSQL.
- External PostgreSQL: The end user is responsible for upgrading and maintaining External PostgreSQL configurations.
- Internal PostgreSQL: The PostgreSQL upgrade steps are a general process intended for the internal PostgreSQL.
Danger
Backup the Supermarket database:
Database migrations have inherent risk to your system. Create a backup before beginning any migration or update. This ensures that you have a recoverable state in case any step in the process fails. Copy the backup to a another disk that is not connected to the Private Supermarket installation. This ensures that you have state to restore, in case of a failure in the upgrade process
Back up the PostgreSQL database before upgrading so you can restore the full database to a previous release in the event of a failure in the upgrade steps below.
sudo -u supermarket /opt/supermarket/embedded/bin/pg_dumpall -U supermarket 1543 > / tmp/supermarket-dump.sql
Vacuum the database:
Run
VACUUM FULL
on the PostgreSQL database if you don’t have automatic vacuuming set up. This process will reduce the size of the database by deleting unnecessary data and speeds up the migration. TheVACUUM FULL
operation takes around 1 to 2 minutes per gigabyte of data depending on the complexity of the data, and requires free disk space at least as large as the size of your database.For more information on upgrading using
vacuumdb
see the PostgreSQL 13 documentation for vacuumdb.sudo -u supermarket /opt/supermarket/embedded/bin/vacuumdb --all --full -p 15432
Upgrade Supermarket:
Follow the Upgrade a Private Supermarket steps.
Cleanup the installation:
Follow these steps to clean up the old PostgreSQL installation and other clutter in the cache.
Stop the Supermarket application:
sudo supermarket-ctl stop
Start the newly installed PostgreSQL server.
sudo supermarket-ctl start postgresql
Reindex the database:
reindexdb
is a utility for rebuilding indexes in a PostgreSQL database.For more information on upgrading using
reindexdb
see the PostgreSQL 13 documentation for reindexdb.sudo -u supermarket /opt/supermarket/embedded/bin/reindexdb --all -p 15432
Restart Supermarket:
sudo supermarket-ctl restart
Release Specific Upgrade: Chef Infra Server 15.8.x
Private Supermarket users upgrading to Chef Infra Server version 15.8.0 or above must refresh their logins and re-authenticate Supermarket with Chef Identity.
Troubleshooting
Recovering from Database Cleanup Failures
If either the vacuumdb
or reindexdb
commands fail
Drop the Supermarket PostgreSQL database
/opt/supermarket/embedded/bin/psql -U supermarket -d postgres -p 15432 -c "drop database supermarket"
Recreate the Supermarket PostgreSQL database
/opt/supermarket/embedded/bin/psql -U supermarket -d postgres -p 15432 -c "create database supermarket"
Restore Supermarket PostgreSQL database from the existing dump file:
supermarket-dump-archive.sql
/opt/supermarket/embedded/bin/psql -U supermarket -d supermarket -p 15432 -f /tmp/supermarket-dump-archive.sql
Restart the Supermarket application
supermarket-ctl restart