diff --git a/_vendor/github.com/chef/supermarket/docs-chef-io/content/supermarket/supermarket_upgrade.md b/_vendor/github.com/chef/supermarket/docs-chef-io/content/supermarket/supermarket_upgrade.md index 4b6c454ce9..6c92ab3848 100644 --- a/_vendor/github.com/chef/supermarket/docs-chef-io/content/supermarket/supermarket_upgrade.md +++ b/_vendor/github.com/chef/supermarket/docs-chef-io/content/supermarket/supermarket_upgrade.md @@ -1,5 +1,5 @@ +++ -title = "Upgrade Supermarket" +title = "Upgrade Chef Supermarket" date = 2021-12-28T11:04:48-08:00 draft = false gh_repo = "supermarket" @@ -11,185 +11,244 @@ gh_repo = "supermarket" parent = "supermarket/server" +++ - -## Upgrade Matrix +This document explains how to upgrade Supermarket. - 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. +## Supported versions -Running Version | Upgrade Version | Supported Version -----------------|-----------------|------------------ -4.2 | 5.0 | Yes -< 4.2 | 4.2 | No +Progress Chef supports Supermarket 5.0 and later. For more details about supported Chef Software, see the [supported versions documentation](/versions/#supported-free-distributions). -## Supported Release +### PostgreSQL bundled with Supermarket -Chef Supermarket uses the PostgreSQL database. [PostgreSQL 9.3 is EOL](https://endoflife.date/postgresql) and Private Supermarket users should upgrade to [Supermarket 5.0](https://www.chef.io/downloads) or above and migrate to [PostgreSQL 13](https://www.postgresql.org/about/news/postgresql-13-released-2077/). +Supermarket is bundled with PostgreSQL. +The following table shows which version of PostgreSQL is bundled with each Supermarket version. -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](https://docs.chef.io/versions/#supported-commercial-distributions) documentation. +| Supermarket version | PostgreSQL version | +|---------------------|--------------------| +| >= 4.2 and < 5.0 | 9.3 | +| >= 5.0 and < 5.2 | 13.4 | +| >= 5.2 | 13.18 | -## Upgrade a Private Supermarket +## Before you upgrade -Every Private Supermarket installation is unique. These are general steps for upgrading a Private Supermarket. +Use these guidelines to choose the correct upgrade process: - 1. Stop the Supermarket services: +- If you're upgrading from Supermarket 4.2.x to Supermarket 5.x, this also upgrades the version of PostgreSQL embedded with Supermarket. This process requires extra steps for managing the database and Supermarket configuration. Follow the [Upgrade to Supermarket 5.0 documentation](#upgrade-to-supermarket-42x-to-5x). - ```bash - sudo supermarket-ctl stop - ``` +- If you want to upgrade from a version earlier than 4.2 to Supermarket 5.x, first upgrade to Supermarket 4.2.x using the [regular upgrade process](#upgrade-supermarket), then [upgrade to version 5.x](#upgrade-to-supermarket-42x-to-5x). - 1. Backup the `/var/opt/supermarket` directory. - 1. Download the Chef Supermarket package from [Chef Downloads](https://www.chef.io/downloads). - 1. Upgrade your system by installing the new package using the appropriate package manager for your distribution: - - For Ubuntu: +- For all other upgrades, follow the [regular upgrade process](#upgrade-supermarket). - ```bash - dpkg -i /path/to/package/supermarket*.deb - ``` +## Upgrade Supermarket - - For RHEL / CentOS: +To upgrade Supermarket, follow these steps: - ```bash - rpm -Uvh /path/to/package/supermarket*.rpm - ``` +1. Stop the Supermarket services: - 1. Start the Chef Supermarket services: + ```bash + sudo supermarket-ctl stop + ``` - ```bash - sudo supermarket-ctl start - ``` +1. Back up the `/var/opt/supermarket` directory. +1. Download a Supermarket package from [Chef Downloads](https://www.chef.io/downloads). +1. Install the new package using your distribution's package manager: - 1. Reconfigure Chef Supermarket server: + - For Ubuntu: ```bash - sudo supermarket-ctl reconfigure + dpkg -i /path/to/package/supermarket*.deb ``` - 1. 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. + - For RHEL: ```bash - systemctl list-units | grep runsvdir + rpm -Uvh /path/to/package/supermarket*.rpm ``` - 1. Restart the unit: +1. Start the Chef Supermarket services: - ```bash - systemctl restart UNIT_NAME - ``` + ```bash + sudo supermarket-ctl start + ``` + +1. Reconfigure Chef Supermarket server: - This will restart the `runsvdir`, `runsv`, and `svlogd` service processes that run Chef Supermarket. + ```bash + sudo supermarket-ctl reconfigure + ``` -## Release Specific Upgrade: Supermarket 5.0 and PostgreSQL 13.4 +1. After the upgrade finishes, restart the services that run Chef Supermarket to clear the old installation from server memory. -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. + ```bash + systemctl list-units | grep runsvdir + ``` -### Supermarket 5.0 Changes +1. Restart the unit: -Prepare for the upgrade by following these steps: + ```bash + systemctl restart + ``` -1. Set the attribute: `default['supermarket']['postgresql']['pg_upgrade_timeout']` in `supermarket.rb` to the intended timeout value (***in seconds***) for the upgrade. Set this value based on the size of your data. -1. PostgreSQL 13 deprecated the `checkpoint-segments` attribute and we have removed it from the Supermarket configuration. Remove this entry from your configuration: + This restarts the `runsvdir`, `runsv`, and `svlogd` service processes that run Chef Supermarket. - ```ruby - default['supermarket']['postgresql']['checkpoint_segments'] - ``` +## Upgrade to Supermarket 4.2.x to 5.x -### PostgreSQL 13.4 Upgrade +When you upgrade from Supermarket 4.2.x to 5.x, this also [upgrades PostgreSQL from 9.3 to 13.x](#postgresql-bundled-with-supermarket). +This process requires a one-time downtime to vacuum, upgrade, and re-index the database. -Each Private Supermarket installation is unique. The PostgreSQL upgrade steps are a general process intended for the _internal PostgreSQL_. +### Configure PostgreSQL in the Supermarket settings -- **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_. +Prepare for the upgrade: -{{< danger >}} -**BACKUP THE SUPERMARKET DATABASE AND SECURE THE DATA.** Preserve your backup at all costs. Copy the backup to a second and separate location. -{{< /danger >}} +1. In the `supermarket.rb` settings, set the `pg_upgrade_timeout` attribute to the intended timeout value in seconds. -1. Backup the Supermarket database: + For example: - 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 + ```rb + default['supermarket']['postgresql']['pg_upgrade_timeout'] = + ``` - 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. + Set this value based on your data size. + +1. Remove the `checkpoint-segments` attribute from your `supermarket.rb` settings: + + ```ruby + # This setting is EOL in Supermarket 5.x and PostgreSQL 13 + # default['supermarket']['postgresql']['checkpoint_segments'] + ``` + + PostgreSQL removed the `checkpoint_segments` attribute and we removed it from the Supermarket configuration. + +### Prepare PostgreSQL embedded with Supermarket + +Prepare the PostgreSQL database for upgrading: + +1. Create a backup of the PostgreSQL databases: ```bash - sudo -u supermarket /opt/supermarket/embedded/bin/pg_dumpall -U supermarket 1543 > / tmp/supermarket-dump.sql + cd / + sudo -u supermarket /opt/supermarket/embedded/bin/pg_dumpall -U supermarket -p 15432 > /tmp/supermarket-dump.sql ``` + **Important:** Always back up your PostgreSQL data before upgrading. Store a copy of the backup in a separate, safe location that is not on the Supermarket server. This ensures you can restore your data if anything goes wrong during the upgrade. + 1. 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. The `VACUUM 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. + ```bash + cd / + sudo -u supermarket /opt/supermarket/embedded/bin/vacuumdb --all --full -p 15432 + ``` + + This reduces the database size by deleting unnecessary data and speeds up the migration. Vacuuming takes about 1 to 2 minutes per gigabyte of data, depending on data complexity, and requires free disk space at least as large as your database. + + For more information, see the [`vacuumdb` documentation](https://www.postgresql.org/docs/13/app-vacuumdb.html). + +### Upgrade Supermarket - For more information on upgrading using `vacuumdb` see the PostgreSQL 13 documentation for [vacuumdb](https://www.postgresql.org/docs/13/app-vacuumdb.html). +To upgrade Supermarket, follow these steps: + +1. Stop the Supermarket services: + + ```bash + sudo supermarket-ctl stop + ``` + +1. Back up the `/var/opt/supermarket` directory. + +1. Download a Supermarket package from [Chef Downloads](https://www.chef.io/downloads). + +1. Install the new package using your distribution's package manager: + + - For Ubuntu: ```bash - sudo -u supermarket /opt/supermarket/embedded/bin/vacuumdb --all --full -p 15432 + dpkg -i /path/to/package/supermarket*.deb ``` -1. Upgrade Supermarket: + - For RHEL: - Follow the [Upgrade a Private Supermarket]({{< relref "#upgrade-a-private-supermarket" >}}) steps. -

