Upgrade to Chef Server 12

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 two upgrade scenarios for upgrades from earlier versions of Chef server 12 to a newer version of Chef server 12:

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 server, do the following:

  1. Verify that the make command is available on the Chef server server. If it is not available, install the make command.

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

    $ chef-server-ctl reconfigure

  3. Stop the server:

    $ chef-server-ctl stop

  4. Run dpkg or RPM Package Manager. For dpkg:

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

    where -D enables debugging and 10 creates output for each file that is processed during the upgrade. See the man pages for dpkg for more information about this option.

    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. 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

  8. Enable additional features of the Chef server! The packages may be downloaded directly as part of the installation process or they may be first downloaded to a local directory, and then installed.

    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.

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 server, do the following:

  1. Verify that the make command is available on the primary backend Chef server server. If it is not available, install the make command.

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

    $ chef-server-ctl reconfigure

  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 -D10 -i /path/to/chef-server-core-<version>.deb

    where -D enables debugging and 10 creates output for each file that is processed during the upgrade. See the man pages for dpkg for more information about this option.

    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 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.

  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. 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.

  14. Enable additional features of the Chef server! The packages may be downloaded directly as part of the installation process or they may be first downloaded to a local directory, and then installed.

    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.

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. Verify that the make command is available on the Enterprise Chef server. If it is not available, install the make command.

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

    $ private-chef-ctl reconfigure

  3. Stop the server:

    $ private-chef-ctl stop

  4. Run dpkg or RPM Package Manager. For dpkg:

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

    where -D enables debugging and 10 creates output for each file that is processed during the upgrade. See the man pages for dpkg for more information about this option.

    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. 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

  8. Enable additional features of the Chef server! The packages may be downloaded directly as part of the installation process or they may be first downloaded to a local directory, and then installed.

    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.

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. Verify that the make command is available on the primary backend Enterprise Chef server. If it is not available, install the make command.

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

    $ private-chef-ctl reconfigure

  3. Stop all of the front end servers:

    $ private-chef-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.

    $ private-chef-ctl stop keepalived

  6. Run dpkg or RPM Package Manager on all servers. For dpkg:

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

    where -D enables debugging and 10 creates output for each file that is processed during the upgrade. See the man pages for dpkg for more information about this option.

    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 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.

  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. 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.

  14. Enable additional features of the Chef server! The packages may be downloaded directly as part of the installation process or they may be first downloaded to a local directory, and then installed.

    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.

From Open Source Chef

This section describes the upgrade process from a standalone configuration of Open Source Chef 11.1.0 (or higher) to a standalone configuration of 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.

Please view the notes for more background on the upgrade process from Open Source Chef 11 to Chef server 12.

To upgrade to Chef server 12 from the Open Source Chef server, do the following:

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

    $ chef-server-ctl reconfigure

  2. Stop the Open Source Chef server:

    $ chef-server-ctl stop

  3. Run dpkg or RPM Package Manager on the server to install Chef server 12. For dpkg:

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

    where -D enables debugging and 10 creates output for each file that is processed during the upgrade. See the man pages for dpkg for more information about this option.

    For RPM Package Manager:

    $ rpm -Uvh /path/to/chef-server-core-<version>.rpm

    Chef server 12 is installed to /opt/opscode. (The existing Open Source Chef remains at /opt/chef-server.) From this point, the chef-server-ctl commands are running against the /opt/opscode location.

  4. Upgrade the server with the following command:

    $ chef-server-ctl upgrade

    The upgrade process will automatically detect the presence of Open Source Chef 11, and will step through the migration process, prompting for organization name details along the way.

    The migration process will first download the existing data from the Open Source Chef server, transform that data into the format required for Chef server 12, and then upload that data to the server.

  5. Before data can be uploaded, an organization must be created. When prompted, enter the organization name, and then a full organization name.

    The name must begin with a lower-case letter or digit, may only contain lower-case letters, digits, hyphens, and underscores, and must be between 1 and 255 characters. For example: chef.

    The full name must begin with a non-white space character and must be between 1 and 1023 characters. For example: "Chef Software, Inc.".

    Note

    The upgrade process will automatically assign the organization name to the default_orgname setting in the chef-server.rb file. This setting ensures the new organization name is available for Chef server API requests, such as those made by the chef-client and by knife.

    Warning

    If you receive a missing read permission error when running the knife user list subcommand after the upgrade process is finished, you will need to update the value for the chef_server_url setting in the knife.rb file. The default value for that setting is:

    chef_server_url 'https://CHEF_SERVER_NAME:443/'

    and should be updated to add organizations/ORG_NAME:

    chef_server_url 'https://CHEF_SERVER_NAME:443/organizations/ORG_NAME'

  6. The Chef server is automatically restarted. A prompt is displayed that contains details about how to remove any temporary data that was created during the upgrade process.

  7. Enable additional features of the Chef server! The packages may be downloaded directly as part of the installation process or they may be first downloaded to a local directory, and then installed.

    Update the Chef server URL

    The URL for the Chef server needs to be updated on all nodes and workstations. In the client.rb file on each node and in the knife.rb file on each workstation, update the following setting:

    chef_server_url "https://url.for.server"

    Note

    Any node that is bootstrapped from a workstation with the updated URL will automatically be assigned the new URL for the Chef server. Only existing nodes prior to the upgrade require the URL update.

    Note

    Any chef-client or knife user that tries to access the Chef server after the upgrade will be able to do so as long as the default_orgname is set and is part of the default organization on the upgraded Chef server.

    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.

Chef Manage

Chef management console can be upgraded as part of a standalone or high availability configuration:

  1. After upgrading the Chef server, upgrade each of the front end servers. For Red Hat and CentOS 6:

    $ chef-server-ctl install opscode-manage

    For Ubuntu, for the Chef management console 1.x to 2.x:

    $ apt-get install chef-manage

  2. Reconfigure each of the front end servers:

    $ chef-manage-ctl reconfigure

Chef Push Jobs

Chef push jobs can be upgraded as part of a standalone or high availability configuration:

  1. After upgrading the Chef server, run the following command on all front and back end servers:

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

  2. TCP protocol ports 10000-10003 must be open. This allows the Chef push jobs clients to communicate with the Chef push jobs server. In a configuration with both front and back ends, these ports only need to be open on the back end servers. The Chef push jobs server waits for connections from the Chef push jobs client (and never makes a connection to a Chef push jobs client).

  3. Reconfigure the Chef push jobs servers:

    $ opscode-push-jobs-server-ctl reconfigure

  4. Run the following command on each of the back end servers:

    $ chef-server-ctl reconfigure

    This ensures that the Keepalived scripts are regenerated so they are aware of Chef push jobs.

  5. Restart the Chef push jobs components:

    $ chef-server-ctl restart opscode-pushy-server

  6. Verify the installation:

    $ opscode-push-jobs-server-ctl test

  7. Install the Chef push jobs client on all nodes using the push-jobs cookbook, as needed.

© Chef Software, Inc.
Licensed under the Creative Commons Attribution 3.0 Unported License.
The Chef™ Mark and Chef Logo are either registered trademarks/service marks or trademarks/servicemarks of Chef, in the United States and other countries and are used with Chef Inc's permission.
We are not affiliated with, endorsed or sponsored by Chef Inc.
https://docs-archive.chef.io/release/server_12-8/upgrade_server.html