Manage virtual machine client notes

The VSS CLI allows “client custom notes” to be added to the virtual machine annotation field with a maximum of 500 characters long. Client notes are useful to add reminders, codes or any particular metadata that is different from the VSS Metadata such as admin, client, etc.

This example demonstrates how to create a virtual machine with given client notes, list and update client notes to an existing virtual machine.

Deploy virtual machine

In order to launch a new virtual machine, we will use the following parameters:

Operating system: OS=centos64Guest
Network: NET=dvportgroup-11052
Folder: FOLDER=group-v6736
ISO image: ISO='[vss-ISOs] Linux/CentOS/CentOS-7.0-1406-x86_64-Minimal.iso'
Name: NAME=Frontend-1
Notes: NOTES="Project: Enterprise CMS\nToDo: Backup, Recovery"

Multi-line strings are handled differently by shells.

Run vss-cli compute vm mk shell to deploy a virtual machine without an operating system installed. Before deploying the virtual machine, display what options and arguments the shell command takes:

vss-cli compute vm mk shell --help

Usage: vss-cli compute vm mk shell [OPTIONS] NAME

  Create a new virtual machine with no operating system pre-installed.

Options:
  -d, --description TEXT          A brief description.  [required]
  -b, --client TEXT               Client department.  [required]
  -a, --admin TEXT                Admin name, phone number and email separated
                                  by `:` i.e. "John
                                  Doe:416-123-1234:john.doe@utoronto.ca"

  -r, --inform TEXT               Informational contact emails in comma
                                  separated

  -u, --usage [Test|Prod|Dev|QA]  Vm usage.
  -o, --os TEXT                   Guest operating system id.  [required]
  -m, --memory INTEGER            Memory in GB.
  -c, --cpu INTEGER               Cpu count.
  -f, --folder TEXT               Logical folder moref name or path.
                                  [required]

  -i, --disk INTEGER              Disks in GB.  [required]
  -n, --net TEXT                  Network adapter <moref-or-name>=<nic-type>.
                                  [required]

  -t, --domain TEXT               Target fault domain name or moref.
  --notes TEXT                    Custom notes.
  -s, --iso TEXT                  ISO image to be mounted after creation
  -h, --high-io                   Use VMware Paravirtual SCSIController.
  -e, --extra-config TEXT         VMWare Guest Info Interface in JSON format.
  --power-on                      Power on after successful deployment.
  --vss-service TEXT              VSS Service related to VM
  --instances INTEGER             Number of instances to deploy  [default: 1]
  --help                          Show this message and exit.

Now that we have everything, proceed to deploy a new virtual machine with 1GB of memory, 1 vCPU, 20GB disk and a tag Project:CMS as follows:

vss-cli compute vm mk shell --description 'NGINX web server' --client EIS --os centos \
--memory 1 --cpu 1 --folder TargetFolder --disk 20 --net Public --iso centos --notes "Project:CMS" \
Frontend-1

In matter of seconds, a confirmation email will be sent with the allocated IP address, if VL-1584-VSS-PUBLIC was selected.

List Client Notes

Optional Obtain the new UUID by either listing and filtering virtual machines in your inventory vss-cli compute vm ls --filter-by name=Front or listing your new requests vss-cli request new ls -s created_on desc. The following command illustrates how to list virtual machines with the front string in their names:

This version of the VSS CLI supports managing virtual machines not only using the UUID, but using names. In case of multiple results, the CLI prompts to select the right instance.

vss-cli compute vm ls -f name=Front

moref    name              folder.path                  cpu_count    memory_gb  power_state    ip_address
-------  ----------------  -------------------------  -----------  -----------  -------------  ------------
vm-2182  2004T-Frontend-1  VSS > Development > Dev03            1            1  poweredOff

To query existing virtual machine client-note use the vss-cli compute vm get <uuid> client-note command as follows:

vss-cli compute vm get Frontend1 client-note

value               : Project:CMS

Update Client Notes

In order to update or replace existing client notes, use vss-cli compute vm set <uuid> client-note <new-note> to append or use the flag --replace to overwrite all notes.

vss-cli compute vm set Frontend1 client-note "Billing Code: 1234"

And query to validate any change:

vss-cli compute vm get Frontend1 client-note

value               : Project: Enterprise CMS
                      ToDo: Backup, Recovery
                      Billing Code: 1234

If you wanted just to replace existing contents, add the --replace/-r option to the command as follows:

vss-cli compute vm set Frontend1 client-note --replace "Billing Code: 1234"

And query to validate any change:

vss-cli compute vm get Front_end_1 client-note

Value               : Billing Code: 1234