vsphere

Table of Contents

1. Overview
2. Module Description
3. Support
4. Setup
   • Requirements
   • Installing the vsphere module
   • Getting Started with vSphere
5. Usage
   • List and manage vSphere machines
   • Customize vSphere machines
   • Create linked clones
   • Delete vSphere machines
   • Purge unmanaged virtual machines
6. Reference
   • Types
   • Parameters
7. Limitations
8. Development
9. Known Issues

Overview

VMware vSphere is a cloud computing virtualization platform.

Module Description

The vSphere module allows you to manage vSphere machines using Puppet.

Support

This module is not supported or maintained by Puppet and does not qualify for Puppet Support plans. It's provided without guarantee or warranty and you can use it at your own risk. All bugfixes, updates, and new feature development will come from community contributions. [tier:community]

Setup

Requirements

• Puppet Enterprise 3.7 or greater
• Ruby 1.9 or greater
• Rbvmomi Ruby gem 1.8 or greater
• vSphere 5.5 - 6.7

Installing the vSphere module

The following are dependencies of the module. Install these on the system which you configure the module on. For example, in a server-agent setup, install the dependencies on the agent.

On Debian 7 and 8, Ubuntu 14.04 LTS, and similar

1. Install the required dependencies:

On Debian 7 and 8, Ubuntu 14.04 LTS and similar

apt-get install zlib1g-dev libxslt1-dev build-essential

On RHEL 6 and 7, CentOS, and similar

yum install zlib-devel libxslt-devel patch gc gcc-c++ kernel-devel make

2. Install the required gems with this command:

/opt/puppetlabs/puppet/bin/gem rbvmomi --no-ri --no-rdoc
/opt/puppetlabs/puppet/bin/gem hocon --version='~>1.0.0' --no-ri --no-rdoc

If you are running Puppet Enterprise 2015.2.0 you need to use the updated path:

/opt/puppetlabs/puppet/bin/gem install rbvmomi --no-ri --no-rdoc
/opt/puppetlabs/puppet/bin/gem install hocon --version='~>1.0.0' --no-ri --no-rdoc

Note: Example pins the hocon gem version to prevent possible incompatibilities.

Special Case for RHEL 7.x dervied Docker containers

It may be necessary to install the nokogiri gem first, BEFORE the rbvmomi and hocon gems. It has been observed on RHEL 7.x derived OS Docker containers that the nokogiri gem installation fails if it is installed as part of the dependency resolution for the rbvmomi or hocon gems:

  /opt/puppetlabs/puppet/bin/gem install nokogiri --no-ri --no-rdoc
  /opt/puppetlabs/puppet/bin/gem rbvmomi --no-ri --no-rdoc
  /opt/puppetlabs/puppet/bin/gem hocon --version='~>1.0.0' --no-ri --no-rdoc

Configuring credentials

1. Set the following environment variables specific to your vSphere installation:

   • Required Settings:

   export VCENTER_SERVER='your-host'
   export VCENTER_USER='your-username'
   export VCENTER_PASSWORD='your-password'
   

   • Optional Settings:

   # Whether to ignore SSL certificate errors. Defaults to true.
   export VCENTER_INSECURE='true or false'
   
   # Whether to use SSL. Defaults to true.
   export VCENTER_SSL='true or false'
   
   # Sets vSphere server port to connect to. Defaults to 443(SSL) or 80(non-SSL).
   export VCENTER_PORT='your-port'
   

   Alternatively, you can provide the information in a configuration file. Store this as vcenter.conf in the relevant confdir. This should be:

   • nix Systems: /etc/puppetlabs/puppet
   • Windows: C:\ProgramData\PuppetLabs\puppet\etc
   • non-root users: ~/.puppetlabs/etc/puppet

   The file format is:

   vcenter: {
     host: "your-host"
     user: "your-username"
     password: "your-password"
   }
   

   Or with all the settings:

   vcenter: {
     host: "your-host"
     user: "your-username"
     password: "your-password"
     port: your-port
     insecure: false
     ssl: false
   }
   

   Warning: Usernames that contain a backslash, typically Active Directory domain accounts, must be triple-quoted. For example:

   vcenter: {
     host: "your-host"
     user: """DOMAIN\your-username"""
     password: "your-password"
   }
   

   Note that you can use either the environment variables or the config file. If both are present the environment variables will be used. You cannot have some settings in environment variables and others in the config file.

2. Finally install the module with:

puppet module install puppetlabs-vsphere

Getting started with vSphere

This module allows for describing a vSphere machine using the Puppet DSL. To create a new machine from a template or other machine and keep it powered on:

vsphere_vm { '/opdx1/vm/eng/sample':
  ensure => running,
  source => '/opdx1/vm/eng/source',
}

To create the same machine without booting it, or to boot it at a later time, change the ensure parameter to stopped:

vsphere_vm { '/opdx1/vm/eng/sample':
  ensure => stopped,
  source => '/opdx1/vm/eng/source',
}

To create the same machine on a specific datastore, add the datastore parameter:

