Skip to content
Chef knife plug-in for VMware REST API
Ruby Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.expeditor Add PR verification with buildkite Oct 10, 2019
spec Update copyrights Nov 28, 2018
.travis.yml Add a code of conduct file Dec 7, 2018 Add a contributing file Nov 28, 2018
LICENSE Rename the license file Nov 28, 2018 Update README for OSS Best Practices Aug 9, 2019
VERSION Bump version to 2.0.6 by Chef Expeditor Oct 12, 2019
knife-vcenter.gemspec Allow for knife-cloud 2.x Oct 10, 2019


Gem Version Build Status Inline docs

Umbrella Project: Knife

Project State: Active

Issues Response Time Maximum: 14 days

Pull Request Response Time Maximum: 14 days

This is the official Chef Knife plugin for VMware REST API. This plugin gives knife the ability to create, bootstrap, and manage VMware vms.

This is a knife plugin that allows interaction with vSphere using the vSphere Automation SDK.

Please refer to the CHANGELOG for version history and known issues.


  • Chef 13.0 higher
  • Ruby 2.3.3 or higher


Using ChefDK, simply install the Gem:

chef gem install knife-vcenter

If you're using bundler, simply add Chef and knife-vcenter to your Gemfile:

gem 'chef'
gem 'knife-vcenter'


In order to communicate with vSphere, you must specify your user credentials. You can specify them in your knife.rb file:

knife[:vcenter_username] = "myuser"
knife[:vcenter_password] = "mypassword"
knife[:vcenter_host] = ""
knife[:vcenter_disable_ssl_verify] = true # if you want to disable SSL checking

or alternatively you can supply them on the command-line:

knife vcenter _command_ --vcenter-username myuser --vcenter-password mypassword

vCenter Permissions

You need the following permissions (at minimum) on your user to be able to use knife-vcenter.

  • Datastore
    • Allocate space ☑️
    • Browse datastore ☑️
  • Host
    • Local Operations
      • Create virtual machine ☑️
      • Delete virtual machine ☑️
      • Manage user groups ☑️
      • Reconfigure virtual machine ☑️
  • Network
    • Assign Network ☑️
  • Resource
    • Assign virtual machine to resource pool ☑️
  • Virtual Machine ☑️


knife vcenter cluster list

Lists the clusters on the connected vSphere environment

$ knife vcenter cluster list
ID           Name     DRS?   HA?
domain-c123  Cluster  False  False

knife vcenter datacenter list

List the data centers configures in the vSPeher environment

$ knife vcenter datacenter list
ID             Name
datacenter-21  Datacenter

knife vcenter host list

List the hosts in the vSphere in the vSphere environment

$ knife vcenter host list
ID       Name          Power State  Connection State

knife vcenter vm list

List out all the virtual machines that exist in the vSphere environment

$ knife vcenter vm list
ID      Name                             Power State  CPU Count  RAM Size (MB)
vm-42   alpine-docker                    POWERED_OFF  1          4,024
vm-35   automate-ubuntu                  POWERED_OFF  1          4,096
vm-44   chef                             POWERED_OFF  1          4,096
vm-33   chef-automate                    POWERED_OFF  1          4,096
vm-34   chef-buildnode                   POWERED_OFF  1          4,096
vm-43   chef-compliance                  POWERED_OFF  1          4,096
vm-71   CyberArk                         POWERED_OFF  1          8,192
vm-45   jenkins                          POWERED_ON   4          8,096
vm-36   LFS                              POWERED_OFF  2          4,096

knife vcenter vm show NAME

Display details about a specific virtual machine.

$ knife vcenter vm show chef
ID: vm-44
Name: chef
Power State: POWERED_OFF

The IP address of the machine is not returned yet as this requires a call to a different SDK

knife vcenter vm clone NAME

Create a new machine by cloning an existing machine or a template. This machine will be bootstrapped by Chef, as long as all the relevant details are in the knife.rb file.

The following parameters are required:

  • --datacenter - Datacenter in the vSphere environment that controls the target host
  • --template - Name of the virtual machine or template to use

There are some optional parameters that can be specified:

  • --targethost - The host that the virtual machine should be created on. If not specified the first host in the cluster is used.
  • --folder - Folder that machine should be stored in. If specified this must already exist.
  • --pool - Name of resource pool to use when creating the machine
  • --disable_power_on - Do not power on the machine. Default: false
$ knife vcenter vm clone example-01 --targethost --folder example --ssh-password P@ssw0rd! --datacenter Datacenter --template ubuntu16-template -N example-01
Creating new machine
Waiting for network interfaces to become available...
ID: vm-183
Name: example-01
Power State: POWERED_ON
Bootstrapping the server by using bootstrap_protocol: ssh and image_os_type: linux

Waiting for sshd to host (

knife vcenter vm delete NAME

Deletes a virtual machine from vSphere. If you supply --purge the machine will be removed from the Chef Server.

NOTE: If the node name is different to the host name then the -N argument must be specified in conjunction with the --purge option

$ knife vcenter vm delete example-01 -N example-01 --purge
Creating new machine
Waiting for network interfaces to become available...
ID: vm-183
Name: example-01
Power State: POWERED_ON
Bootstrapping the server by using bootstrap_protocol: ssh and image_os_type: linux

Waiting for sshd to host (
WARNING: Deleted node example-01
WARNING: Deleted client example-01


For information on contributing to this project see


  • Report issues/questions/feature requests on [GitHub Issues][issues]

Pull requests are very welcome! Make sure your patches are well tested. Ideally create a topic branch for every separate change you make. For example:

  1. Fork the repo
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Run the tests and rubocop, bundle exec rake spec and bundle exec rake rubocop
  4. Commit your changes (git commit -am 'Added some feature')
  5. Push to the branch (git push origin my-new-feature)
  6. Create new Pull Request


Author:: Russell Seymour (

Author:: JJ Asghar (

Copyright:: Copyright (c) 2017-2018 Chef Software, 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

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.
You can’t perform that action at this time.