Upgrade to Chef Server 12

[edit on GitHub]

The following sections describe the upgrade process for Chef server 12.

Note

Be sure to back up the Chef server data before starting the upgrade process.

From Chef Server 12

There are three upgrade scenarios for upgrades from earlier versions of Chef server 12 to a newer version of Chef server 12:

Note

As of version 12.14, Chef server will not render passwords outside of the /etc/opscode directory by default. If you are not using any Chef server add-ons, or you’re using the latest add-on versions, you can set insecure_addon_compat to false in /etc/opscode/chef-server.rb. With this option set to false, Chef server writes all credentials to a single location. Note that this setting should only be applied after both the Chef server and its add-ons have been upgraded to compatible versions.

For additional information on this change, including a list of supported add-on versions, see Chef Server Credentials Management.

Standalone

This section describes the upgrade process for a standalone configuration. The upgrade process will require downtime equal to the amount of time it takes to stop the server, run dpkg or RPM Package Manager, and then upgrade the server.

To upgrade to Chef server 12 from a standalone Chef server, do the following:

  1. Run the following command to make sure all services are in a sane state.

    $ chef-server-ctl reconfigure
    
  2. Download the desired Chef server version from the Chef Server Downloads page.

  3. Stop the server:

    $ chef-server-ctl stop
    
  4. Run dpkg or RPM Package Manager.

    For dpkg:

    $ dpkg -i /path/to/chef-server-core-<version>.deb
    

    For RPM Package Manager:

    $ rpm -Uvh --nopostun /path/to/chef-server-core-<version>.rpm
    
  5. Upgrade the server with the following command:

    $ chef-server-ctl upgrade
    
  6. Start Chef server 12:

    $ chef-server-ctl start
    
  7. Upgrade the Chef server add-ons.

  8. After the upgrade process is complete and everything is tested and verified to be working properly, clean up the server by removing all of the old data:

    $ chef-server-ctl cleanup
    

High Availability

This section describes the upgrade process from a high availability configuration. The upgrade process will require downtime equal to the amount of time it takes to stop the server, run dpkg or RPM Package Manager, and then upgrade the server.

To upgrade to Chef server 12 from a high availability Chef server configuration, do the following:

  1. Run the following on all servers to make sure all services are in a sane state.

    $ chef-server-ctl reconfigure
    
  2. Download the desired Chef server version from the Chef Server Downloads page, then copy it to each server.

  3. Stop all of the front end servers:

    $ chef-server-ctl stop
    
  4. Identify the name of the original non-bootstrap backend server. This is the back end server that does not have :bootstrap => true in /etc/opscode/private-chef.rb.

  5. Stop Keepalived on the original non-bootstrap backend server. This will ensure that the bootstrap back end server is the active server. This action may trigger a failover.

    $ chef-server-ctl stop keepalived
    
  6. Run dpkg or RPM Package Manager on all servers.

    For dpkg:

    $ dpkg -i /path/to/chef-server-core-<version>.deb
    

    For RPM Package Manager:

    $ rpm -Uvh --nopostun /path/to/chef-server-core-<version>.rpm
    
  7. On the primary back end server, stop all services except Keepalived. With Chef server 12, the Keepalived service will not be stopped with the following command:

    $ chef-server-ctl stop
    

    If the upgrade process times out, re-run the command until it finishes successfully.

  8. Upgrade the back end primary server with the following command:

    $ chef-server-ctl upgrade
    

    If the upgrade process times out, re-run the command until it finishes successfully.

  9. Copy the entire /etc/opscode directory from the back end primary server to all front and back end nodes. For example, from each server run:

    $ scp -r <Bootstrap server IP>:/etc/opscode /etc
    

    or from the back end primary server:

    $ scp -r /etc/opscode <each servers IP>:/etc
    
  10. Upgrade the back end secondary server with the following command:

    $ chef-server-ctl upgrade
    

    In some instances, after the upgrade process is complete, it may be required to stop Keepalived on the back end secondary server, then restart Keepalived on the back end primary server, and then restart Keepalived on the back end secondary server.

  11. Upgrade all front end servers with the following commands:

    $ chef-server-ctl upgrade
    
  12. Run the following command on all front end servers and the primary back end server:

    $ chef-server-ctl start
    

    Note

    Do not run this command on the secondary back-end server!

  13. Upgrade the Chef server add-ons on each server.

  14. After the upgrade process is complete, the state of the system after the upgrade has been tested and verified, and everything looks satisfactory, remove old data, services, and configuration by running the following command on each server:

    $ chef-server-ctl cleanup
    

    Note

    The message [ERROR] opscode-chef-mover is not running is expected, does not indicate an actual error, and is safe to ignore.

