Upgrade to Chef Automate 3.x

Chef Automate provides an entire suite of enterprise capabilities for node visibility and compliance. Chef Automate upgrades from one minor version to another automatically, but it won’t automatically upgrade to a major version. See the instructions below for manually upgrading Chef Automate from date-based versions to Chef Automate 3.x.

Upgrade journey

Choose the following upgrade journey based on your current version of Chef Automate. These upgrades are all manual.

Your Current Version	Upgrade To
Any version before 20220329091442	20220329091442
20220329091442	3.0.x

For example, if today you are on version 2021201164433, then your upgrade journey should be:

Manual upgrade to 20220329091442.
Manual upgrade to 3.0.x.

Prerequisites

Plan your downtime: This upgrade requires downtime. Before upgrading, set the environment to handle the downtime.
Backup Chef Automate database: This Chef Automate version upgrades PostgreSQL. Backup your data before upgrading.
Current Version should be 20220329091442 If you aren’t on this version, do a normal upgrade for your topology.

Upgrade to version 20220329091442

Check your current version:

sudo chef-automate version

If your Server Version is less than 20220329091442. Please upgrade to latest date pattern version number.

Airgapped upgrade to 20220329091442

On an internet-connected machine, download the latest Chef Automate CLI.

curl https://packages.chef.io/files/current/latest/chef-automate-cli/chef-automate_linux_amd64.zip | gunzip - > chef-automate && chmod +x chef-automate

Create a bundle for version 20220329091442.

./chef-automate airgap bundle create --version 20220329091442

Copy the bundle file automate-20220329091442.aib and the downloaded CLI chef-automate to the air-gapped machine running Chef Automate.

On the air-gapped machine, run the upgrade with the bundle.

sudo ./chef-automate upgrade run --airgap-bundle automate-20220329091442.aib

Check that all services are running.
```
sudo chef-automate status
```

Normal upgrade to 20220329091442

Upgrade Chef Automate to latest minor version (20220329091442):
```
sudo chef-automate upgrade run
```
Check all services are up and running:
```
sudo chef-automate status
```

Upgrade Path to version 3.0.x from 20220329091442

The following four upgrade scenarios are possible:

Chef Automate with Embedded PostgreSQL
Chef Automate with External PostgreSQL
Chef Automate in air-gapped environment with embedded PostgreSQL
Chef Automate in air-gapped environment with external PostgreSQL

Note

If you are unsure if your installation of Chef Automate is using an external PostgreSQL database, run chef-automate config show. You are using an external PostgreSQL database if enable=true is present in the global.v1.external.postgresql config setting.

Warning

Sixty percent of your drive should be free space before starting a major version upgrade.

Chef Automate with embedded PostgreSQL

To upgrade Chef Automate with embedded PostgreSQL, follow the steps given below:

Upgrade Chef Automate from version 20220329091442 to 3.0.x

Start a major version upgrade:
The command prompts you to accept several pre-upgrade checklist items. Complete those actions before you continue.
```
sudo chef-automate upgrade run --major
```

Once the upgrade is complete, you will get a list of steps to perform post-upgrade.

Post Upgrade Steps:

Check the upgrade status of Chef Automate:
```
sudo chef-automate upgrade status
```
When the status is up-to-date, move ahead.

Migrate your data from PostgreSQL 9.6 to PostgreSQL 13:

sudo chef-automate post-major-upgrade migrate --data=PG

Verify that all services are running:
```
sudo chef-automate status
```
Verify that all the data is present in your upgraded Chef Automate. If yes, clear the old PostgreSQL 9.6 data:
```
sudo chef-automate post-major-upgrade clear-data --data=PG
```

Chef Automate with external PostgreSQL

To upgrade Chef Automate with external PostgreSQL, follow the steps given below:

Upgrade Chef Automate from version 20220329091442 to 3.0.x

Upgrade your external PostgreSQL database v9.6 to v13.5 manually. See the external PostgreSQL upgrade documentation. If you have configured Host, Port, or Password of PostgreSQL, patch the new configuration to use Chef Automate.
Start major version upgrade:
```
sudo chef-automate upgrade run --major
```
Check upgrade status is up-to-date
```
sudo chef-automate status
```

