VMware: Using the govc CLI to automate vCenter commands


Categories: Linux, Virtualization

The vSphere web GUI is a nice visual tool, but if you need to retrieve vCenter information in bulk or perform mass operations across VMs, then a command line tool such as govc in invaluable.

govc is written in Go, which means it has support on Linux as well as most other platforms.

Installation

Identity the latest release on releases page for govc. Then install on Linux using these commands:

# donwload and unzip
wget https://github.com/vmware/govmomi/releases/download/v0.20.0/govc_linux_amd64.gz
gunzip govc_linux_amd64.gz

# rename
mv govc_linux_amd64 govc
sudo chown root govc
sudo chmod ug+r+x govc
sudo mv govc /usr/local/bin/.

# validate in path
which govc
# validate version
govc version

Basic Connectivity

Export a set of environment variables so the CLI knows how to connect to vCenter:

# vCenter host
export GOVC_URL=myvcenter.name.com
# vCenter credentials
export GOVC_USERNAME=myuser
export GOVC_PASSWORD=MyP4ss
# disable cert validation
export GOVC_INSECURE=true

And now try the most basic commands:

$ govc about
Name:         VMware ESXi
Vendor:       VMware, Inc.
Version:      6.7.0
Build:        8169922
OS type:      vmnix-x86
API type:     HostAgent
API version:  6.7
Product ID:   embeddedEsx
UUID

$ govc datacenter.info
Name:                mydc
  Path:              /mydc
  Hosts:             1
  Clusters:          0
  Virtual Machines:  3
  Networks:          1
  Datastores:        1

$ govc ls
/mydc/vm
/mydc/network
/mydc/host
/mydc/datastore

# set variable 'dc' so we can use it later
$ dc=$(govc ls /)

Network

govc ls -l=true $dc/network

ESXi Cluster

# cluster name
govc ls $dc/host
# details on cluster, all members and their cpu/mem utilization
govc host.info <clusterPath>

# all members listed (type: HostSystem, ResourcePool)
govc ls -l=true <clusterPath>
# for each cluster member of type HostSystem, individual stats
govc host.info <memberPath>

Datastores

# top level datastores (type: Datastore and StoragePod)
govc ls -l=true $dc/datastore

# for atomic Datastore type, get capacity
govc datastore.info <datastorePath>

# get StoragePod overall utilization
govc datastore.cluster.info <storagePodPath>
# get list of storage pod members
govc ls <storagePodPath>
# then get capacity of each member
govc datastore.info <storagePodMemberPath>

Get VM information

Now search for a VM by name, get a summary of the VM details, then full VM details.

# show basic info on any VM names that start with 'myvm'
govc vm.info myvm*

# show basic info on single VM
govc vm.info myvm-001

# use full path to get detailed VM metadata
vmpath=$(govc vm.info myvm-001 | grep "Path:" | awk {'print $2'})
govc ls -l -json $vmpath

Shutdown VM, power up VM

# gracefully shutdown guest OS using tools
govc vm.power -s=true myvm-001
# force immediate powerdown
govc vm.power -off=true myvm-001 

# power VM back on
govc vm.power -on=true myvm-001

 

REFERENCES

govmomi command usage

example usage from deadline.top

example usage from prefetch.net

upload Ubuntu ISO to filestore

handling vSphere events using govmomi and golang

example golang code from orchestration.io

govc to import OVA

gswallow, govc and object.collect and json

NOTES

view all ‘Managed Object Properties’

govc find -type m
# in list
govc object.collect '/mydc1/vm/Discovered virtual machine/ubuntu-focal'

# in json format
govc object.collect -json '/mydc1/vm/Discovered virtual machine/ubuntu-focal'

Get versions of all ESXi hosts in cluster

# define datacenter and cluster
dc=mydc1
cluster=mycluster1

# loop through each esxi host in cluster and grab version
for hostpath in $(govc ls /$dc/host/$cluster | grep -v Resources); do
  govc host.info -json=true $hostpath | jq '.HostSystems[].Summary.Config.Product.Version' -r
done

Get versions and maintenance mode for each ESXi host in cluster

# define datacenter and cluster
dc=mydc1
cluster=mycluster1

# brief output of each ESXi host in cluster
govc host.info /$dc/host/$cluster/*

# pull out full detail of version and maintenance mode using jq
govc host.info -json /$dc/host/$cluster/* | jq '.HostSystems[] | [.Summary.Config.Name, .Summary.Config.Product.Version .Runtime.InMaintenanceMode] | @tsv' -r | sort

Upload ISO into datastore

# get list of datacenters
govc ls
# show details of datacenter
my_dc=/mydc
govc datacenter.info $my_dc

# get list of datastores
govc ls /$my_dc/datastore
my_datastore=/$my_dc/datastore/x/y

# upload ISO directly into datastore
my_iso=ubuntu-22.04.1-live-server-amd64.iso
govc datastore.upload --dc=$my_dc --ds=$my_datastore $my_iso $my_iso

Export template as OVA

# overwrite (-f), write images (-i) exported to folder with name of vm
govc export.ovf -f=true -i=true -dc=$dc -vm $vm_name .

Import OVA as template

# show folders
govc find / -type f

# create vcenter folder for templates
folder=/mydc1/vm/templates
govc folder.create $folder

# upload local OVA and mark as template
govc import.ova -folder=templates -options - my.ova <<EOF
{
"DiskProvisioning": "thin",
"MarkAsTemplate": true
}
EOF

Specify custom CA certificate for vCenter

# download and extract vCenter certs
wget https://$GOVC_URL/certs/download.zip --no-check-certificate
unzip download.zip

# pick CA cert
ls -l certs/lin
ca_cert="certs/lin/xxxxxxx"

export GOVC_INSECURE=false
govc ls --tls-ca-certs=$ca_cert

mark as VM or template

dc=mydc1
folder=/${dc}/vm/templates
vm=testvm
template_vm="${folder}/${vm}"

# ensure powered off
govc vm.power -off $template_vm

# mark as template in vcenter
govc vm.markastemplate $template_vm

# mark back as VM in vcenter, need to specify esx host and datacenter
esxhost=$(govc vm.info $template_vm | grep 'Host:' | awk '{print $2}')
govc vm.markasvm -host=$esxhost -dc=$dc $template_vm