Tiered

This section describes the upgrade process from a tiered server configuration. The upgrade process will require downtime equal to the amount of time it takes to stop the server, run dpkg or RPM Package Manager, and then upgrade the server.

Note

These instructions are primarily intended for existing users of the tier Chef server topology. For the latest information on high availability and how to set up a highly-available server cluster, see High Availability: Backend Cluster

To upgrade to Chef server 12 from a tiered Chef server configuration, do the following:

  1. Run the following on all servers to make sure all services are in a sane state.

    $ chef-server-ctl reconfigure
    
  2. Download the desired Chef server version from the Chef Server Downloads page, then copy it to each server.

  3. Stop all of the front end servers:

    $ chef-server-ctl stop
    
  4. Run dpkg or RPM Package Manager on all servers.

    For dpkg:

    $ dpkg -i /path/to/chef-server-core-<version>.deb
    

    For RPM Package Manager:

    $ rpm -Uvh --nopostun /path/to/chef-server-core-<version>.rpm
    
  5. Stop the back end server:

    $ chef-server-ctl stop
    
  6. Upgrade the back end server:

    $ chef-server-ctl upgrade
    
  7. Copy the entire /etc/opscode directory from the back end server to all front end servers:

    $ scp -r /etc/opscode <each server's IP>:/etc
    
  8. Upgrade each of the front end servers:

    $ chef-server-ctl upgrade
    
  9. Run the following command on both the front end, and back end servers:

    $ chef-server-ctl start
    
  10. Upgrade the Chef server add-ons on each server.

  11. After the upgrade process is complete, the state of the system after the upgrade has been tested and verified, and everything looks satisfactory, remove old data, services, and configuration by running the following command on each server:

    $ chef-server-ctl cleanup
    

From Enterprise Chef

There are two upgrade scenarios for upgrades from Enterprise Chef 11 to Chef server 12:

Before upgrading, please view the notes for more background on the upgrade process from Enterprise Chef 11 to Chef server 12.

Standalone

This section describes the upgrade process from a standalone Enterprise Chef 11 to Chef server 12. The upgrade process will require downtime equal to the amount of time it takes to stop the server, run dpkg or RPM Package Manager, and then upgrade the server. The final step will remove older components (like CouchDB) and will destroy the data after the upgrade process is complete.

To upgrade to Chef server 12 from a standalone Enterprise Chef server, do the following:

  1. Run the following command to make sure all services are in a sane state.

    $ private-chef-ctl reconfigure
    
  2. Stop the server:

    $ private-chef-ctl stop
    
  3. Run dpkg or RPM Package Manager.

    For dpkg:

    $ dpkg -i /path/to/chef-server-core-<version>.deb
    

    For RPM Package Manager:

    $ rpm -Uvh --nopostun /path/to/chef-server-core-<version>.rpm
    
  4. Upgrade the server with the following command:

    $ chef-server-ctl upgrade
    
  5. Start Chef server 12:

    $ chef-server-ctl start
    
  6. Upgrade the Chef server add-ons.

  7. After the upgrade process is complete and everything is tested and verified to be working properly, clean up the server by removing all of the old data:

    $ chef-server-ctl cleanup
    

High Availability

This section describes the upgrade process from a high availability Enterprise Chef 11 to Chef server 12. The upgrade process will require downtime equal to the amount of time it takes to stop the server, run dpkg or RPM Package Manager, and then upgrade the server. The final step will remove older components (like CouchDB) and will destroy the data after the upgrade process is complete.

