NAME

puppet-node_vmware - View and manage VMware vSphere virtual machine nodes.

SYNOPSIS

puppet node_vmware action

DESCRIPTION

This subcommand provides a command line interface to work with VMware vSphere virtual machine instances. The goal of these actions is to easily create new virtual machines, start and stop them, and clean up when they're no longer required. After creating new nodes, you can use the node subcommand's install, classify, and init actions to bring them into your Puppet infrastructure.

To use this subcommand, you must include four configuration options in your ~/.fog file: A vCenter user account, a password, a server hostname, and the hash digest of the vCenter server's SSL public key. (See below for the exact names of the settings.) Puppet will display the public key digest the first time you connect to vCenter if the setting is omitted from the configuration file.

The following is an example of ~/.fog configured with an "API" access account.

:default:
  :vsphere_server: vcenter.example.lan
  :vsphere_username: api_user
  :vsphere_password: sekret
  :vsphere_expected_pubkey_hash: 431dd5d0412...

OPTIONS

Note that any configuration parameter that's valid in the configuration file is also a valid long argument, although it may or may not be relevant to the present action. For example, server is a valid configuration parameter, so you can specify --server <servername> as an argument.

See the configuration file documentation at http://docs.puppetlabs.com/references/stable/configuration.html for the full list of acceptable parameters. A commented list of all configuration options can also be generated by running puppet with --genconfig.

--mode MODE

The run mode to use for the current action. Valid modes are user, agent, and master.

--render-as FORMAT

The format in which to render output. The most common formats are json, s (string), yaml, and console, but other options such as dot are sometimes available.

--verbose

Whether to log verbosely.

--debug

Whether to log debug information.

ACTIONS

create - Create a new VM from a template

SYNOPSIS

puppet node_vmware create --name= | -n= --template= | -t= [--wait | -w] [--wait-for-boot | -i] [--timeout=]

DESCRIPTION

This action creates a new virtual machine by cloning an existing VMware VM marked as a template.

OPTIONS

--name= | -n= - The name of the new VM to create. This name must be unique within the folder containing the source VM or template.

--template= | -t= - The path of the VMware virtual machine template to clone. A full path to the template is expected in the same format as displayed from the list action.

--timeout= - The maximum number of seconds to wait for API calls to complete. Many of the API calls may take considerable time to run. If not specified, this defaults to 600 seconds.

--wait | -w - If this option is specified then Puppet will wait for the VMware copy operation to finish. This could be a lengthy process but provides the ability to reliably wait until the VM has finished cloning before moving on.

--wait-for-boot | -i - If this option is specified then Puppet will wait for the VMware copy to finish and the VM to boot and obtain an IP address on the network. This requires the VMware Tools installed in the guest VM. This option implies the --wait option.

RETURNS

Hash containing attributes about the new virtual machine.

find - Find a VMware virtual machine

SYNOPSIS

puppet node_vmware find [--timeout=] path

DESCRIPTION

Find a single VMware virtual machine by path. The default output of the find action provides a limited set of information. To obtain all available attributes for a virtual machine, please use a different rendering mode such as --render-as yaml.

OPTIONS

--timeout= - The maximum number of seconds to wait for API calls to complete. Many of the API calls may take considerable time to run. If not specified, this defaults to 600 seconds.

RETURNS

Array of virtual machine attribute hashes.

list - List VMware virtual machines

SYNOPSIS

puppet node_vmware list [--folder= | -f=] [--timeout=]

DESCRIPTION

List VMware virtual machines in all Datacenters. This command may take considerable time to run in large VMware environments.

The default output of the list action provides a limited set of information. To obtain all available attributes for each virtual machine, please use a different rendering mode, such as --render-as yaml.

OPTIONS

--folder= | -f= - This option limits the listing of virtual machines to a single folder, which is much faster than listing all virtual machines in the entire inventory.

--timeout= - The maximum number of seconds to wait for API calls to complete. Many of the API calls may take considerable time to run. If not specified, this defaults to 600 seconds.

RETURNS

Array of virtual machine attribute hashes.

start - Start a virtual machine

SYNOPSIS

puppet node_vmware start [--timeout=] path

DESCRIPTION

This action starts a stopped virtual machine. This is also known as powering on the virtual machine.

OPTIONS

--timeout= - The maximum number of seconds to wait for API calls to complete. Many of the API calls may take considerable time to run. If not specified, this defaults to 600 seconds.

RETURNS

Hash containing the VM's status

stop - Stop a running virtual machine

SYNOPSIS

puppet node_vmware stop [--force] [--timeout=] path

DESCRIPTION

This action stops a running virtual machine. By default, the guest operating system will be gracefully shut down using VMware Tools.

OPTIONS

--force - Forcibly power off the virtual machine without giving the guest operating system a chance to gracefully shut down.

--timeout= - The maximum number of seconds to wait for API calls to complete. Many of the API calls may take considerable time to run. If not specified, this defaults to 600 seconds.

RETURNS

Hash containing the VM's status

terminate - Terminate (destroy) a VM

SYNOPSIS

puppet node_vmware terminate [--timeout=] path

DESCRIPTION

This action terminates a virtual machine. This is a destructive action that will forcibly shut down a VM if it's running and then delete it from the VMware inventory and datastore. Only carry out this action on VMs you want to permanently delete. The VM hard disk images WILL BE DELETED.

OPTIONS

--timeout= - The maximum number of seconds to wait for API calls to complete. Many of the API calls may take considerable time to run. If not specified, this defaults to 600 seconds.

RETURNS

Hash containing the VM's status

EXAMPLES

create

$ puppet node_vmware create --name jefftest --template /Datacenters/Solutions/vm/el56

find

Get info about a specific VM:

$ puppet node_vmware find /Datacenters/Solutions/vm/el56
/Datacenters/Solutions/vm/el56
  powerstate: poweredOff
  name:       el56
  hostname:   --------
  instanceid: 50323f93-6835-1178-8b8f-9e2109890e1a
  ipaddress:  ---.---.---.---
  template:   true

list

List all VMs in the entire inventory:

$ puppet node_vmware list
/Datacenters/Solutions/vm/centos5-01
  powerstate: poweredOff
  name:       centos5-01
  hostname:   centos5.example.vm
  instanceid: 503271e5-2cc4-1f1a-4303-75d33938fcf4
  ipaddress:  ---.---.---.---
  template:   false

/Datacenters/Solutions/vm/el56
  powerstate: poweredOff
  name:       el56
  hostname:   --------
  instanceid: 50323f93-6835-1178-8b8f-9e2109890e1a
  ipaddress:  ---.---.---.---
  template:   true

List only the VMs in the Templates folder:

$ puppet node_vmware list --folder=/Datacenters/DC1/vm/Templates
/Datacenters/Solutions/vm/Templates/el56template
  powerstate: poweredOff
  name:       el56template
  hostname:   --------
  instanceid: 09CB9D9B-2498-41E0-807A-382408829C07
  ipaddress:  ---.---.---.---
  template:   true

start

$ puppet node_vmware start /Datacenters/MyDC/vm/jefftest

stop

$ puppet node_vmware stop /Datacenters/MyDC/vm/jefftest --force

terminate

$ puppet node_vmware terminate /Datacenters/MyDC/vm/jefftest

COPYRIGHT AND LICENSE

Copyright 2011 by Puppet Labs Puppet Enterprise Software License Agreement