Chef Automate in air-gapped environment with embedded PostgreSQL

Upgrade Chef Automate from version 20220329091442 to 3.0.x

To upgrade to 3.0.x, follow the steps below:

On internet-connected machine

Download latest CLI of Chef Automate

curl https://packages.chef.io/files/current/latest/chef-automate-cli/chef-automate_linux_amd64.zip | gunzip - > chef-automate && chmod +x chef-automate

Create an Airgap Installation Bundle (AIB):

sudo ./chef-automate airgap bundle create --version 3.0.49

Or you can download it with a curl request.

curl https://packages.chef.io/airgap_bundle/current/automate/3.0.49.aib -o automate-3.0.49.aib

Copy the latest Chef Automate CLI (chef-automate) and AIB (automate_3.0.x.aib) to the air-gapped machine running Chef Automate.

On air-gapped machine running Chef Automate

Make sure your upgrade strategy as none in Chef Automate config. Check using:
```
sudo ./chef-automate config show
```
Reference to change upgrade strategy

Upgrade using new AIB and Chef Automate CLI:

sudo ./chef-automate upgrade run --airgap-bundle automate_3.0.x.aib --major

Post Upgrade Steps:

Check the upgrade status of Chef Automate:
```
sudo chef-automate upgrade status
```
When the status is up-to-date, move ahead.

Migrate your data from PostgreSQL 9.6 to PostgreSQL 13:

sudo chef-automate post-major-upgrade migrate --data=PG

Verify that all services are running:
```
sudo chef-automate status
```
Verify that all the data is present in your upgraded Chef Automate. If yes, clear the old PostgreSQL 9.6 data:
```
sudo chef-automate post-major-upgrade clear-data --data=PG
```

Chef Automate in air-gapped environment with external PostgreSQL

Upgrade Chef Automate from version 20220329091442 to 3.0.x

To upgrade to 3.0.x, follow the steps below:

On internet-connected machine

Download latest CLI of Chef Automate

curl https://packages.chef.io/files/current/latest/chef-automate-cli/chef-automate_linux_amd64.zip | gunzip - > chef-automate && chmod +x chef-automate

Create an Airgap Installation Bundle (AIB):

sudo ./chef-automate airgap bundle create --version 3.0.49

Or you can download it with a curl request.

curl https://packages.chef.io/airgap_bundle/current/automate/latest.aib -o automate-3.0.49.aib

Copy the latest Chef Automate CLI (chef-automate) and AIB (automate_3.0.x.aib) to the air-gapped machine running Chef Automate.

On air-gapped machine running Chef Automate

Make sure your upgrade strategy as none in Chef Automate config. Check using:
```
sudo ./chef-automate config show
```
Reference to change upgrade strategy
Upgrade your external PostgreSQL database v9.6 to v13.5 manually. See the external PostgreSQL upgrade documentation. If you have configured Host, Port, or Password of PostgreSQL, patch the new configuration to use Chef Automate.

Upgrade using new AIB and Chef Automate CLI:

sudo ./chef-automate upgrade run --airgap-bundle automate_3.0.x.aib --major

Check upgrade status is up-to-date
```
sudo chef-automate status
```

Troubleshooting

If Chef Automate fails to migrate your data to PostgreSQL 13 when running chef-automate post-major-upgrade migrate --data=PG, restore the data:

sudo chef-automate backup restore </path/to/backups/>BACKUP_ID

If you have Air-Gapped bundle which you want to restore to, then use this command:

sudo chef-automate backup restore  --airgap-bundle </path/to/bundle> </path/to/backups/>BACKUP_ID

Reference for Restore methods.

Use the backup ID from the backup you created before starting the upgrade.

If the restore fails even after upgrading the Chef Automate version, follow the steps given below:

Uninstall Chef Automate:
```
sudo chef-automate uninstall
```
Install the last date-based version (20220329091442) using the air-gapped installation process. See the air-gapped installation documentation for more information.

Restore the backup:

sudo chef-automate backup restore <backup_id>

See the Chef Automate restore documentation for more information.

Note

If you used backup and restore method to migrate data then you will have to remove this file: /hab/svc/deployment-service/var/upgrade_metadata.json. To mock completion of post upgrade checklist items.