Downloading and integrating cookbooks as vendor branches into your Git repository

The Chef community offers a wide variety of ready-made cookbooks for many major software packages. They're a great starting point for your own infrastructure. However, usually you need to modify these cookbooks to suit your needs. Modifying your local copy of a community cookbook leaves you with the dilemma of not being able to update to the latest version of the community cookbook without losing your local changes.

Getting ready

You'll need to make sure that your local Git repository is clean and does not have any uncommitted changes:

mma@laptop:~/chef-repo $ git status

# On branch master
nothing to commit (working directory clean)

How to do it...

Carry out the following given steps:

1. Go to https://supermarket.chef.io/cookbooks and search for the cookbook you need. In our example, we will use the mysql cookbook, which you can find by typing mysql in the search box and hitting enter. All we need is to note down the exact name of the cookbook; in this case, it's simply mysql.
   
2. Use knife to pull down the cookbook and integrate it with your local repository:

   mma@laptop:~/chef-repo $ knife cookbook site install mysql
   

   Installing mysql to /Users/mma/work/chef-repo/cookbooks
   …TRUNCATED OUTPUT…

   Verify the downloaded cookbooks:

   mma@laptop:~/chef-repo $ cd cookbooks
   mma@laptop:~/chef-repo/cookbooks $ ls -l
   

   total 8
   -rw-r--r--   1 mma  staff  3064 27 Sep  2013 README.md
   
   
   drwxr-xr-x+ 10 mma  staff   340  7 Dez 20:43 mysql
   drwxr-xr-x+ 12 mma  staff   408  7 Dez 20:43 yum
   drwxr-xr-x+  9 mma  staff   306  7 Dez 20:43 yum-mysql-community

   Validate the Git status:

   mma@laptop:~/chef-repo/cookbooks $ git status
   

   # On branch master
   # Your branch is ahead of 'origin/master' by 3 commits.
   #
   nothing to commit (working directory clean)

3. You might have noticed that your local branch received three commits. Let's take a look at those:

   mma@laptop:~/chef-repo/cookbooks $ git log
   

   commit 271d3de3b95bdc32d68133cdc91cb04e09625f59
   Author: Matthias Marschall <[e-mail]>
   Date:   Sun Dec 7 20:43:50 2014 +0100
   
       Import yum version 3.5.1
   
   commit cc72319ca7989df26e0ba7c3a76f78f6a7a7a4e2
   Author: Matthias Marschall <[e-mail]>
   Date:   Sun Dec 7 20:43:44 2014 +0100
   
       Import yum-mysql-community version 0.1.10
   
   commit 30984edb00c12177e25558bdfcd519da508b3ac5
   Author: Matthias Marschall <[e-mail]>
   Date:   Sun Dec 7 20:43:38 2014 +0100
   
       Import mysql version 5.6.1

The knife command successfully downloaded and imported the mysql cookbook as well as its dependencies.

How it works...

Knife executes a set of commands to download the desired cookbook and to integrate it with your local repository.

Let's take a look at the output of the knife cookbook site install command again and go through it step-by-step:

1. First, the command makes sure that you're on the master branch of your repository:

   Checking out the master branch.
   

2. The next step is to create a new vendor branch for the mysql cookbook, if none exists so far:

   Creating pristine copy branch chef-vendor-mysql.
   

3. Then, knife downloads the tarball, removes any older version, uncompresses the new tarball, and removes it after successfully extracting its contents into a new cookbook directory:

   Downloading mysql from the cookbooks site at version 5.6.1 to /Users/mma/work/chef-repo/cookbooks/mysql.tar.gz
   Cookbook saved: /Users/mma/work/chef-repo/cookbooks/mysql.tar.gz
   Removing pre-existing version.
   Uncompressing mysql version 5.6.1.
   Removing downloaded tarball

4. Now, it's time to commit the newly extracted files to the vendor branch:

   1 files updated, committing changes

5. Finally, Git tags the branch with the current version of the cookbook:

   Creating tag cookbook-site-imported-mysql-5.6.1

The knife cookbook site install command executes all the previously mentioned steps for all the cookbooks the desired cookbook depends on, by default.

Eventually, you end up with a separate branch, the so-called vendor branch, for every downloaded cookbook integrated into your master branch and nicely tagged as shown:

mma@laptop:~/chef-repo$ git branch -a

  chef-vendor-iptables
  chef-vendor-mysql
* master
  remotes/origin/master

This approach enables you to change whatever you like in your master branch and still pull down newer versions of the community cookbook. Git will automatically merge both versions or ask you to remove conflicts manually; these are standard Git procedures.

There's more...

If you want to integrate the desired cookbook into another branch, use the --branch BRANCH_NAME parameter.

mma@laptop:~/chef-repo [experimental] $ knife cookbook site install mysql –-branch experimental

Installing mysql to /Users/mma/work/chef-repo/cookbooks
Checking out the experimental branch.
Pristine copy branch (chef-vendor-mysql) exists, switching to it.
Downloading mysql from the cookbooks site at version 5.6.1 to /Users/mma/work/chef-repo/cookbooks/mysql.tar.gz
Cookbook saved: /Users/mma/work/chef-repo/cookbooks/mysql.tar.gz
Removing pre-existing version.
Uncompressing mysql version 5.6.1.
removing downloaded tarball
No changes made to mysql
Checking out the experimental branch.
…TRUNCATED OUTPUT…

As you can see, instead of checking out the master branch, the knife cookbook site install command uses the experimental branch now.

You can use the -D switch when running the command in order to avoid downloading all the cookbooks that your desired cookbook depends on.

mma@laptop:~/chef-repo $ knife cookbook site install mysql -D

Installing mysql to /Users/mma/work/chef-repo/cookbooks
Checking out the master branch.
Pristine copy branch (chef-vendor-mysql) exists, switching to it.
Downloading mysql from the cookbooks site at version 5.6.1 to /Users/mma/work/chef-repo/cookbooks/mysql.tar.gz
Cookbook saved: /Users/mma/work/chef-repo/cookbooks/mysql.tar.gz
Removing pre-existing version.
Uncompressing mysql version 5.6.1.
removing downloaded tarball
No changes made to mysql
Checking out the master branch.

You can see that the command stopped after dealing with the mysql cookbook. It has not yet gotten the other cookbooks.

See also

• You can use Berkshelf to manage cookbooks and their dependencies for you, which makes the preceding approach obsolete. See the Managing cookbook dependencies with Berkshelf recipe in this chapter.