NOTE: When migrating to v5 we recommend that you boot a new environment and test your application there first. We do not recommend an in-place upgrade from v1/v2/v4 to v5.
Chef on v5 differs from earlier stacks, in that there are no longer two distinct main and custom runs, just a single combined run. This combined run is however still initiated via the Dashboard Apply button or the ey recipes apply
command. For full details on Chef on v5 please see this article.
Custom chef recipes themselves function differently on v5. All custom chef recipes that work on v2 and v4 need to be updated.
Downloading Existing Recipes
If you do not already have an up to date copy of the recipes in use on your v4 environment, then these can be downloaded via the CLI, using the the ey-core gem:
If not already installed:
gem install ey-core
then:
ey-core recipes download --environment <nameofenvironment>
EY Authored Recipes
If you previously made use of Engine Yard authored custom Chef recipes on v4, then please firstly check the v5 custom cookbooks repository for the equivalent recipe. Most recipes will assume you have the base structure required, that being the ey-custom
cookbook, which is invoked as a part of the combined Chef run.
To do this complete the following:
-
Create the
cookbooks/
directory. You can create this directory anywhere on your local system, preferably within a directory you will associated with the specific environment(s) the recipes will be run on. Some customers may then commit this directory to a repository for easy management. Other customers choose to add thecookbooks/
directory to the root of your application, though this should be noted that doing so does not automate the running of the cookbooks in any way, it is simply for ease of storage. Optional - If you have an existingcookbooks/
directory in your working directory, move it to a temporary directory first.cd /path/to/working_dir (mv -i cookbooks cookbooks.v4) mkdir cookbooks
-
Create the required cookbook files:
mkdir -p cookbooks/ey-custom/recipes touch cookbooks/ey-custom/recipe/after-main.rb touch cookbooks/ey-custom/metadata.rb
ey-custom/recipes/after-main.rb
is now the entry-point of custom chef recipes. You do not need themain/
directory that you used on v4. Edit the recipe's metadata file as below:# cookbooks/ey-custom/metadata.rb name 'ey-custom'
-
For each custom recipe you wish to utilise, follow that specific recipe's readme, but fundamentally you will need to include the recipe in ey-custom's
after-main.rb
and depend on it in themetadata.rb
. Most recipes contain a copy ofey-custom
in their cookbooks directory, which can be copied over to avoid steps 1-2 if this is the first custom recipe being utilised, or the contents of which should be merged with the existing ey-custom recipe if this is an additional recipe.For example, to use the delayed_job4 recipe that EY maintains, you could copy both
ey-custom
andcustom-delayed_job4
from https://github.com/engineyard/ey-cookbooks-stable-v5/tree/next-release/custom-cookbooks/delayed_job4/cookbooks to yourcookbooks/
directory if you did not already have aney-custom
cookbook, or if you did, just copy thecustom-delayed_job4
directory and then:On
cookbooks/ey-custom/recipes/after-main.rb
, addinclude_recipe 'custom-delayed_job4'
On
cookbooks/ey-custom/metadata.rb
, adddepends 'custom-delayed_job4'
If you have no self-authored recipes then skip ahead to Applying Recipes.
Customer Authored Recipes
If you want to convert your existing v4 custom chef recipes to v5 because we have not converted them yet or they are recipes you wrote yourself, follow steps 1 & 2 of the above EY Authored Recipes section in order to backup the existing recipes and create the base structure, then complete the following steps:
-
Copy the recipe from
cookbooks.v4/
tocookbooks/
. If you follow our instructions above, you will start with an emptycookbooks/
.cd /path/to/working_dir cp -pr cookbooks.v4/RECIPE_NAME cookbooks/
-
Add
cookbooks/RECIPE_NAME/metadata.rb
.name 'RECIPE_NAME'
-
Add
include_recipe
anddepends
to the ey-custom recipe. You always need to add these 2 for any recipe that you want to use.On
cookbooks/ey-custom/recipes/after-main.rb
, addinclude_recipe 'RECIPE_NAME'
On
cookbooks/ey-custom/metadata.rb
, adddepends 'RECIPE_NAME'
-
Replace
node['instance_role']
,node['name']
, and similar code and add['dna']
. We moved some data ondna.json
from the "root" todna{}
. Check out/etc/chef/dna.json
on a v5 instance to see the new format.Run the code below to view the code that needs to be changed
cd /path/to/cookbooks.v4/ # or cookbooks/ grep -r "node\[\(:\|'\|\"\)\(applications\|engineyard\|environment\|instance_role\|members\|name\|users\|utility_instances\)" .
# node['instance_role'] on v4 node['dna']['instance_role'] # node ['name'] on v4 node['dna']['name']
Data specified on the
attributes
directory will not change. If you havedefault['redis'] = {'version' => "3.2.1"}
you would still use
node['redis']['version']
-
Change the package versions. The v5 stack has new packages. Update your recipes to use these new versions. Refer to the table of common packages below.
Package Package name V5 Version Imagemagick media-gfx/imagemagick 6.9.4.1 Java dev-java/icedtea-bin 3.3.0 (JDK 8)
7.2.6.8 (JDK 7)Memcached net-misc/memcached 1.4.25 Redis dev-db/redis 3.2.0 wkhtmltopdf media-gfx/wkhtmltopdf-bin 0.12.2.1-r1 -
(Optional) Use a string instead of symbol when accessing node attributes. The code below are similar. Either can be used. Foodcritic (lint tool for Chef) suggests using a string.
# use this node['dna']['instance_role'] # don't use this node[:dna][:instance_role]
Applying Recipes
Once the recipes are ready upload them to environment via the CLI, using the ey-core gem:
If not already installed:
gem install ey-core
then:
ey-core recipes upload --environment <nameofenvironment>
then run Chef via the dashboard Apply button or via the CLI:
ey-core recipes apply --environment <nameofenvironment>
Comments
Article is closed for comments.