Upgrade to Chef Automate 3.x
Warning
Chef Automate provides an entire suite of enterprise capabilities for node visibility and compliance. Chef Automate upgrades from one minor version to another automatically. However, Chef Automate will not 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
Please choose following upgrade journey based on your current version of Chef Automate. All of these upgrades are manual upgrades.
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 are not on this version, please do normal upgrade as per 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 Internet connected machine
- Download 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 bundle of version 20220329091442
./chef-automate airgap bundle create --version 20220329091442
- Copy the bundle file
automate-20220329091442.aib
and latest downloaded CLIchef-automate
to the airgapped machine running Chef Automate.
On the airgapped machine running Chef Automate
- Upgrade Automate with bundle
sudo ./chef-automate upgrade run --airgap-bundle automate-20220329091442.aib
- Check all services are up and 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
There are four possible upgrade scenarios:
- 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
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
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:
Here, you will be prompted to accept multiple Pre Upgrade checklist. Please ensure to do those actions before upgrade.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 we can directly download via 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 we can directly download via 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
/hab/svc/deployment-service/var/upgrade_metadata.json
. To mock completion of post upgrade checklist items.