vsphere_vm { '/opdx1/vm/eng/sample':
  ensure    => stopped,
  source    => '/opdx1/vm/eng/source',
  datastore => 'datastore1',
}

Usage

List and manage vSphere machines

In addition to creating new machines, as above, this module supports listing and managing machines via puppet resource:

puppet resource vsphere_vm

Note that this outputs some read-only information about the machine, for instance:

vsphere_vm { '/opdx1/vm/eng/sample':
  ensure                      => 'present',
  resource_pool               => 'general1',
  cpu_reservation             => '0',
  cpus                        => '1',
  guest_ip                    => '10.32.99.41',
  hostname                    => 'debian',
  instance_uuid               => '501870f2-f891-879f-2bb7-f87023789959',
  memory                      => '1024',
  memory_reservation          => '0',
  number_ethernet_cards       => '1',
  power_state                 => 'poweredOn',
  snapshot_disabled           => false,
  snapshot_locked             => false,
  snapshot_power_off_behavior => 'powerOff',
  template                    => false,
  tools_installer_mounted     => false,
  uuid                        => '4218419b-3b98-18ca-e77f-93b567dda463',
}

The read-only properties are documented in the reference section below.

Customize vSphere machines

You can customize vSphere machines using the Puppet DSL. Note that customizing a running vSphere machine reboots the machine.

To modify an existing machine:

vsphere_vm { '/opdx1/vm/eng/sample':
  ensure       => present,
  memory       => 1024,
  cpus         => 1,
  extra_config => {
    'advanced.setting' => 'value',
  }
}

Create linked clones

You can also specify that a newly launched machine should be a linked clone. Linked clones share a disk with the source machine.

vsphere_vm { '/opdx1/vm/eng/sample':
  ensure       => present,
  source       => '/opdx1/vm/eng/source',
  linked_clone => true,
}

Delete vSphere machines

You can also delete the machine we created above by setting the ensure property to absent in the manifest or using puppet resouce like so:

puppet resource vsphere_vm /opdx1/vm/eng/garethr-test ensure=absent

To remove only the machine's definition, but leave the underlying configuration and disk files in place, you can set ensure to unregistered:

puppet resource vsphere_vm /opdx1/vm/eng/garethr-test ensure=unregistered

Please note that the module currently provides no mechanism to clean up the files left behind by this operation.

Purge unmanaged virtual machines

If you are using Puppet as the only tool to manage the machines in your vSphere installation, you can have Puppet automatically delete any machines not specified in your manifest. This can be useful if you want to enforce only one way of doing things.

Doing this uses the resources type and the associated purge parameter. This is described in the documentation as follows:

Whether to purge unmanaged resources. When set to true, this deletes any resource that is not specified in your configuration and is not autorequired by any managed resources.

The example below shows this in use. Remember that this deletes all your virtual machines except those described in the same manifest. Do not run the following code on its own.

resources { 'vsphere_vm':
  purge => true,
}

A safer option is to run this with the noop parameter set to true. This won't actually delete the unmanaged machines, but it will tell you about machines it would have deleted. This means you can add them to your manifest or delete them manually as needed.

resources { 'vsphere_vm':
  purge => true,
  noop  => true,
}

This outputs something similar in the logs (this example running under debug):

Debug: Prefetching rbvmomi resources for vsphere_vm
Notice: /Stage[main]/Main/Vsphere_vm[/west1/vm/test]/ensure: current_value running, should be absent (noop)
Debug: Finishing transaction 70211596554260
Debug: Storing state
Debug: Stored state in 0.43 seconds

A note on datacenters

By default, this module uses the default datacenter for your installation. If this fails or if you have multiple virtual datacenters on vSphere, you can specify which datacenter you are managing using the VCENTER_DATACENTER environment variable like so:

export VCENTER_DATACENTER=my-datacenter

This can also be set in the config file as datacenter.

If the datacenter is nested within folders (groups) in vSphere, specify the full path to the datacenter, for example:

export VCENTER_DATACENTER=Australia/Perth/DC1

Reference

For information on the classes and types, see the REFERENCE.md.

Limitations

For an extensive list of supported operating systems, see metadata.json

The vSphere module is only available for Puppet Enterprise 3.7 and later. This module has been tested with vSphere 5.5.

Development

To run the acceptance tests follow the instructions here.

This module was built by Puppet Labs specifically for use with Puppet Enterprise (PE). Puppet modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. To contribute to Puppet projects, see our module contribution guide.

If you run into an issue with this module, or if you would like to request a feature, please file a ticket. If you have problems getting this module up and running, please contact Support.

Known Issues

When using the vSphere module with the Puppet Server, you first need to ensure the module is successfully loaded. Run the Puppet agent on the server node, for instance, with puppet agent -t. If you do not do this, the first, and only the first, run of the vsphere_vm resource fails on the agent with the following error:

Error: Could not retrieve catalog from remote server: Error 400 on	
SERVER: Could not autoload puppet/type/vsphere_vm: Could not autoload	
puppet/provider/vsphere_vm/rbvmomi: no such file to load --	
puppet_x/puppetlabs/prefetch_error on node