Knife vSphere¶ ↑

DESCRIPTION:¶ ↑

This is an Opscode Knife plugin to interact with VMware’s vSphere. This plugin currently supports the following:

Listings:

VMs
Folders
Templates
Datastores
VLANs (currently requires distributed vswitch)
Resource Pools and Clusters
Customization Specifications
Hosts in a Pool or Cluster

VM Operations:

Power on/off
Clone (with optional chef bootstrap and run list)
Delete
VMDK addition
Migrate
Connect/disconnect network

Clone-specific customization options (for linux guests):

Destination folder
CPU core count
Memory size
DNS settings
Hostname / Domain name
IP addresses / default gateway
vlan (currently requires distributed vswitch)
datastore
resource pool

INSTALLATION:¶ ↑

gem install knife-vsphere

CONFIGURATION:¶ ↑

For initial development, the plugin targets all communication at a vCenter instance rather than at specific hosts. Only named user authentication is currently supported; you can add the credentials to your knife.rb file:

knife[:vsphere_host] = "vcenter-hostname"
knife[:vsphere_user] = "privileged username"
knife[:vsphere_pass] = "your password"
knife[:vsphere_dc] = "your-datacenter"

The vSphere password can also be stored in a base64 encoded version (to visually obfuscate it) by prepending ‘base64:’ to your encoded password. For example:

knife[:vsphere_pass] = "base64:VGhhbmtzRXpyYSE=\n"

If you get the following error, you may need to disable SSL certificate checking: ERROR: OpenSSL::SSL::SSLError: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed

knife[:vsphere_insecure] = true

Credentials can also be specified on the command line for multiple VSphere servers/data centers

SUBCOMMANDS:¶ ↑

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

knife vsphere vm list [-r, –recursive [–only-folders]]¶ ↑

Enumerates the Virtual Machines registered in the target datacenter. Only name is currently displayed.

-r, --recursive    - Recurse down through sub-folders to the specified folder
--only-folders     - In combination with --recursive, print only folder names

knife vsphere vm state [-s STATE, –state STATE] [-w PORT, –wait-port PORT] [-g, –shutdown] [-r, –recursive]¶ ↑

Manage power state of a virtual machine. -s STATE, –state STATE - The power state to transition the VM into; one of on|off|suspended -w PORT, –wait-port PORT - Wait for VM to be accessible on a port -g, –shutdown - Guest OS shutdown

-r, --recursive            - Recurse down through sub-folders to the specified folder

knife vsphere pool list¶ ↑

Enumerates the Resource Pools and Clusters registered in the target datacenter.

knife vsphere template list¶ ↑

Enumerates the VM Templates registered in the target datacenter. Only name is currently displayed.

knife vsphere customization list¶ ↑

Enumerates the customization specifications registered in the target datacenter. Only name is currently displayed.

knife vsphere vm clone <new vm name> –template <source template name> –cspec <customization_spec>¶ ↑

 knife vsphere vm clone NewNode UbuntuTemplate --cspec StaticSpec \
     --cips 192.168.0.99/24,192.168.1.99/24 \
     --chostname NODENAME --cdomain NODEDOMAIN

--dest-folder FOLDER - The folder into which to put the cloned VM
--datastore STORE    - The datastore into which to put the cloned VM
--datastorecluster STORE - The datastorecluster into which to put the cloned VM
--resource-pool POOL - The resource pool into which to put the cloned VM
--template TEMPLATE - The source VM / Template to clone from
--cspec CUST_SPEC - The name of any customization specification to apply
--cplugin CUST_PLUGIN_PATH - Path to plugin that implements KnifeVspherePlugin.customize_clone_spec and/or KnifeVspherePlugin.reconfig_vm
--cplugin-data CUST_PLUGIN_DATA - String of data to pass to the plugin.  Use any format you wish.
--cvlan CUST_VLANS - Comma-delimited list of VLAN names for the network adapters to join
--cips CUST_IPS - Comma-delimited list of CIDR IPs for customization, or *dhcp* to configure that interface to use DHCP
--cgw CUST_GW - CIDR IP of gateway for customization
--chostname CUST_HOSTNAME - Unqualified hostname for customization
--cdomain CUST_DOMAIN - Domain name for customization
--ctz CUST_TIMEZONE - Timezone invalid 'Area/Location' format
--ccpu CUST_CPU_COUNT - Number of CPUs
--cram CUST_MEMORY_GB - Gigabytes of RAM
--start STARTVM - Indicates whether to start the VM after a successful clone
--bootstrap FALSE - Indicates whether to bootstrap the VM
--fqdn SERVER_FQDN - Fully qualified hostname for bootstrapping
--ssh-user USERNAME - SSH username
--ssh-password PASSWORD - SSH password
--ssh-port PORT - SSH port
--identity-file IDENTITY_FILE - SSH identity file used for authentication
--node-name NAME - The Chef node name for your new node
--hint HINT_NAME[=HINT_FILE] Specify Ohai Hint to be set on the bootstrap target.  Use multiple --hint options to specify multiple hints.
--prerelease - Install the pre-release chef gems
--bootstrap-version VERSION - The version of Chef to install
--bootstrap-proxy PROXY_URL - The proxy server for the node being bootstrapped
--distro DISTRO - Bootstrap a distro using a template
--template-file TEMPLATE - Full path to location of template to use
--run-list RUN_LIST - Comma separated list of roles/recipes to apply
--secret-file SECRET_FILE - A file containing the secret key to use to encrypt data bag item values
--no-host-key-verify - Disable host key verification
--json-attributes - A JSON string to be added to the first run of chef-client
--disable-customization - Disable default customization