To upgrade to Chef server 12 from a high availability Enterprise Chef server, do the following:

  1. Run the following on all servers to make sure all services are in a sane state.

    $ private-chef-ctl reconfigure
    
  2. Stop all of the front end servers:

    $ private-chef-ctl stop
    
  3. Identify the name of the original non-bootstrap backend server. This is the back end server that does not have :bootstrap => true in /etc/opscode/private-chef.rb.

  4. Stop Keepalived on the original non-bootstrap backend server. This will ensure that the bootstrap back end server is the active server. This action may trigger a failover.

    $ private-chef-ctl stop keepalived
    
  5. Run dpkg or RPM Package Manager on all servers.

    For dpkg:

    $ dpkg -i /path/to/chef-server-core-<version>.deb
    

    For RPM Package Manager:

    $ rpm -Uvh --nopostun /path/to/chef-server-core-<version>.rpm
    
  6. On the primary back end server, stop all services except Keepalived. With Chef server 12, the Keepalived service will not be stopped with the following command:

    $ chef-server-ctl stop
    

    If the upgrade process times out, re-run the command until it finishes successfully.

  7. Upgrade the back end primary server with the following command:

    $ chef-server-ctl upgrade
    

    If the upgrade process times out, re-run the command until it finishes successfully.

  8. Copy the entire /etc/opscode directory from the back end primary server to all front and back end nodes. For example, from each server run:

    $ scp -r <Bootstrap server IP>:/etc/opscode /etc
    

    or from the back end primary server:

    $ scp -r /etc/opscode <each server's IP>:/etc
    
  9. Upgrade the back end secondary server with the following command:

    $ chef-server-ctl upgrade
    

    In some instances, after the upgrade processes is complete, it may be required to stop Keepalived on the back end secondary server, then restart Keepalived on the back end primary server, and then restart Keepalived on the back end secondary server.

  10. Upgrade all front end servers with the following commands:

    $ chef-server-ctl upgrade
    
  11. Run the following command on all front end servers and the primary back end server:

    $ chef-server-ctl start
    

    Note

    Do not run this command on the secondary back-end server!

  12. Upgrade the Chef server add-ons on each server.

  13. After the upgrade process is complete, the state of the system after the upgrade has been tested and verified, and everything looks satisfactory, remove old data, services, and configuration by running the following command on each server:

    $ chef-server-ctl cleanup
    

    Note

    The message [ERROR] opscode-chef-mover is not running is expected, does not indicate an actual error, and is safe to ignore.

Upgrading Add-ons

This section details the process for upgrading additional features after the Chef server has been upgraded.

Use Downloads

The install subcommand downloads packages from https://packages.chef.io/ by default. For systems that are not behind a firewall (and have connectivity to https://packages.chef.io/), these packages can be installed as described below.

Feature Command
Chef Manage

Use Chef management console to manage data bags, attributes, run-lists, roles, environments, and cookbooks from a web user interface.

On the Chef server, run:

$ chef-server-ctl install chef-manage

then:

$ chef-server-ctl reconfigure

and then:

$ chef-manage-ctl reconfigure

Note

Starting with the Chef management console 2.3.0, the Chef MLSA must be accepted when reconfiguring the product. If the Chef MLSA has not already been accepted, the reconfigure process will prompt for a yes to accept it. Or run chef-manage-ctl reconfigure --accept-license to automatically accept the license.

Chef Push Jobs

Use Chef push jobs to run jobs—an action or a command to be executed—against nodes independently of a chef-client run.

On the Chef server, run:

$ chef-server-ctl install opscode-push-jobs-server

then:

$ chef-server-ctl reconfigure

and then:

$ opscode-push-jobs-server-ctl reconfigure
Reporting

Use Reporting to keep track of what happens during every chef-client runs across all of the infrastructure being managed by Chef. Run Reporting with Chef management console to view reports from a web user interface.

On the Chef server, run:

$ chef-server-ctl install opscode-reporting

then:

$ chef-server-ctl reconfigure

and then:

$ opscode-reporting-ctl reconfigure

Use Local Packages

The install subcommand downloads packages from https://packages.chef.io/ by default. For systems that are behind a firewall (and may not have connectivity to packages.chef.io), these packages can be downloaded from https://downloads.chef.io/chef-manage/, and then installed manually. First download the package that is appropriate for the platform, save it to a local path, and then run the install command using the --path option to specify the directory in which the package is located:

$ chef-server-ctl install PACKAGE_NAME --path /path/to/package/directory

For example:

$ chef-server-ctl install chef-manage --path /root/packages

The chef-server-ctl command will install the first chef-manage package found in the /root/packages directory.