Knife Windows Plugin

DESCRIPTION:

This plugins adds additional functionality to the Chef Knife CLI tool for configuring/interacting with nodes running Microsoft Windows. The subcommands should function on any system running Ruby 1.9.1+ but nodes being configured via these subcommands require Windows Remote Management (WinRM) 1.0+. WinRM allows you to call native objects in Windows. This includes, but is not limited to, running batch scripts, powershell scripts and fetching WMI variables. For more information on WinRM, please visit Microsoft’s WinRM site. You will want to familiarize yourself with (certain key aspects) of WinRM because you will be scripts/running commands with this tool to get you from (specific point A) to (specific point B).

WinRM is built into Windows 7 and Windows Server 2008+. It can also be easily installed in older version of Windows, including:

  • Windows XP

  • Windows Server 2003

  • Windows Vista

More information can be found on Microsoft Support article 968930.

SUBCOMMANDS:

This plugin provides the following Knife subcommands. Specific command options can be found by invoking the subcommand with a –help flag

knife winrm

The winrm subcommand allows you to invoke commands in parallel on a subset of the nodes in your infrastructure. The winrm subcommand uses the same syntax as the search subcommand; you could could find the uptime of all your web servers using the command:

% knife winrm "role:web" "net stats srv" -x Administrator -P 'super_secret_password'

Or force a chef run:

% knife winrm 'ec2-50-xx-xx-124.compute-1.amazonaws.com' 'chef-client -c c:/chef/client.rb' -m -x Administrator -P 'super_secret_password'
ec2-50-xx-xx-124.compute-1.amazonaws.com [Fri, 04 Mar 2011 22:00:49 +0000] INFO: Starting Chef Run (Version 0.9.12)
ec2-50-xx-xx-124.compute-1.amazonaws.com [Fri, 04 Mar 2011 22:00:50 +0000] WARN: Node ip-0A502FFB has an empty run list.
ec2-50-xx-xx-124.compute-1.amazonaws.com [Fri, 04 Mar 2011 22:00:53 +0000] INFO: Chef Run complete in 4.383966 seconds
ec2-50-xx-xx-124.compute-1.amazonaws.com [Fri, 04 Mar 2011 22:00:53 +0000] INFO: cleaning the checksum cache
ec2-50-xx-xx-124.compute-1.amazonaws.com [Fri, 04 Mar 2011 22:00:53 +0000] INFO: Running report handlers
ec2-50-xx-xx-124.compute-1.amazonaws.com [Fri, 04 Mar 2011 22:00:53 +0000] INFO: Report handlers complete

This subcommand operates in a very similar manner as ssh[http://wiki.opscode.com/display/chef/Knife#Knife-SSHSubcommand]…just leveraging the WinRM protocol for communication. It also include’s knife ssh‘s “interactive session mode”

knife winrm bootstrap

Performs a Chef Bootstrap (via the WinRM protocol) on the target node. The goal of the bootstrap is to get Chef installed on the target system so it can run Chef Client with a Chef Server. The main assumption is a baseline OS installation exists. It is primarily intended for Chef Client systems that talk to a Chef server.

In the future this subcommand will be used internally by some cloud computing server create commands like the current *knife bootstrap* subcommand is. This subcommand operates in a very similar manner as bootstrap[http://wiki.opscode.com/display/chef/Knife+Bootstrap]…just leveraging the WinRM protocol for communication. An initial run_list for the node can also be passed to the subcommand. Example usage:

knife winrm bootstrap ec2-50-xx-xx-124.compute-1.amazonaws.com -r 'role[webserver]','role[production]' -x Administrator -P 'super_secret_password'

BOOTSTRAP TEMPLATES:

This gem provides the following bootstrap templates:

windows-shell

This bootstrap template does the following:

  • Installs Ruby 1.8.7 via the Ruby Installer for Windows which also includes the latest version of RubyGems

  • Installs required Windows-related gems from RubyGems.org

  • Installs latest Chef version from RubyGems.org including Ohai and Chef.

  • Writes the validation.pem per the local knife configuration.

  • Writes a default config file for Chef (C:chefclient.rb) using values from the knife.rb.

  • Creates a JSON attributes file containing the specified run list and run Chef.

This is the default bootstrap template used by the winrm bootstrap subcommand.

REQUIREMENTS/SETUP:

Chef Version

CHEF-1248 added the ability to load Knife subcommands from alternate locations including Ruby gems (such as this one). This feature will be built into the 0.10 release of Chef. Until then this feature can be added to Chef 0.9.x releases by using a monkey patched knife bin file:

cd YOUR_CHEF_REPO
curl https://gist.github.com/raw/f33e15bac2820dd572d4/cb6ab81023440235868e83b96fa0ae527d37e2d7/knife >> knife
chmod 744 knife

More details about Knife plugins can be found on the Chef wiki.

Nodes

NOTE: Before any WinRM related knife subcommands will function correctly a node’s WinRM installation must be configured correctly. The below settings should be added to your base server image (AMI) or passed in using some sort of user-data mechanism provided by your cloud provider.

A server running WinRM must also be configured properly to allow outside connections and the entire network path from the knife workstation to the server. The easiest way to accomplish this is to use WinRM’s quick configuration option:

C:\Users\Administrator> winrm quickconfig -q

The Chef and Ohai gem installations (that occur during bootstrap) take more memory than the default 150MB WinRM allocates per shell. Bump it up to 300MB with the following setting:

C:\Users\Administrator> winrm set winrm/config/winrs @{MaxMemoryPerShellMB="300"}

WinRM supports both the HTTP and HTTPS transports and the following authentication schemes: Kerberos, Digest, Certificate and Basic. The details of these authentication transports are outside of the scope of this README but details can be found on the WinRM configuration guide. Currently, this plugin support Kerberos and Basic authentication schemes.

For development and testing purposes, unencrypted traffic with Basic authentication can make things easier:

C:\Users\Administrator> winrm set winrm/config/service @{AllowUnencrypted="true"}
C:\Users\Administrator> winrm set winrm/config/service/auth @{Basic="true"}

LICENSE:

Author

Seth Chisamore (<[email protected]>)

Copyright

Copyright © 2011 Opscode, Inc.

License

Apache License, Version 2.0

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.