By far the most popular solution for managing SmartOS configuration is Opscode Chef. It is a very powerful tool with a very active community of users. Here you'll learn about the various ways in which you can utilize Chef to manage your SmartOS nodes.
Before we dig into the various components and procedures, lets briefly consider the various combinations of options available to you. These methods can be mixed-and-matched to fit your specific situation. Please consider the following:
- . Options available include:
- The Official Omnibus installer: This method is still experimental for Solaris/SmartOS, but you should know it exists and may be a viable option shortly.
- The Joyent Ops Fat Client: Discussed below, this is our binary distribution of Chef to simplify and speed installation
- Install PKG-SRC, then install Ruby, then install the Chef Gem: This is a more complex solution which takes more time and consume far more disk, but if wish to leverage PKG-SRC in other ways, such as installing Nagios for example, it may be a viable option
- Hosted Chef & Knife: In this case you would orchestrate using the knife utility. This includes sending cookbooks to the Opscode Platform, bootstrapping new nodes with Knife Bootstrap Templates, and running the chef-client as a daemon which executes on a regular schedule finding and applying changes to your cookbooks.
- Chef Solo & Scripts: In this case you would create a custom bash bootstrap script, hosted on a web server accessible to the nodes, which would be responsible for installing Chef on the node, configuring it, and creating an SMF service to wrap chef-solo. The cookbooks would be stored on the web server as a tarball which would be downloaded on each chef-solo run which is initiated manually by restarting the Chef SMF service.
As I said, these options can be mixed and matched. For instance, if you opt to use Knife to bootstrap a node, you may use a bootstrap template which installs PKG-SRC and then Chef and its dependencies or you may opt for a simpler bootstrap template which uses the fat client. There are many possible combinations and it would be possible to explore all of them. Therefore, we will present some details here on some of the concepts and you can use them in whichever order is best for you.
Many of the tools and cookbooks referenced on this page can be found in the joyent/smartos_cookbooks Github repository.
For cookbooks and scripts to be used with SmartMachines/Zones, please refer to the joyent/smartmachine_cookbooks repo.
To speed up deployment and minimize dependencies on nodes, Joyent Operations produces a pre-compiled "fat client". Similar to the Opscode Omnibus Chef distribution, this compressed tarball is approx 15MB in size and consumes less than 50M when installed. It contains a full distribution of Ruby 1.9 plus all the gems required for Chef & Ohai.
Please note that our client distribution is not official or supported by either Opscode or Joyent.
To use, simply untar in / and add /opt/chef/bin to your path.
If you desire to install Chef a long with a full userland compliment, you can install PKG-SRC as described in the "Installing pkgin" procedure, then install Ruby using pkgin in ruby19, and then gem install chef.
For clarity, we'll assume this is your first time using Chef. Install Chef on your local system as appropriate; see Chef Wiki: Installation for help.
Start by going to Opscode.com and signing up for a free Hosted Chef account. Once you've logged into your account, navigate to the Organizations page and download the "Knife Config" (knife.rb). Create a /.chef/ directory and copy the knife.rb file you downloaded into it. When you created your account you should have received a client key and validation key; if you don't have them, generate a new validation key on your Organizations page and a generate a new client (user) key on your account change password page. When you have both keys, copy them into the /.chef/ directory.
Next we need to download some cookbooks. Get a head start by pulling the smartos_cookbooks repository from Github. The cookbook root is smartos_cookbooks/cookbooks. You'll want to then update your Knife configuration to use this directory as your cookbook path, by modifying the "cookbook_path" line in ~/.chef/knife.rb.
Now we're ready to start working with knife. You can upload the cookbooks you'd like to use.
Knife has the ability to "bootstrap" a node. This process consists of SSH'ing to the node and executing a bootstrap script which installs Chef as appropriate for the "distribution", then configures the client and starts it running. At the time of this writting there is no SmartOS bootstrap scripts provided by default with Chef, so we'll need to create our own. This is done by creating a .erb file for the "distribution" in ~/.chef/bootstrap/ and then specifying the distro name during boostrap with knife.
There are 2 Knife Bootstraps available for the SmartOS Global Zone, one using the flat client and another using PKG-SRC, which can be downloaded here: SmartOS GZ Knife Bootstraps on Github
Once the bootstrap template is in place, we can use knife bootstrap <ip_addr> to setup the node. We will pass 3 optional arguments: "-d smartos-fat" to specify the bootstrap template ("distribution"), "-r smartos" to specify which cookbooks should be in the initial cookbook run_list, and finally "-N hostname" to specify the name we wish to give to this node, which the smartos cookbook will also set as your hostname.
Here is example of what bootstrapping using the Fat Client looks like:
Chef Solo provides a means of executing cookbooks without the need for a Chef server. This is ideal in both very small (where its not worth the trouble) and very large (where a single server may be overwhelmed) deployments. The following is a description of the process of building a Chef Solo implementation similar to that used by Joyent Operations.
At a high level, the process will look like this:
- Fork the smartos_cookbooks Repository
- Modify the bootstrap script to match your web server IP's and URL scheme
- Create one or more Node Attribute files
- Review, modify, or add to the Cookbooks as you wish
- Copy the bootstrap script, fat client, cookbook tarball, node attributes to a web server
- Execute the bootstrap script on new clients
With Solo we'll server all content to our nodes using standard HTTP rather than a Chef server. Therefore, you'll require a directory on a web server somewhere which can serve your files, we'll assume http://meme.com/chef/. Remember that one of key advantages of using this method instead of Chef Server is because it is so easy to scale web servers, so please choose a capable machine for the task.
In your web directory you will host the following files:
All but the fatclient come directly from the smartos_cookbooks git repository. Clone the repository to your load system, then edit the Makefile SERVER_DEST variable to the host and path where your files will be scp'ed to. Once done, you can modify and commit changes to your local repo and send them all to the server by simply typing "make":
Finally, you should lock down your Chef files if they contain sensitive information. The best method is to add ACL's to a .htaccess file in the directory your using. Here is an example:
The bootstrap script is a BASH script which can be curl'ed and executed as a single line thus making node setup as easy and mistake proof as possible. This should not be confused with the earlier mentioned Knife Bootstrap scripts.