chef-11-migration-draft.txt

Migrating from Chef 10 to Chef 11

Strategy

We stand up a new Chef 11 server. We then download all the artifacts and data from Chef 10 using knife download, and then upload them to the Chef 11 server using knife upload. Since the data is saved into a repo before uploading, we can verify the data and modify it as needed.


Considerations

Chef 10 uses CouchDB. Chef 11 uses PostgreSQL. There are also changes in the underlying data. However, the data from the API are communicated in JSON and knife knows how to handle the differences between Chef 10 and 11. `knife upload` and `knife download` in knife-essentials will take us most of the way there.

In Chef 10, the default admin identity is a client. In Chef 11, this is a user. In this walkthrough, we will assume you want to use the new admin key. To use the same admin key, you will need to convert the admin client JSON into the admin user JSON, then update your knife file.

In Chef 10, the name "chef-validator" is a magic name indicating the validator client. In Chef 11, there is no longer a magic name. Instead, a client has validation privileges if "validator" is set to true. Validators can only create new clients and modify themselves. They cannot modify another client or user. If you want to use the Chef 10 validation keys, then you must modify chef-validator.json file and add "validator": true into the JSON.


Preparations

You need the following:

(1) A working Chef 11 server (http://www.opscode.com/chef/install/)
(2) Prepare a Chef 10 and Chef 11 knife.rb
(3) A workstation set up to use knife
(4) The latest knife-essentials gem installed 


Preparing a Chef 10 and Chef 11 knife.rb

This walkthrough assumes you have a directory on your workstation set aside for knife work. The directory structure should look like this:


chef-10/
chef-11/
repo/


mkdir chef-10 chef-11 repo

Download the Chef-10 admin client key and put it into chef-10 as chef-10/admin.pem. 

Then, create chef-10/knife.rb with the following contents:


config_dir = File.dirname(__FILE__)
cookbook_dir = File.join(config_dir, "..", "repo", "cookbook")

log_level :info
log_location STDOUT
node_name 'admin'
client_key "#{config_dir}/admin.pem"
chef_server_url "http://chef-10.example.com:4000" # Supply your Chef 10 server url
cache_type 'BasicFile'
cache_options(:path => "#{config_dir}/checksums")

# This is probably not in your standard knife.rb. This ensures *all* versions
# of all your cookbooks gets migrated
versioned_cookbooks true


Download the Chef-11 admin.pem key into chef-11. Create a chef-11/knife.rb with the following content:

config_dir = File.dirname(__FILE__)
cookbook_dir = File.join(config_dir, "..", "repo", "cookbook")

log_level :info
log_location STDOUT
node_name 'admin'
client_key "#{config_dir}/admin.pem"
chef_server_url "https://chef-11.example.com" # Supply your Chef 11 server url
cache_type 'BasicFile'
cache_options(:path => "#{config_dir}/checksums")

# This is probably not in your standard knife.rb. This ensures *all* versions
# of all your cookbooks gets migrated
versioned_cookbooks true


Gems

Make sure you have the latest Chef 11 installed.

gem install chef


Migration

knife download / -c chef-10/knife.rb --chef-repo-path repo/ --repo-mode everything
rm repo/clients/admin.json repo/clients/chef-validator.json repo/clients/chef-webui.json
knife upload / -c chef-11/knife.rb --chef-repo-path repo/ --repo-mode everything


Alternative Migration: Using the old admin client keys

If you want to use the admin client private keys for the admin user, we can convert the admin client JSON file into the admin user JSON file. However, since we are using the admin key for the upload, we will also have to make changes to the credential file.


knife download / -c chef-10/knife.rb --chef-repo-path repo/ --repo-mode everything
rm repo/clients/chef-validator.json repo/clients/chef-webui.json
# Stash admin.json 
mv repo/clients/admin.json .
knife upload / -c chef-11/knife.rb --chef-repo-path repo/ --repo-mode everything

# Move admin.json into users and upload that. Make sure this happens after
# the main migration.
mv admin.json repo/users/
knife upload /users/admin.json -c chef-11/knife.rb --chef-repo-path repo/ --repo-mode everything
cp chef-10/admin.pem  chef-11/


If you change the admin key before uploading everything, Chef 11 will start using the new admin credentials and the rest of the migration will fail. To fix this, move the Chef 10 admin.pem file into the Chef 11 config directory and rerun the migration. `knife upload` uses a diff algorithm to determine what still needs to be uploaded and will only upload those artifacts. This allows the migration to complete using the new credentials.




Alternative Migration: Using the old validation keys


If you want to use the Chef 10 validation keys, then you will need to make sure the "validator": true is set for chef-validator.


knife download / -c chef-10/knife.rb --chef-repo-path repo/ --repo-mode everything


rm repo/clients/admin.json
rm repo/clients/chef-webui.json


# Edit the chef-validator.json file and add "validator": true
${EDITOR} repo/clients/chef-validator.json


knife upload / -c chef-11/knife.rb --chef-repo-path repo/ --repo-mode everything


# Edit admin.json and add "validator": json
${EDITOR} admin.json
mv admin.json repo/users/
knife upload /users/admin.json -c chef-11/knife.rb --chef-repo-path repo/ --repo-mode everything