Clones an existing VM template into a new VM instance, optionally applying an existing customization specification.

Customization Plugin Example:

# cplugin_example.rb

class KnifeVspherePlugin
  def data=(cplugin_data)
    # Parse your cplugin_data from the format of your choosing.
  end

  # optional
  def customize_clone_spec(src_config, clone_spec)
    # Customize the clone spec as you see fit.
    return customized_clone_spec
  end

  # optional
  def reconfig_vm(target_vm)
    # Do anything you want in here with the cloned VM.
  end
end

# cplugin_example.rb for cloning a Windows template to VM

require 'rbvmomi'

class KnifeVspherePlugin
  attr_accessor :data

  def customize_clone_spec(src_config, clone_spec)

    if File.exists? data
      customization_data = JSON.parse(IO.read(data))
    else
      abort "Customization plugin data file #{data} not accessible"
    end

    cust_guiUnattended = RbVmomi::VIM.CustomizationGuiUnattended(
      :autoLogon => false,
      :autoLogonCount => 1,
      :password => nil,
      :timeZone => customization_data['timeZone']
    )
    cust_identification = RbVmomi::VIM.CustomizationIdentification(
      :domainAdmin => nil,
      :domainAdminPassword => nil,
      :joinDomain => nil
    )
    cust_name = RbVmomi::VIM.CustomizationFixedName(
      :name => customization_data['host_name']
    )
    cust_user_data = RbVmomi::VIM.CustomizationUserData(
      :computerName => cust_name,
      :fullName => customization_data['fullName'],
      :orgName => customization_data['orgName'],
      :productId => customization_data['windows_key']
    )
    cust_sysprep = RbVmomi::VIM.CustomizationSysprep(
      :guiUnattended => cust_guiUnattended,
      :identification => cust_identification,
      :userData => cust_user_data
    )
    dhcp_ip = RbVmomi::VIM.CustomizationDhcpIpGenerator
    cust_ip = RbVmomi::VIM.CustomizationIPSettings(
      :ip => dhcp_ip
    )
    cust_adapter_mapping = RbVmomi::VIM.CustomizationAdapterMapping(
      :adapter => cust_ip
    )
    cust_adapter_mapping_list = [cust_adapter_mapping]
    global_ip = RbVmomi::VIM.CustomizationGlobalIPSettings
    customization_spec = RbVmomi::VIM.CustomizationSpec(
      :identity => cust_sysprep,
      :globalIPSettings => global_ip,
      :nicSettingMap => cust_adapter_mapping_list
    )
    clone_spec.customization = customization_spec
    puts "New clone_spec object :\n #{YAML::dump(clone_spec)}"
    clone_spec
  end

  def reconfig_vm (target_vm)
    puts "In reconfig_vm method.  No actions implemented.."
  end
end

# json data file

{
    "fullName": "Your Company Inc.",
    "orgName": "Your Company Inc.",
    "windows_key": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx",
    "host_name": "foo_host",
    "timeZone": "100"
}

knife vsphere vm toolsconfig PROPERTY VALUE [–empty]¶ ↑

--empty           - allows clearing string properties

Sets properties in tools property. See "www.vmware.com/support/developer/vc-sdk/visdk25pubs/ReferenceGuide/vim.vm.ToolsConfigInfo.html" for available properties and types.

