To better understand how a server is configured using a ServerTemplate that uses Chef cookbooks and recipes.
This tutorial is designed for users who are new to using Chef cookbooks and recipes to launch servers. Although a basic understanding of Chef will make it easier for you to follow this tutorial, prior knowledge or experience with Chef is not required. If you are new to Chef, it's recommended that you first familiarize yourself with basic Chef terms and concepts. See Chef Basics.
In this tutorial you will perform the following tasks:
- Import a Chef-based ServerTemplate from the MultiCloud Marketplace
- Launch a server
- SSH into the server
Upon completion of this tutorial you will have a basic understanding of how Chef cookbooks and recipes are used in the RightScale platform to launch and configure servers using ServerTemplates.
Create a Deployment
Create a new deployment that you will use to launch a server later in this tutorial. (e.g. QuickStart Chef Tutorial). See Create a New Deployment.
Import a ServerTemplate
- Go to the MultiCloudMarketplace (Design > MultiCloud Marketplace > ServerTemplates) and import the latest revision of the following ServerTemplate:
- When you import a new ServerTemplate from the MultiCloud Markeplace that references repositories, RightScale will immediately try and retrieve the contents of the referenced repositories from the Source Control Management (SCM) system where they're currently being stored (e.g. GitHub) and save a copy of the contents into RightScale's repository caching service called Repose. Although your code will be hosted in repository systems like GitHub, it's important for the RightScale system to not be reliant upon third party SCMs being online 24x7. To prevent any external dependencies, RightScale stores a cached version of all referenced repositories in our Repose mirrors. When a server is launched or a script is executed on a running server, the cookbooks and recipes are actually retrieved from Repose and stored locally on the instance.
- Click on the ServerTemplate's Scripts tab. You will see a list of the ServerTemplate's scripts organized into three different sections depending on when the script should be executed.
Boot Sequence - Scripts that are automatically executed in sequential at boot time when a new server is launched or rebooted.
Operational Scripts - Scripts that are designed to be executed manually to perform various operational tasks for lifecycle management scenarios, such as creating a backup, start/stop an application, etc.
Decommission Sequence - Scripts that are automatically executed in sequential at decommission time when a server is terminated.
- A ServerTemplate can contain scripts that are bash RightScripts or Chef recipes. In this particular example, all of the scripts are Chef recipes. A ServerTemplate can only use scripts from its attached cookbooks. Later, when you develop and customize your own ServerTemplates, you will need to attach cookbooks to a ServerTemplate before you can add any of its recipes to a ServerTemplate.
View a Cookbook
If you want to learn more about the scripts that are used by a ServerTemplate, click on the appropriate cookbook link to view more detailed information.
- Click on the 'app' cookbook in the right-hand pane.
- Under the Recipes section you will find a list of cookbook's recipes and their descriptions.
- Under the Info section you can view the cookbook's ReadMe file. To see the actual code of a recipe, click the Download button to download a tarball (*.tar) that includes all of a cookbook's contents.
- Unpack the tarball to take a closer look at a cookbook's recipes that are used by this particular ServerTemplate. In this particular cookbook, the recipes are located in the 'recipes' directory. In each cookbook, you will find sub-directories for the various types of Chef resources (attributes, definition, recipes, resources, etc.). One of the most important pieces of a cookbook is its metadata, which defines any cookbook dependencies as well as descriptions for recipes and inputs.
- Notice that there are two metadata files in thecookbook. If you develop your own Chef cookbooks and recipes, you will need to manually edit the metadata.rb file and then generate the matching metadata.json file. You should never edit the metadata.json file directly. You must remember to regenerate the metadata.json file each time you update the metadata.rb file.
metadata.json: The file that RightScale uses in order to properly display a script's information. (DO NOT EDIT)
metadata.rb: The human-readable version of the metadata.json file. (EDIT)
- Click on the metadata.rb file.
Notice that the following information is declared in the metadata.
Cookbook Dependencies: Any cookbook dependencies are declared in the metadata. One of the useful features of Chef is the ability for one Chef resource to leverage other Chef resources. For example, if a Chef recipe located in the current cookbook uses a Chef resource that's located in a different cookbook, you must explicitly list the other cookbook in the metadata. This way, any additionally required cookbooks will also be retrieved from Repose. If you do not declare a cookbook dependency, the script (that uses the other resource) will fail because the code for the referenced resource will not exist on the local instance.
Chef Recipes: The name and description for each recipe.
Chef Attributes: Chef attributes are treated as user-definable inputs. At a minimum, you will need to provide the name and description for the attribute. The descriptions will appear as tooltips under the Inputs tab of the dashboard. You can also define a default value as well as whether a value for the attribute is required or optional for script execution.
Inspect the Inputs
Now that you've seen the Chef code that will be executed on the server, let's view some of the scripts' inputs.
- Click on the ServerTemplate's Inputs tab.
- Notice how the content of the cookbook's metadata file is used to display the related input information in the dashboard. In the example screenshot below, you'll see how the information for the "Database Admin Password" input in the 'db' cookbook's metadata.rb file is displayed in the dashboard under the Inputs tab. Later, if you choose to develop your own Chef cookbooks and recipes, it's very important that you have a properly formatted metadata.rb file so that all of the related cookbook information will be rendered correctly in the dashboard.
(Click on the image to enlarge.)
Create and Launch a Server
You are now ready to create and launch a server.
- While viewing the ServerTemplate, click the Add Server button to add a server into your deployment. (e.g. Beginner Chef Tutorial) Select or create any required cloud resources (e.g. SSH Key, Security Group, etc.) Name the server accordingly. (e.g. My Beginner)
See Add a Server to a Deployment if you need help adding a server to a deployment.
- Launch the server. (All of the required inputs for any required boot scripts should already be predefined at the ServerTemplate level. Any "missing" inputs on the launch screen are for optional inputs and are not required for launch.)
- Once the server becomes operational, go to the server's Info tab and click its Public DNS name link, or copy and paste its public IP address in a browser window to view the Apache test page.
Check the Audit Entries
Now take a look at the audit entries to better understand how the Chef recipes are executed on the server.
- Once the server becomes operational, go to the server's Audit Entries tab and click the one that describes the execution of the boot scripts.
- Expand the different sections to view more detailed information.
Configuring software repositories: Describes which software repositories were used based on the specified repository dates.
Preparing boot bundle: RightScale inspects the metadata.json files of each cookbook to determine which cookbooks need to be retrieved and sends the results to the instance.
Retrieving cookbooks: The RightLink agent on the instance retrieves the contents of all the cookbooks that are required to complete the current Chef run list from Repose and copies them locally on the instance. A single Chef run list is created to complete the operation. In this case, it's creating a single Chef run list that consists of all the ServerTemplate's boot scripts. However, a single Chef run list would also be created if you were to run a single operational script. For this particular example, all of the boot scripts are Chef recipes. Although a single Chef run is created, the scripts are executed in sequential order even if the boot script list were to contain a mix of Chef recipes and RightScripts. (Later in this tutorial you will navigate to where the cookbooks are locally stored on the instance.) Note: You can still use RightScripts in a ServerTemplate that uses Chef recipes.
Converging: During the converge phase, RightLink executes the Chef run list on the instance. Notice how the execution of each script is clearly grouped by recipe name, which makes it easier to find the related output of a script for troubleshooting purposes.
SSH into the Server
- Click the server's SSH Console button to SSH into the server.
- Go to the following location to view where Chef cookbooks are locally stored on the instance.
- Since this particular ServerTemplate only uses Chef recipes, go into the 'cookbooks' directory. (Note: If the ServerTemplate contained any RightScripts, a copy of the script would be saved in the 'right_scripts' directory.) A directory will be created for each repository that is used by the current Chef run list. The SHA that's used to identify the cookbook repository in Repose is used to name the repository's directory. The actual SHA that is used refers to a specific commit for the referenced repository. (Note: The repositories are listed numerically; the order does not reflect the defined repository hierarchy defined by the RepoPath.)
- Let's take a closer look at one of the cookbook repositories. (Tip: Enter the first few numbers of a repository and then click the Tab button to autofill the rest of the name.) You will typically be able to use the underlying cookbooks to determine which repository you're looking at. In the example below, we are looking at the 'rightscale/cookbook' repository. You'll notice that only four cookbooks were loaded onto the instance even though the repository itself contains many other cookbooks. The reason why the local copy of the repository on the server only has those four cookbooks is because RightScale will only retrieve the cookbooks (from Repose) that are required to complete the current Chef run list.
- Now that you've seen what happens during the boot phase when a server is launched for the first time, what happens when you run an operational script? Go to the server's Scripts tab and run the 'web_apache::do_start' operational script.
- Go to the server's Audit Entries tab. Once the script is complete, click on its audit entry to view more details. Under the "Retrieving cookbooks" section, expand the details of the audit entry.
Each time that a script is executed, a Chef run list is created and the cookbooks that are required to successfully execute the script are retrieved from Repose. If the cookbook already exists, its contents will be overwritten. If a cookbook does not exist, a new directory is created and the cookbook's contents are downloaded into it. The key point is that cookbooks are always retrieved from Repose each time a script is executed. The contents of the cookbooks are stored locally on the instance and then executed. (The only exception to this rule is if you are using the 'rs_agent_dev:download_cookbooks_once=true' tag. See the Chef Developer Workflows for details.)
Post Tutorial Steps
Terminate the Server
Congratulations! You have successfully completed this tutorial. Although you only launched a simple server using a ServerTemplate that uses Chef cookbooks and recipes, hopefully you have a better understanding of the underlying processes and the relationship between all of the different components.