Upgrade Chef Automate

[edit on GitHub]


The following sections describe the upgrade process between versions of Chef Automate and when upgrading from a delivery-cluster setup to Chef Automate.


This section describes the prereqs for the upgrade.

  1. Previously installed version of Chef Automate.
  2. sudo or root access to the machine.

Update license

If you need to update a license on a Chef Automate server, perform the following steps:

  1. Securely copy your new license to your Chef Automate server. You must overwrite the current delivery.license file located at /var/opt/delivery/license/delivery.license. The scp utility is used below to log into an Ubuntu machine; however, you can use other utilities such as rsync to securely copy the new license onto your Chef Automate server.

    scp -i SSH_KEY /path/to/automate.license ubuntu@IP_ADDRESS:/home/ubuntu/automate.license
  2. Log into the Chef Automate server via SSH.

    ssh -i SSH_KEY ubuntu@IP_ADDRESS
  3. After a successful login, copy the license file to the /var/opt/delivery/license directory.

    sudo mv ~/automate.license /var/opt/delivery/license/delivery.license
  4. Reconfigure and restart your Chef Automate server.

    sudo automate-ctl reconfigure && sudo automate-ctl restart


To upgrade to the latest version of Chef Automate, do the following:

  1. Download the latest version of Chef Automate from https://downloads.chef.io/automate/ and copy it to your Chef Automate server.

  2. Update the package as appropriate for the server’s OS:

    For Debian:


    For Red Hat or Centos:

  3. If you are upgrading from a previous version of Chef Automate, then run sudo automate-ctl reconfigure to complete the upgrade process. If you are upgrading from a delivery-cluster setup, then skip to the section below.


    This will restart your Chef Automate services and may result in a brief period of unavailability.


    Prior to Chef Automate 0.6.0, this tool was named delivery-ctl. To support backwards compatibility, you can continue to call delivery-ctl in Chef Automate 0.6.0.

Upgrading from a delivery-cluster setup

Chef Delivery clusters configured using the delivery-cluster setup process specify a search method to identify build nodes that is not compatible with the previous build node or new runner installation mechanisms used by Chef Automate. In order to ensure that both your existing build nodes and those added with automate-ctl install-build-node or automate-ctl install-runner can be seen by an Chef Automate server, you will need to edit /etc/delivery/delivery.rb and modify the value present for delivery['default_search'].

In the delivery.rb configured by delivery-cluster, you will find a line that looks like this:

delivery['default_search']   = "((recipes:delivery_build OR recipes:delivery_build\\\\:\\\\:default) AND chef_environment:_default)"

If you have further customized this setting, modify your custom query to include OR tags:delivery-build-node. If you have not modified it from what delivery-cluster set up, you can replace it with the following line:

delivery['default_search']   = "((recipes:delivery_build OR recipes:delivery_build\\\\:\\\\:default OR tags:delivery-build-node) AND chef_environment:_default)"

Save your changes and then run sudo automate-ctl reconfigure to complete the upgrade process.


Legacy build nodes created by delivery-cluster can be used with a Chef Automate server. Some visibility features are designed to only work with new build nodes and runners installed through the command line process, but the workflow feature in Chef Automate can use legacy, new, or mixed node pools; however, you cannot upgrade a legacy build node to the new build node or runner models. If you would like to use new build nodes/runners, please use fresh hosts or completely wipe your legacy build nodes before attempting to run automate-ctl install-build-node or automate-ctl install-runner.

Upgrading and the automate-ctl setup command

The automate-ctl setup command used during the Chef Automate installation process is intended to simplify the initial configuration of your Chef Automate cluster. If your cluster is up and running, you don’t need to run this command; however to set up additional runners with the automate-ctl install-runner command, running automate-ctl setup is recomended to ensure all required files are in the correct place.

Upgrading to Push Jobs Server 2.1 and Later

If you are using Push Jobs Server to orchestrate your build nodes, 2.1.0 and later are now fully supported for use with Chef Automate. Instructions for this upgrade can be found here.