+ ```bash + rpm -Uvh /path/to/package/supermarket*.rpm + ``` -1. Cleanup the installation: +1. Reconfigure Chef Supermarket server: - Follow these steps to clean up the old PostgreSQL installation and other clutter in the cache. + ```bash + sudo supermarket-ctl reconfigure + ``` - 1. Stop the Supermarket application: +1. After the upgrade finishes, restart the services that run Chef Supermarket to clear the old installation from server memory. - ```bash - sudo supermarket-ctl stop - ``` + ```bash + systemctl list-units | grep runsvdir + ``` - 1. Start the newly installed PostgreSQL server. +1. Restart the unit: - ```bash - sudo supermarket-ctl start postgresql - ``` + ```bash + systemctl restart + ``` + + This restarts the `runsvdir`, `runsv`, and `svlogd` service processes that run Chef Supermarket. + +### Clean up the PostgreSQL database -1. Reindex the database: +Follow these steps to remove the old PostgreSQL installation and clear the cache: - `reindexdb` is a utility for rebuilding indexes in a PostgreSQL database. +1. Stop Supermarket: + + ```bash + sudo supermarket-ctl stop + ``` - For more information on upgrading using `reindexdb` see the PostgreSQL 13 documentation for [reindexdb](https://www.postgresql.org/docs/13/app-reindexdb.html). +1. Start the newly installed PostgreSQL server: + + ```bash + sudo supermarket-ctl start postgresql + ``` + +1. Reindex the PostgreSQL database: ```bash sudo -u supermarket /opt/supermarket/embedded/bin/reindexdb --all -p 15432 ``` + [`reindexdb`](https://www.postgresql.org/docs/13/app-reindexdb.html) rebuilds PostgreSQL database indexes. + 1. Restart Supermarket: ```bash sudo supermarket-ctl restart ``` -## Release Specific Upgrade: Chef Infra Server 15.8.x +## 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. +If you use Private Supermarket and upgrade to Chef Infra Server version 15.8.0 or above, refresh your logins and re-authenticate Supermarket with Chef Identity. ## Troubleshooting -### Recovering from Database Cleanup Failures +### Recovering from database cleanup failures -If either the `vacuumdb` or `reindexdb` commands fail +If the `vacuumdb` or `reindexdb` commands fail, follow these steps: -1. Drop the Supermarket PostgreSQL database +1. Drop the Supermarket PostgreSQL database: ```bash /opt/supermarket/embedded/bin/psql -U supermarket -d postgres -p 15432 -c "drop database supermarket" ``` -1. Recreate the Supermarket PostgreSQL database +1. Recreate the Supermarket PostgreSQL database: ```bash /opt/supermarket/embedded/bin/psql -U supermarket -d postgres -p 15432 -c "create database supermarket" ``` -1. Restore Supermarket PostgreSQL database from the existing dump file: `supermarket-dump-archive.sql` +1. Restore the Supermarket PostgreSQL database from the existing `supermarket-dump-archive.sql` dump file: ```bash /opt/supermarket/embedded/bin/psql -U supermarket -d supermarket -p 15432 -f /tmp/supermarket-dump-archive.sql ``` -1. Restart the Supermarket application +1. Restart Supermarket: ```bash supermarket-ctl restart diff --git a/_vendor/modules.txt b/_vendor/modules.txt index 782d05b54c..6fce7128fe 100644 --- a/_vendor/modules.txt +++ b/_vendor/modules.txt @@ -9,7 +9,7 @@ # github.com/inspec/inspec-habitat/docs-chef-io v0.0.0-20220218210405-bfd542da49fd # github.com/inspec/inspec-k8s/docs-chef-io v0.0.0-20240122032042-421355eaf502 # github.com/chef/chef-workstation/docs-chef-io v0.0.0-20250522055454-8df8550a2503 -# github.com/chef/supermarket/docs-chef-io v0.0.0-20241105172430-a362eded8f72 +# github.com/chef/supermarket/docs-chef-io v0.0.0-20250602140848-cded623a3f5c # github.com/chef/effortless/docs-chef-io v0.0.0-20230711123605-c8beb79aba4f # github.com/chef/compliance-profiles/docs-chef-io v0.0.0-20250529075927-4db22de509f8 # github.com/chef/compliance-remediation-2022/docs-chef-io v0.0.0-20250529065228-f3ed2176e6bf diff --git a/go.mod b/go.mod index b81c3e6b45..90ca598182 100644 --- a/go.mod +++ b/go.mod @@ -13,7 +13,7 @@ require ( github.com/chef/effortless/docs-chef-io v0.0.0-20230711123605-c8beb79aba4f // indirect github.com/chef/license-service/docs-chef-io v0.0.0-20250120051510-ae1de80f4621 // indirect github.com/chef/samples v0.0.0-20250424163637-3393187e624c // indirect - github.com/chef/supermarket/docs-chef-io v0.0.0-20241105172430-a362eded8f72 // indirect + github.com/chef/supermarket/docs-chef-io v0.0.0-20250602140848-cded623a3f5c // indirect github.com/cowboy/jquery-hashchange v0.0.0-20100902193700-0310f3847f90 // indirect github.com/habitat-sh/habitat/components/docs-chef-io v0.0.0-20250523161510-a254ccc738ad // indirect github.com/inspec/inspec-alicloud/docs-chef-io v0.0.0-20240122032124-a1d2a214e170 // indirect diff --git a/go.sum b/go.sum index 2003e69eb5..b2b9e41cfe 100644 --- a/go.sum +++ b/go.sum @@ -18,8 +18,8 @@ github.com/chef/license-service/docs-chef-io v0.0.0-20250120051510-ae1de80f4621 github.com/chef/license-service/docs-chef-io v0.0.0-20250120051510-ae1de80f4621/go.mod h1:leNCF0KadV7zjm7YpVegNnbmWYUFXgaPKHP4tTDacos= github.com/chef/samples v0.0.0-20250424163637-3393187e624c h1:wjPanPVse/MWOel7hQ2tx/YVO2taon1qv6DWtfNn6Fo= github.com/chef/samples v0.0.0-20250424163637-3393187e624c/go.mod h1:RiMNPQ6ddrNSgTOcBrYaEVicaP52xs9TQz4RA+XTreA= -github.com/chef/supermarket/docs-chef-io v0.0.0-20241105172430-a362eded8f72 h1:mGnH8fxL69YfwoLP+mJP5fodAukQVf0A5lmF+7Cq/64= -github.com/chef/supermarket/docs-chef-io v0.0.0-20241105172430-a362eded8f72/go.mod h1:D+9mmEZxCwpdhZ8LrEODBWMwMufmJUubSt5NlU/lLB4= +github.com/chef/supermarket/docs-chef-io v0.0.0-20250602140848-cded623a3f5c h1:qwUIyVKomElUxOdGjCRarkP0eRQOHA7cdgr0/X8ZQbA= +github.com/chef/supermarket/docs-chef-io v0.0.0-20250602140848-cded623a3f5c/go.mod h1:D+9mmEZxCwpdhZ8LrEODBWMwMufmJUubSt5NlU/lLB4= github.com/cowboy/jquery-hashchange v0.0.0-20100902193700-0310f3847f90 h1:p/a5iSATj0OjrqJLX/YKxYdGXhZzW58yyyNIC4JY4S0= github.com/cowboy/jquery-hashchange v0.0.0-20100902193700-0310f3847f90/go.mod h1:N/6F0+wmdvL6k0AjqyKIncMRClKAN92atjZdTLtYMaw= github.com/habitat-sh/habitat/components/docs-chef-io v0.0.0-20250523161510-a254ccc738ad h1:ouEmy8zUhSus+Tqi0IDVktKo6OCCGQ84xmGNsDQfKdw=