Examples:

knife vsphere vm toolsconfig myvirtualmachine syncTimeWithHost false
knife vsphere vm toolsconfig myvirtualmachine pendingCustomization -e

knife vsphere vm delete VMNAME [–purge]¶ ↑

Deletes an existing VM, removing it from vSphere inventory and deleting from disk, optionally deleting it from Chef as well.

--purge           - Delete the client and node from Chef as well

knife vsphere vm snapshot VMNAME (options)¶ ↑

--list            - List the current tree of snapshots
--create SNAPSHOT - Create a new snapshot off of the current snapshot
--remove SNAPSHOT - Remove a named snapshot.
--revert SNAPSHOT - Revert to a named snapshot.
--revert-current  - Revert to current snapshot.
--start           - Indicates whether to start the VM after a successful revert

Manages the snapshots for an existing VM, allowing for creation, removal, and reverting of snapshots.

knife vsphere datastore list¶ ↑

Lists all known datastores with capacity and usage

knife vsphere datastore maxfree [–regex]¶ ↑

Gets the datastore with the most free space

--regex           - Pattern to match the datastore name

knife vsphere datastorecluster list¶ ↑

Lists all known datastorecluster with capacity and usage

knife vsphere datastorecluster maxfree [–regex]¶ ↑

Gets the datastorecluster with the most free space

--regex           - Pattern to match the datastore name

knife vsphere vm execute VMNAME COMMAND [ARGUMENTS] –exec-user USER –exec-passwd PASSWD [ –exec-dir DIRECTORY ]¶ ↑

Executes a program on the guest. Requires vCenter 5.0 or higher.

Command path must be absolute. For Linux guest operating systems, /bin/bash is used to start the program. For Solaris guest operating systems, /bin/bash is used to start the program if it exists. Otherwise /bin/sh is used.

Arguments are optional, and allow for redirection in Linux and Solaris.

--exec-user USERNAME - The username on the guest to execute as.
--exec-passwd PASSWD - The password for the user executing as.
--exec-dir DIRECTORY - Optional: Working directory to execute in. Will default to $HOME of user.

knife vsphere vm vmdk add VMNAME SIZE¶ ↑

Adds VMDK to VM.

Optional arguments

--vmdk-type TYPE - VMDK type, "thick" or "thin", defaults to "thin"

knife vsphere vm markastemplate VMNAME –folder FOLDER¶ ↑

Marks a VM as template.

knife vsphere hosts list –pool POOL¶ ↑

Lists all hosts in given Pool

knife vsphere vm migrate VMNAME (options)¶ ↑

Migrate VM to resource pool/datastore/host. Resource pool and datastore are mandatory.

--folder FOLDER                   - folder in which to search for VM
--resource-pool POOL        - destination resource pool
--dest-host HOST            - destination host (optional)
--dest-datastore DATASTORE  - destination datastore, accesible to HOST
--priority PRIORITY         - migration priority (optional, default defaultPriority )

knife vsphere vm net STATE VMNAME¶ ↑

Set networking state for VMNAME by connecting/disconnecting network interfaces. Posible states are up/down.

knife vsphere cpu ratio [CLUSTER] [HOST]¶ ↑

Lists the ratio between assigned virtual CPUs and physical CPUs on all hosts.

knife vsphere cpu ratio
Output:
### Cluster Cluster1 ###
host1.domain.com: 1.8125
host2.domain.com: 2.40625
host3.domain.com: 1.8125

### Cluster Cluster2 ###
host4.domain.com: 1.8125
host5.domain.com: 2.40625

Developing, or using the latest code¶ ↑

The master version of this code may be ahead of the gem itself. If it’s in master you can generally consider it ready to use. To use master instead of what’s published on Ruby gems:

gem uninstall knife-vsphere
git clone git@github.com:ezrapagel/knife-vsphere.git # or your fork
cd knife-vsphere
rake build                                           # Take note of the version
gem install pkg/knife-vsphere-1.0.1.gem              # Use the version above

LICENSE:¶ ↑

Authors: Ezra Pagel <ezra@cpan.org> Jesse Campbell <hikeit@gmail.com> John Williams <john@37signals.com> Ian Delahorne <ian@scmventures.se> Bethany Erskine <bethany@paperlesspost.com> Adrian Stanila <adrian.stanila@sacx.net> Raducu Deaconu <rhadoo_io@yahoo.com> Leeor Aharon

VMware vSphere is a trademark of VMware, 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.

atiniir/knife-vsphere