SA 10.1 Chef ManagementUser Guide

HP Server Automation
Ultimate Edition
Software Version: 10.20
User Guide: Chef Cookbook Management
Document Release Date: December 12, 2014
Software Release Date: December 12, 2014
Legal Notices
Warranty
The only warranties for HP products and services are set forth in the express warranty statements
accompanying such products and services. Nothing herein should be construed as constituting an
additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.
The information contained herein is subject to change without notice.
Restricted Rights Legend
Confidential computer software. Valid license from HP required for possession, use or copying. Consistent
with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and
Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard
commercial license.
Copyright Notices
© Copyright 2001-2014 Hewlett-Packard Development Company, L.P.
Trademark Notices
Adobe® is a trademark of Adobe Systems Incorporated.
Intel® and Itanium® are trademarks of Intel Corporation in the U.S. and other countries.
Microsoft®, Windows®‚ Windows® XP are U.S. registered trademarks of Microsoft Corporation.
Oracle and Java are registered trademarks of Oracle and/or its affiliates.
UNIX® is a registered trademark of The Open Group.
Support
Visit the HP Software Support Online website at:
http://www.hp.com/go/hpsoftwaresupport
This website provides contact information and details about the products, services, and support that HP
Software offers.
HP Software online support provides customer self-solve capabilities. It provides a fast and efficient way
to access interactive technical support tools needed to manage your business. As a valued support
customer, you can benefit by using the support website to:
2
•
Search for knowledge documents of interest
•
Submit and track support cases and enhancement requests
•
Download software patches
•
Manage support contracts
•
Look up HP support contacts
•
Review information about available services
•
Enter into discussions with other software customers
•
Research and register for software training
Chapter
Most of the support areas require that you register as an HP Passport user and sign in. Many also require a
support contract. To register for an HP Passport ID, go to:
http://h20229.www2.hp.com/passport-registration.html
To find more information about access levels, go to:
http://h20230.www2.hp.com/new_access_levels.jsp
Support Matrices
For complete support and compatibility information, see the support matrix for the relevant product
release. All support matrices and product manuals are available here on the HP Software Support Online
website:
http://h20230.www2.hp.com/sc/support_matrices.jsp
You can also download the HP Server Automation Support and Compatibility Matrix for this release from
the HP Software Support Online Product Manuals website:
http://h20230.www2.hp.com/selfsolve/manuals
Documentation Updates
All the latest Server Automation product documentation for this release is available from the SA
Documentation Library:
http://support.openview.hp.com/selfsolve/document/KM00417675/binary/
SA_10_docLibrary.html
Use the SA Documentation Library to access any of the guides, release notes, support matrices, and white
papers relevant to this release or to download the full documentation set as a bundle. The SA
Documentation Library is updated in each release and whenever the release notes are updated or a new
white paper is introduced.
How to Find Information Resources
You can access the information resources for Server Automation using any of the following methods:
Method 1: Access the latest individual documents by title and version with the new SA Documentation
Library
Method 2: Use the complete documentation set in a local directory with All Manuals Downloads
Method 3: Search for any HP product document in any supported release on the HP Software
Documentation Portal
To access individual documents:
1
Go to the SA 10.x Documentation Library:
http://support.openview.hp.com/selfsolve/document/KM00417675/binary/
SA_10_docLibrary.html
2
Log in using your HP Passport credentials.
3
Locate the document title and version that you want, and then click go.
3
To use the complete documentation set in a local directory:
1
To download the complete documentation set to a local directory:
a
Go to the SA Documentation Library:
http://support.openview.hp.com/selfsolve/document/KM00417675/
binary/SA_10_docLibrary.html
b
Log in using your HP Passport credentials.
c
Locate the All Manuals Download title for the SA 10.1 version.
d
Click the go link to download the ZIP file to a local directory.
e
Unzip the file.
2
To locate a document in the local directory, use the Documentation Catalog (docCatalog.html),
which provides an indexed portal to the downloaded documents in your local directory.
3
To search for a keyword across all documents in the documentation set:
a
Open any PDF document in the local directory.
b
Select Edit > Advanced Search (or Shift+Ctrl_F).
c
Select the All PDF Documents option and browse for the local directory.
d
Enter your keyword and click Search.
To find additional documents on the HP Software Documentation Portal:
Go to the HP Software Documentation Portal:
http://h20230.www2.hp.com/selfsolve/manuals
This site requires that you register for an HP Passport and sign in. To register for an HP Passport ID, click
the New users - please register link on the HP Passport login page.
You will also receive updated or new editions if you subscribe to the appropriate product support service.
Contact your HP sales representative for details. See Documentation Change Notes for a list of any
revisions.
Product Editions
There are two editions of Server Automation:
4
•
Server Automation (SA) is the Ultimate Edition of Server Automation. For information about Server
Automation, see the SA Release Notes and the SA User Guide: Server Automation.
•
Server Automation Virtual Appliance (SAVA) is the Premium Edition of Server Automation. For more
information about what SAVA includes, see the SAVA Release Notes and the SAVA at a Glance Guide.
Chapter
Documentation Change Notes
The following table indicates changes made to this document since the last released edition.
Date
Changes
May 2014
Pre-released draft for bootcamp
July 2014
Original release of this document with SA 10.1.
5
6
Chapter
Contents
1 Getting Started with Chef Cookbooks in SA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Overview of Chef Cookbooks in SA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Setting up your SA Environment to Handle Chef Cookbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Required User Group Permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Enabling an SA Server to Run Chef Recipes by Installing the chef-solo Policy. . . . . . . . . . . . . . . . . . . . . . . . . 9
Attach the chef-solo Policy to the Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Remediate Servers to Deploy the chef-solo Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Chef-supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Downloading Cookbooks from the Chef Community. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
chef-solo Bundle Configuration in SA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
chef-solo configuration file—solo.rb. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Unix solo.rb Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Windows solo.rb Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Package Repository for Chef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Specifying the Package Repository for Chef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Localization Support for Chef Recipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2 Chef Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Using Chef Cookbooks and Recipes in SA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Uploading Chef Cookbooks to SA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Importing a Chef Cookbook from the SA Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Uploading Chef Cookbooks from the SA Command Line Interface (CLI) . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Cookbook Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Managing Chef Cookbooks in SA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Accessing Chef Cookbooks from the SA Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Viewing Cookbook Details in SA Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Editing Chef Cookbook Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Running Chef Recipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Customizing a Run Chef Recipe Job. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Retain Job Output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Log Files on the SA Managed Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Job Results Fields Examples 29
Job Results Fields Defined 30
Blocking a Run Chef Recipe Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
A Chef Cookbook Management Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Permissions for Running a Chef Recipe from a Cookbook with No Dependencies . . . . . . . . . . . . . . . . . . . . 31
Permission Management for Cookbooks with Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Multi-tenancy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
7
B Chef Cookbook Page Help1
1 Getting Started with Chef Cookbooks in SA
Overview of Chef Cookbooks in SA
You can now use SA to view and manage Chef Cookbooks and run Chef Recipes. Server Automation 10.1
supports native Chef Cookbooks in the following ways:
•
Uploading Chef Cookbooks to SA
•
Managing Chef Cookbooks from SA
•
Running Chef Recipes from SA
This document describes how to perform these Chef-related activities in SA.
See the Opscode documentation for explanations about Chef content and framework:
http://docs.opscode.com/
Setting up your SA Environment to Handle Chef Cookbooks
Required User Group Permissions
SA provides user group Chef Group out of the box with all the necessary action permissions.
In addition to having the required action permissions, the user must be assigned the appropriate resource
and folder permissions.
For detailed guidelines of the permissions for managing Chef Cookbooks, see Chef Cookbook
Management Permissions.
Enabling an SA Server to Run Chef Recipes by Installing the chef-solo Policy
In order to run Chef Recipes on an SA Agent-managed server, you must first deploy the Chef runtime
environment on the server.
An SA Agent-managed server is a server that is managed by an SA Agent. There are multiple ways to
deploy a managed server in SA, such as by SA Agent or a virtualization service. To run Chef Recipes, the
servers must be managed by the SA Agent.
SA 10.1 ships with a single chef-solo bundled software policy that can be run on any supported server
platform to enable the Chef Runtime Environment.
9
The chef-solo bundled policy contains the same open source Chef Client installers for each chef-supported
platform that can be downloaded from the Chef Community, as well as two Application Configurations for
the supported platform families: Chef Solo Unix and Chef Solo Windows. This policy is provided directly in
SA for your convenience.
figure 1
chef-solo bundled policy
After the Chef Runtime Environment is enabled on a server, that server can handle running Chef Recipes.
To implement this policy on a server, attach it to the desired server and remediate the server. The
chef-solo bundled software policy will recognize the OS and platform of the server and deploy the correct
package and Application Configuration on the server. This means that you do not need to find and select
individual Chef Client installation packages for each server; the one bundled software policy contains
them all and deploys the items that are required.
To deploy the chef-solo policy and enable the Chef Runtime Environment:
1
Attach the chef-solo Policy to the Servers.
Use your preferred method:
2
—
Method 1: To attach server(s) or device group(s) to the chef-solo policy
—
Method 2: To attach the chef-solo policy to server(s) or device group(s)
Remediate Servers to Deploy the chef-solo Policy.
This will install the correct Chef Client installation package and Application Configuration on each of
the attached servers.
These steps are described below.
10
Chapter 1
Attach the chef-solo Policy to the Servers
Method 1: To attach server(s) or device group(s) to the chef-solo policy
1
From the SA Client navigation pane, select Library > By Type > Software Policies.
a
A list of supported operating systems appears in the content pane. Select the desired OS and
platform to display the available software policies in the content pane.
b
You may have to drill down the hierarchy a few levels to see the list of software policies.
c
See Chef-supported Platforms on page 13 for a list of platforms with a Chef Client installer.
2
Select the chef-solo software policy. The policy details will appear in the lower pane.
3
From the Actions menu, select Attach.... The Attach Server window appears.
(Optional) Enable Remediate Servers Immediately to remediate the attached servers against the
software policy.
4
Navigate to the list of managed servers or device groups:
a
Select All Managed Servers to view the server list.
Or
b
5
Select Device Groups to view the device group list.
From the content pane, select the desired servers or device groups.
Only agent-managed servers can be used to run the Chef Recipes, so you must select SA Agent-managed
servers or device groups containing agent-managed servers.
6
Click Attach. The Remediate window will appear.
Method 2: To attach the chef-solo policy to server(s) or device group(s)
1
From the SA Client navigation pane, access the list of managed servers or device groups:
a
Select Devices > Servers > All Managed Servers to view the server list.
Or
b
Select Devices > Device Groups to view the device group list.
2
From the content pane, select the servers or device groups.
3
From the Actions menu, select Attach > Software Policy. The Attach Software Policy window
appears.
(Optional) Select Remediate Servers Immediately to remediate the servers against the software
policy.
4
Select the Browse Software Policies tab to view a flat list of software policies.
5
Select the chef-solo policy.
6
Click Attach. The Remediate window will appear.
Getting Started with Chef Cookbooks in SA
11
Remediate Servers to Deploy the chef-solo Policy
To remediate the servers to deploy the chef-solo policy:
1
Access the Remediate window from the server list or from the policy view:
There are two ways to access the remediate window. Each is described below.
a
To access the Remediate window from the server list:
—
From the SA Client navigation pane, access the list of managed servers or device groups:
Select Devices > Servers > All Managed Servers to view the server list.
Or
Select Devices > Device Groups to view the device group list.
—
Select the server(s) or device group(s) you want to remediate.
Only agent-managed servers can be used to run the Chef Recipes, so you must select SA Agent-managed
servers or device groups containing agent-managed servers.
—
b
From the Actions menu, select Remediate....
To access the Remediate window from the software policy list:
—
From the SA Client navigation pane, select Library > By Type > Software Policies.
Select the desired OS and platform to display the available software policies in the content
pane. (You may have to drill down the hierarchy a few levels to see the list of software
policies.)
See Chef-supported Platforms on page 13 for a list of platforms with a Chef Client installer.
2
—
Select the chef-solo software policy. The policy details will appear in the lower pane.
—
Select View > Server Usage. A list of the servers attached to this policy appears in the lower
pane.
—
Select a server or multiple servers, and then select Remediate... from the Actions menu.
From the Remediate window, you can specify the remediation job options, run the job, and view the
job status. The navigation pane in the Remediate window walks you through the following standard
remediation steps.
In each step, review and modify the settings as desired and click Next to proceed through the steps.
(See the User Guide: Software Management for additional details about these options.)
Step 1: Select Servers and Policies for Remediation
•
This option will reflect the server(s) you selected in step 1. You can modify your selection within
the job as well using the
•
12
and
icons to add or remove selected servers.
You can click Start Job at any point after Step 1 to run the remediation job. However, it is
recommended that you review the optional settings before running the job.
Chapter 1
Step 2 (Optional): Specify Reboot, Error Handling, and Script Options for Remediation
•
In the Reboot section, you can control when to reboot servers during the chef-solo Client
Package installation or uninstallation.
•
In the Error Handling section, specify if you want to skip error handling when possible to
minimize downtime.
•
In the RPM Rollback section, select the Create RPM Rollback point option to set the current server
state as a rollback point. This preserves the current state in case you want to restore it later if
something about a subsequent update fails.
This option is only available and relevant on certain Linux servers.
•
In the Scripts section, specify if you want any scripts to run on a server before or after
installation or uninstallation. You can specify different scripts on each of the four tabs in this
section:
—
Pre-Download (Installation Only)
—
Post-Download (Installation Only)
—
Pre-Install/ Pre-Uninstall
—
Post-Install/ Post-Uninstall
Step 3 (Optional): Preview the Remediation Job
You can preview a detailed list of actions that will be performed on a server as a result of the software
remediation job. Information is displayed for each server or device group where the job will be run.
Step 4 (Optional): Schedule the Remediation Stages
The remediation process has three stages: 1) Analysis, 2) Download, and 3) Remediate. You can
schedule specific times to run each stage, or set each stage to run immediately after the previous one
completes.
Step 5 (Optional): Set E-mail Notifications for Remediation
Set e-mail notifications to alert you or other users on the success or failure of the remediation
process. You can associate a Ticket ID to identify and track this job.
Step 6: Run the Remediation Job and View Job Status
•
When you are satisfied with the job settings, click Start Job to run the remediation job.
•
When you run the remediation job, the Job Status window provides summary information about
the job progress. You can also view the status of each action required to complete the job.
Chef-supported Platforms
See the SA Support and Compatibility Matrix for SA-supported managed server platforms. See the Chef
Community (http://community.opscode.com/) for Chef Client supported platforms.
Getting Started with Chef Cookbooks in SA
13
Downloading Cookbooks from the Chef Community
Download the desired Chef Cookbooks from the Chef Community to your local machine to upload to SA.
1
Point your browser to the Chef Community portal: http://community.opscode.com/
2
Select a Chef Cookbook to download.
3
Click Download and browse to a local directory to store the cookbook.
4
Follow the on-screen instructions to complete the download.
After downloading the cookbooks to your local machine, you can upload them to SA and manage their
usage. For details, see Using Chef Cookbooks and Recipes in SA on page 17.
chef-solo Bundle Configuration in SA
The Chef standalone client, chef-solo, is installed and configured in SA by remediating the
platform-independent software policy by the same name, chef-solo, located in folder /Opsware/Tools/
Chef. The chef-solo bundled software policy contains the platform installers for the platforms supported
both by SA managed servers and Chef.
See Enabling an SA Server to Run Chef Recipes by Installing the chef-solo Policy on page 9 for details
on the installation procedure.
The remainder of this topic section describes the configuration of the chef-solo configuration file, ‘solo.rb’,
in SA.
chef-solo configuration file—solo.rb
Where the chef-solo configuration file is stored depends on the operating system of the server:
•
Unix: /etc/opt/opsware/chef/solo.rb
•
Windows: C:\Program Files\Common Files\Opsware\etc\chef\solo.rb
This section shows the integration-required parameters that go into the Chef’s solo.rb file, per operating
system. You can add or remove parameters as needed for your implementation.
Unix solo.rb Parameters
These parameters will be overridden in SA for Unix managed servers:
14
setting
default value in SA
cookbook_path
"/var/opt/opsware/chef/cookbooks"
file_backup_path
"/var/opt/opsware/chef/backup"
file_cache_path
"/var/opt/opsware/chef/cache"
node_path
"/var/opt/opsware/chef/node"
role_path
"/var/opt/opsware/chef/roles"
Chapter 1
Windows solo.rb Parameters
These parameters will be overridden in Windows managed servers:
setting
default value in SA
cookbook_path
"C:/Program Files/Common Files/Opsware/chef/cookbooks"
file_backup_path
"C:/Program Files/Common Files/Opsware/chef/backup"
file_cache_path
"C:/Program Files/Common Files/Opsware/chef/cache"
node_path
"C:/Program Files/Common Files/Opsware/chef/node"
role_path
"C:/Program Files/Common Files/Opsware/chef/roles"
The template namespace is set to /system/chef and the filename key to /files/chef/solo_rb.
Package Repository for Chef
Package installations in Chef rely on the native package manager to retrieve the packages and
dependencies from the configured repositories. This requires that the managed server be connected to
the internet directly or through an internet proxy.
If SA is deployed in an air-gapped environment, the only source of package content is the SA Software
Repository. In this case, the package managers (PKGMGR) on the managed servers need to be configured
to use the Software Repository as a package repository for Chef.
Specifying the Package Repository for Chef
This section describes how to make the Chef content (recipes) search for packages inside SA instead of the
Internet.
To perform this task, the system administrator must belong to a user group with the appropriate
permissions to edit System Configuration Settings.
Editing SA System Configuration settings is discouraged unless you have approval from HP Support to
make a specific change. Changes to the System Configuration settings can have adverse effects on all SA
operations and cannot always be resolved. You may perform this specific task as explicitly stated, but do
not change any other System Configuration settings without the express instructions from HPSA Support.
To modify the package repository setting:
1
Log in to the SA Client as an Opsware System Administrator.
2
Navigate to system configuration settings for the Command Engine:
Administration > System Configuration > Command Engine
3
Search for ‘way.chef.package_repository’.
Getting Started with Chef Cookbooks in SA
15
4
Enter the configuration state that works for your environment:
0: SA package repository only (default)
1: Both the SA package repository and external repositories configured on the managed server
2: Repositories configured on the managed server only
Setting SA as the package repository for Chef works only for managed servers that use yum as their
package manager.
Localization Support for Chef Recipes
SA supports recipes that are localized. It does not support non-ASCII-based names for cookbooks or
recipes.
16
Chapter 1
2 Chef Management
Using Chef Cookbooks and Recipes in SA
This section describes how to use and manage Chef Cookbooks and Recipes in SA.
HP does not provide Chef content. The Chef Cookbooks can be downloaded from the Chef Community
portal, any other source provider, or can be created by software developers. See the Opscode
documentation for explanations about Chef content and framework:
http://docs.opscode.com/
Uploading Chef Cookbooks to SA
SA supports uploading Chef Cookbooks to SA the same way you would import any software package. You
can import from the SA Client or from the SA Command Line Interface (CLI).
figure 2
primary method for uploading chef cookbooks to SA
See the User Guide: Software Management for additional details about the software import task in SA.
17
Importing a Chef Cookbook from the SA Client
Importing cookbooks in the SA Client is the same process as importing other packages. It is important to
select “Chef Cookbook” file type during the import.
To import a Chef Cookbook from the SA Client:
1
Find and select the desired import destination for the Chef Cookbook using one of the following
methods. All of these methods start from the Library tab in the SA Client:
a
b
c
2
Method 1: Library > By Type > Chef Cookbooks.
—
Find and open the operating system where the Chef Cookbook(s) should be imported.
—
Select Actions > Import Cookbook…
Method 2: Library > By Type > Packages.
—
Find and open the operating system where the Chef Cookbook(s) should be imported.
—
Select Actions > Import Software…
Method 3: Library > By Folder.
—
Find and open the folder in which the Chef Cookbook(s) should be imported.
—
Select Actions > Import Software…
In the File(s) section of the Software Imports window:
a
Click Browse to locate the Chef Cookbook(s) to import.
b
Select the cookbook(s) to import.
Character encoding is not relevant because cookbooks are binary files.
18
c
Click Open.
d
Select Chef Cookbook (tgz archive) file type from the Type drop-down list:
Chapter 2
3
In the Folder section of the Software Imports window, click Browse to select the destination folder
location.
a
From the Platform drop-down list, select the applicable operating systems or operating system
families.
Best Practice: Associate a cookbook with the supported platforms defined by the cookbook metadata.
The platform associations for Chef Cookbooks are only guidelines as SA mirrors the behavior of Chef and
will run the Recipe on any chosen server.
When viewing cookbooks on the Chef Community portal (http://community.opscode.com/), the supported
platforms are indicated on the download page and in the cookbook metadata file (metadata.rb). To view
the cookbook metadata in SA, see Viewing Cookbook Details in SA Client on page 22.
4
Click Import.
(Optional) If one of the packages you are importing already exists in the folder, you will be prompted
with the following options for handling the duplicate file:
You have the following options:
Chef Management
•
Replace: Replace (overwrite) the contents of the existing file.
•
Replace All: When there are multiple existing files with the same name as the file you are
importing, you can replace (overwrite) the contents of all the existing file.
•
Skip: Skip the replacement of a single file. If you have multiple existing files with the same name
as the files you are importing, you can select which files to skip or not. Skipping the import of a
file does not affect other files with different names if you are importing multiple files. Only the
specified file(s) will be skipped, the other specified files will be imported.
•
Skip All: All specified files with the same name as the file you are importing will be skipped and
not replaced.
•
Cancel: Cancels the Import Packages operation entirely. No files are imported.
•
Help: Provides online help for the current dialog.
19
5
View the progress of the importing files in the Software Imports window while the import is
underway, the Software Imports window displays the details and progress of the import. This window
displays all the imports made within the session.
Uploading Chef Cookbooks from the SA Command Line Interface (CLI)
Importing cookbooks via the SA CLI is the same process as importing other packages. It is important to
specify “Chef Cookbook” file type during the import.
To perform SA CLI commands, your login must have the appropriate authorizations to run oupload or
odownload. For information on permissions, see the SA Administration Guide.
See the SA User Guide: Server Automation for additional details about SA CLI commands. See the SA
User Guide: Software Management for information specific to different package types.
To Upload Chef Cookbooks from the SA Command Line Interface (CLI)
The oupload command has the following syntax. The filenames can contain a relative or absolute
local file or directory path. If an option value contains spaces, enclose the value in quotes.
oupload [options] filenames
1
To upload a Chef Cookbook, specify the package type, “Chef Cookbook” in quotes or just
CHEF_COOKBOOK, without quotes.
For example:
[root@cbt1 ~]# /opt/opsware/ocli/ocli/bin/oupload.sh --os "Red Hat
Enterprise Linux Server 6" --pkgtype "Chef Cookbook" --folder "Package
Repository" ./ntp20131006.tar.gz
where ./ntp20131006.tar.gz is the local relative path to the cookbook you are uploading to the
SA folder “Package Repository.” In this example, the command is performed from one of the SA Core
servers.
2
When prompted, enter the username and password of an SA user with the appropriate authorizations.
3
If the file already exists, in the specified location, you will be prompted with the option to overwrite
the file. Enter “y” to overwrite it or “n” to cancel the action:
ntp20131006.tar.gz already exists. overwrite? [y,n]: y
4
“COMPLETE” will appear on the command line to notify you when the process is complete:
Package Repository/./ntp20131006.tar.gz: COMPLETE
[root@core-20 install_opsware]#
20
Chapter 2
Cookbook Versioning
SA stores cookbooks in a folder-like structure and this allows users to upload the same cookbook (name
and version) several times by placing it in different folders or in the same folder but with different SA
filenames.
In such a case, it is undefined which exact instance of the cookbook will be used at runtime. This will not
cause any issues as long as users follow the basic principle that two cookbooks having the same names
and versions are identical.
Managing Chef Cookbooks in SA
Accessing Chef Cookbooks from the SA Client
figure 3
new SA object type: chef cookbooks
To locate Chef Cookbooks in SA Client By Folder:
Chef Management
1
From the navigation pane, select Library > By Type > Chef Cookbooks.
2
Navigate down the hierarchy by selecting a platform and then a platform version.
3
From the content pane, select a cookbook and then select Locate in Folders from the Actions menu.
The folder hierarchy for the policy appears in the content pane.
21
To locate Chef Cookbooks in SA Client By Type:
1
From the navigation pane, select Library > By Type > Chef Cookbooks.
2
Navigate down the hierarchy by selecting a platform and then a platform version.
3
Select a cookbook associated with this specific platform version.
Viewing Cookbook Details in SA Client
SA provides complete visibility into the properties, metadata, and recipes of the imported cookbooks.
To view cookbook details from the preview pane:
You can access the cookbook details directly from the preview pane when selecting the cookbook:
figure 4
previewing details of a cookbook from the chef cookbooks list view
To view cookbook details from within the cookbook:
22
1
From the navigation pane, select Library > By Type > Chef Cookbooks.
2
Navigate down the hierarchy by selecting a platform and then a platform version.
3
Select a cookbook associated with this specific platform version.
Chapter 2
4
From the Actions menu, select Open to view Cookbook details. There are three views in the Cookbook
explorer.
a
Properties (cookbook file information)
b
Metadata (attributes and components of the cookbook)
c
Recipes (the contents of each of the recipes in the cookbook).
Editing Chef Cookbook Properties
The Cookbook: Properties window in the SA Client allows you to view and edit the properties of a
cookbook. You can edit a cookbook’s Name, Description, OS, and Location.
Editing cookbook properties can be done only by users that have write permissions for the folder where
the cookbook resides.
To edit chef cookbook properties:
1
From the navigation pane, select Library > By Type > Chef Cookbooks.
2
Navigate down the hierarchy by selecting a platform and then a platform version.
3
Select a cookbook associated with this specific platform version.
4
From the Actions menu, select Open to view Cookbook details.
5
In the navigation pane, select Properties to view cookbook file information.
6
Update the editable fields:
•
Name: The default name is based on the name of the import file. This is an editable text field.
—
7
Chef Management
Only the internal SA name of the cookbook is editable; not the native one, so
cookbook-dependency resolution is not affected by a rename.
•
Description: Enter a meaningful description for the cookbook in the text field
•
OS: Click the arrow to select or deselect supported operating systems for this cookbook.
•
Location: Click Select to navigate to and select the folder path in the SA Library. Navigate to the
desired folder location and click Select again to make the selection.
Select File > Save to save your changes.
23
Running Chef Recipes
After enabling the SA Server to run Chef Recipes, and after importing a Chef Cookbook, you can easily run
a Chef Recipe on any Chef-enabled SA managed server.
For prerequisite steps, see Enabling an SA Server to Run Chef Recipes by Installing the chef-solo Policy
on page 9.
figure 5
running chef recipes on a chef-enabled SA managed server
To run Chef Recipes from SA Devices tab:
1
From the SA Client navigation pane, access the list of managed servers or device groups:
a
Select Devices > Servers > All Managed Servers to view the server list.
Or
b
2
24
Select Devices > Device Groups to view the device group list.
From the content pane, select the servers or device groups.
Chapter 2
3
From the Actions menu, select Run > Chef Recipe.
4
Click Select Recipe to find the desired recipe.
5
Select the specific Chef Recipe you wish to run and click Select.
6
From the Run Chef Recipe window, review the additional options:
a
Scheduling: specify to run the recipe at a schedule time. By default, it will run immediately.
b
Notifications: specify e-mail notifications be sent when the job succeeds or fails. By default, no
e-mails are sent.
You can override the chef command options. For example, you can use the Options window to specify any
Runtime or Output options. See Run Chef Recipe: Options for details.
7
When you are satisfied with the job settings, click Start Job to run the recipe.
To run Chef Recipes from the SA Library:
You can also run Chef Recipes by selecting the recipe from the SA Library.
1
From the SA Client navigation pane, access the list Chef Cookbooks in the SA Library:
Library > By Type > Chef Cookbooks
Chef Management
2
Select the platform and version you want.
3
From the content pane, select the cookbook you want.
4
In the View list, select Recipes.
5
From the list of recipes in the detail pane, select the recipe or recipes that you want to run.
25
Library > By Type > Chef Cookbooks:
6
Select Action > Run Chef Recipe...
7
In the Recipes step, the selected recipes appear. You can add or remove using the
or
icons.
The Server group calculation option enables you to choose whether to calculate the device group
servers “Now” or “At runtime.”
26
•
Select “Now” to calculate the servers that comprise the device groups now, while you define the
job.
•
Select “At runtime” to defer calculating the servers that comprise the selected device groups to
when the Run Chef Recipe job is run.
Chapter 2
8
9
Step through the additional settings in the Run Chef Recipe window before starting the job:
a
In the Devices step, select the servers or device groups where you want to run the recipe.
b
In the Options step, specify any Runtime or Output options. You can override the chef command
options at run time or control whether to retain job output. (See Run Chef Recipe: Options for
details about these settings. See Retain Job Output for information about how and where the
output log files are stored.)
c
In the Scheduling step, specify to run the recipe at a schedule time. By default, it will run
immediately.
d
In the Notifications step, specify e-mail notifications be sent when the job succeeds or fails. By
default, no emails are sent.
When you are satisfied with the job settings, click Start Job to run the recipe.
Customizing a Run Chef Recipe Job
Attributes are a basic concept in Chef and play a crucial role in managing a Chef node (a managed server in
SA terminology). Chef attributes have different scopes and sources. See the Chef documentation on
attributes.
The SA custom attributes framework provides a way to pass attributes defined in SA at Chef runtime,
during a Run Chef Recipe job.
The syntax used to define SA custom attributes for Chef is very similar to the one used to define Chef
native attributes: all custom attributes applicable to a managed server (after scope resolution), whose
names start with "chef_attr," will be passed to the Chef runtime.
Chef Management
27
The following figure is an example of how to override the proxy username and password that will be used
by the yum cookbook. Notice that both " and ' can be used as separators. Using ' keeps the look and
feel of the community Chef cookbooks:
See the SA User Guide: Server Automation for more information about how to use SA Custom Attributes.
Retain Job Output
This section describes the chef-solo log files on the SA Managed Server and the retain job output setting
in the Run Chef Recipe job.
Log Files on the SA Managed Server
There are two log files containing information regarding the chef-solo command execution on SA
managed servers:
•
chef.log - contains the SA log of Run Chef Recipe Jobs and is additive
•
chef-solo.out - contains the full chef-solo command output for the last job executed on the managed
server
Where the chef-solo log files are stored depends on the operating system of the server:
•
Unix: /var/log/opsware/agent/
•
Windows: C:\Program Files\Common Files\Opsware\log\agent\
Job Results Fields Examples
Successful Run Chef Recipe job results display the chef-solo output if the retain job output was selected in
the job options with a value >0 KB:
figure 6
Successful Job Results:
If the job failed, the Exception section will state the failure and provide the exit code, the error details and
cause, and any action if there is one. This is displayed for all servers that are not successful:
figure 7
Chef Management
Failed Job Results:
29
Job Results Fields Defined
table 1
Job Results Fields
Field
Description
Start time
time the job started
End time
time the job ended
Output
•
contains the chef-solo output if ‘Retain job output’ was selected and the
‘Size of the job output to retain’ was set to a value greater than 0 KB
•
empty if ‘Discard all job output’ was selected or ‘Retain job output’ was
selected with 'Size of the job output to retain' set to 0 KB
•
Values are grouped into three categories:
Exit Code
Exception
•
—
negative values: failed Run Chef Recipe jobs where SA prerequisites
are not met (such as missing permissions or missing dependencies)
—
positive values (native chef-solo error codes): failed Run Chef Recipe
jobs where chef-solo fails
—
0: successful Run Chef Recipe jobs
displayed for all servers with ‘Failed’ Run Chef Recipe job status
Blocking a Run Chef Recipe Job
You can block Run Chef Recipe jobs just as you can any software or script job via the Operations
Orchestration job blocking function. See Blocking Jobs in the SA-OO Integration – Job Blocking and
Approving chapter in the SA integration Guide for instructions.
30
Chapter 2
A Chef Cookbook Management Permissions
This section specifies the Chef Cookbook Management permissions required by users to perform specific
actions in the SA Client. For security administrators, the table answers this question: To perform a
particular action, what permissions does a user need?
In addition to the action permissions listed, every user action also requires the Managed Servers and
Groups permission. For additional guidelines on how to set up SA permissions, see the Permissions
Reference appendix in the SA Administration Guide.
Permissions for Running a Chef Recipe from a Cookbook with No Dependencies
The following permissions are required in order to run a Chef Recipe from a cookbook with no
dependencies:
•
These Action Permissions control the Chef tasks you can perform.
Permission
Setting
Task Enabled
Run Chef Recipes
Yes
the ability to start or schedule a specific Run Chef
Recipe job.
Manage Package
Read (or stronger)
the ability to use Cookbooks (which is a type of SA
package) in Run Chef Recipe jobs.
The user running the Run Chef Recipe job must belong to a user group with the Run Chef Recipes and
Manage package permissions.
•
Folder Permissions control the access to the SA Library folder where the cookbook resides.
The user running the Run Chef Recipe job must belong to a user group with Read permission on the
folder where the cookbook resides.
•
Resource Permissions control the access of the current user to the managed servers in SA.
The user running the Run Chef Recipe job must belong to a user group with Read&Write permission on
the server’s facility, customer, and at least one of it’s Device Groups.
For more information about setting resource permissions, see About Resource Permissions in the SA
Administration Guide.
•
Customer Constraints on Folders determine which servers can be the target of a Run Chef Recipe job.
As each server is assigned to a Customer, the customer constraints of the cookbook folder must
include the Customer of the target server.
Alternatively, you can ignore folder customer permissions entirely by assigning the Customer
Independent customer to the cookbook folders.
For more information about setting folder permissions, see About Resource Permissions in the SA
Administration Guide.
Chef Cookbook Management Permissions
31
Permission Management for Cookbooks with Dependencies
The dependencies of a cookbook must satisfy the same permission requirements as the main cookbook:
Read folder permissions and the proper folder customer constraints. If multiple versions of the dependent
cookbooks exist, SA will use the newest version of the dependent cookbooks for which the entire
dependency graph satisfies all required permissions.
Example: In the following setup, when the user tries to run a recipe from cookbook A, SA will resolve its
dependency on cookbook B to version 1.7.4.
figure 8
Illustration of Permissions for Running Chef Recipes
More in-depth, version 1.8 of cookbook B cannot be used because folder2 is not associated to customer1
(the customer of the targeted server). Version 1.7.5 of cookbook B can’t be used because the user doesn’t
have any permissions on folder3. Versions 1.7.4 and 1.7.3 are both accessible and SA will choose the
higher version, therefore 1.7.4.
32
Chapter A
Multi-tenancy
Customer constraints on folders provide the mechanism to support multi-tenancy, which allows you to
apply different content to different customers.
In the example below, applying cookbook A to a group of two managed servers (cbt2 and m529) will result
in applying version 1.0 of cookbook B to server m529 and version 2.0 of cookbook B to server cbt2.
figure 9
Illustration of Multi-tenancy for Chef Recipes
Chef Cookbook Management Permissions
33
34
Chapter A
B Chef Cookbook Page Help
This appendix provides help on each of the pages in the SA Client that are used for managing and using
Chef Cookbooks and Recipes.
Pages:
•
Chef Cookbooks
•
Cookbook: Properties
•
Cookbook: Metadata
•
Cookbook: Recipes
•
Recipes: Contents
•
Cookbook Imports
•
Run Chef Recipe: Devices
•
Run Chef Recipe: Add Devices
•
Run Chef Recipe: Recipes
•
Run Chef Recipe: Select Recipes
•
Run Chef Recipe: Options
•
Run Chef Recipe: Scheduling
•
Run Chef Recipe: Notifications
•
Run Chef Recipe: Job Status
Chef Cookbooks
This window displays and manages Chef Cookbooks that are in the Library.
From the navigation pane, select an operating system to display cookbooks for that operating system.
Then, select a specific cookbook to view detailed information in the Details pane. The type of information
displayed in the Details pane depends on the option selected in the View list. The optional views are:
•
Properties (See Cookbook: Properties)
•
Metadata (See Cookbook: Metadata)
•
Recipes (See Cookbook: Recipes)
The Actions menu provides the following options when you select a cookbook:
•
Open: opens the cookbook explorer window.
•
Locate a Cookbook in Folder: searches the By Folder directory in the SA Library to find the location of
the selected cookbook.
•
Import Cookbook...: opens the import window. (See Cookbook Imports)
•
Export Cookbook...: opens the export window where you can browse your local machine for a
directory to save the cookbook.
Chef Cookbook Page Help
1
•
Rename Cookbook: renames the selected cookbook
•
Delete Cookbook: deletes the selected cookbook
• Editing Chef Cookbook Properties
• Running Chef Recipes
• Accessing Chef Cookbooks from the SA Client
• Cookbook: Properties
• Cookbook: Metadata
• Cookbook: Recipes
Cookbook: Properties
The Cookbook: Properties window in the SA Client allows you to view the properties of a cookbook. If you
are in the cookbook object browser after you have opened the cookbook, you can edit some of the
cookbook’s properties, such as Name, Description, OS, and Location.
• Chef Cookbooks
• Editing Chef Cookbook Properties
Cookbook: Metadata
The Cookbook: Metadata window in the SA Client displays the content of the metadata.rb file from the
cookbook, which can contain cookbook version, recipe(s) names, description, supported OS, and other
defining attributes.
• Chef Cookbooks
Cookbook: Recipes
The Cookbook: Recipes window in the SA Client lists all the recipes in the cookbook. If you are in the
cookbook object browser after you have opened the cookbook, you can view the contents of the recipe.
From this window, you can also run any of the selected recipes.
• Chef Cookbooks
• Running Chef Recipes
2
Appendix
Recipes: Contents
The Recipes: Contents window allows you to view the recipe text. From this window, you can also run any
of the selected recipes.
• Managing Chef Cookbooks in SA
• Running Chef Recipes
Cookbook Imports
The Cookbook Imports window allows you to import (upload) cookbooks into SA.
Import Cookbook fields:
File(s)
Click Browse to locate and select the cookbook to import.
Type
Chef Cookbook
Folder
Click Browse to locate and select the desired directory of the SA Library to store the
imported cookbook.
Platforms
Select all the relevant operating system versions for the import file.
All supported SA platforms are available for selection.
Import
Click Import to import the file into the SA Library.
The Software Imports window displays the status of the import.
• Chef Cookbooks
• Importing a Chef Cookbook from the SA Client
• Managing Chef Cookbooks in SA
Duplicate File Handling
If a cookbook being uploaded already exists in the Software Repository, the override dialog appears
providing you with options for handling the duplicate file:
•
Replace: Replace (overwrite) the contents of the existing file.
•
Replace All: When there are multiple existing files with the same name as the file you are importing,
you can replace (overwrite) the contents of all the existing file.
•
Skip: Skip the replacement of a single file. If you have multiple existing files with the same name as
the file you are importing, you can select which files to skip or not. Skipping the import of a file does
not affect other files with different names if you are importing multiple files. Only the specified file(s)
will be skipped, the other specified files will be imported.
•
Skip All: All specified files with the same name as the file you are importing will be skipped and not
replaced.
•
Cancel: Cancels the Import Packages operation entirely. No files are imported.
•
Help: Provides online help for the current dialog.
Chef Cookbook Page Help
3
Run Chef Recipe: Devices
Use the Devices window to specify the managed servers and devices on which to run the Chef Recipe. From
this window you can add or remove the selected devices.
•
Click the Add (
) icon to add a server or device
•
Click the Remove (
) icon to remove the selected server or device.
• Running Chef Recipes
Run Chef Recipe: Add Devices
Use the Select Servers and Device Groups window to select additional managed servers and device groups
on which to run the Chef Recipe.
From this window you can filter or search the list of servers by any server attribute. You can also select
one or multiple servers to add to the job.
After selecting the desired servers, click Select to return to the Run Chef Recipe window.
• Running Chef Recipes
Run Chef Recipe: Recipes
Use the Recipes window to specify the Chef Recipes to run. From this window you can add or remove
recipes as well as specify the order in which the recipes are run. When you select a recipe, the Details pane
displays the contents of the recipe.
•
Click the Add (
) icon to add a recipe.
•
Click the Remove (
•
Use the Up ( )and Down ( )arrows to specify the order in which the recipes are run.
) icon to remove a recipe.
• Running Chef Recipes
Run Chef Recipe: Select Recipes
Use the Select Recipes window to specify the Chef Recipes to run on the selected servers/device groups.
From this window you can filter or search the list of recipes by any recipe attribute. You can also select one
or multiple recipes.
After selecting the desired recipes, click Select to return to the Run Chef Recipe window.
• Running Chef Recipes
4
Appendix
Run Chef Recipe: Options
Use the Options window to specify any Runtime or Output options in order to optimize runtime
performance.
•
Runtime Options: this option enables you to override all Chef parameters, except the following:
Option
Description of override limitation
-c
The configuration file cannot be overridden by this option. If you want to use a
different configuration file, you will need to update the content of the existing
one.
--no-color
This option is not relevant in the SA Client environment.
-o
Mixing the selected recipes with another list of recipes provided by the -o option
is not supported.
If you provide override parameters containing paths, the chef-solo command cannot work properly both
for UNIX and Windows machines. If you provide override parameters containing filesystem paths, you
must run the job separately for UNIX and Windows machines.
•
Output Options: specify how to handle the job output.
These options support customizing the chef run and storing the chef run output.
Jobs can generate a maximum of 10 KB of screen output per server. Use this option to determine
whether to keep or delete the job log after the job is run.
—
If you choose to retain the log output, you can specify the maximum size (in KB) of the file to
retain, up to 10 KB.
—
If you choose to discard all job output, then the chef-solo output will not be retained.
• Running Chef Recipes
Run Chef Recipe: Scheduling
Use the Scheduling window to specify the timing for the Chef Recipe job. Options include:
Schedule Frequency:
Specify how often to run this recipe. Select any one of the following options:
•
Once: Choose this option to run the job immediately or only once at a specified date and time.
•
Daily: Choose this option to run the job on a daily basis at a specified time.
•
Weekly: Choose this option to specify the day or days of the week to run the job.
•
Monthly: Choose this option to specify the months to run the job, and the days of the month.
•
Custom: In the Custom Crontab string field, enter a string the indicates a time schedule. The crontab
string can include serial (1,2,3,4) and range (1-5) values.
Chef Cookbook Page Help
5
Time and Duration:
For each type of schedule, specify the start time for the job. You must also specify the start date and end
date for the job. The Time Zone is set according to the time zone set in your user profile.
• Running Chef Recipes
Run Chef Recipe: Notifications
Set e-mail notifications to alert you or other users on the success or failure of the Chef Recipe job. You can
associate a Ticket ID to identify and track this job.
• Running Chef Recipes
E-mail Notifications:
•
•
By default, your e-mail address will appear in the list of recipient e-mail addresses.
—
To add additional recipients, click Add Notifier and enter the e-mail addresses in the E-mail
Address of Recipient field.
—
To remove a recipient, select the recipient and click Remove.
For each recipient, select the options for when to send an e-mail notification:
—
On Success: sends e-mail to recipient if the job succeeds.
—
On Failure: sends e-mail to recipient if the job fails.
Ticket Tracking:
In the Ticket ID field, enter a unique text string to identify this job. This string will appear in the e-mail
notifications.
Run Chef Recipe: Job Status
When you run the Chef Recipe job, the Job Status window provides summary information about its
progress. You can also view the status of each action required to complete the job.
• Running Chef Recipes
The Job Status window will appear without any details until the job actually begins. When the job starts
depends on the settings defined in the Scheduling step.
•
6
If you set the job to run immediately, then the job will begin immediately after you click Start Job
from any of the setting steps.
—
When the job starts, the Job Status window will appear showing the progress of the job.
—
To view the details of each action, select an action row in the table. The details for the selected
action appear in the lower panel of the content pane.
—
You can also perform any of the following optional actions:
–
Click Back or Next to check job specification details.
–
Click Close to close the window.
Appendix
•
If you scheduled the job for a later time, the job will run at the scheduled time and only then will the
Job Status window show progress details.
•
To view job status later, click Jobs and Sessions from the SA Client navigation pane, and then
double-click on the job to view details.
Chef Cookbook Page Help
7
8
Appendix
Download PDF
Similar pages