Author Archives: rhodges

Introducing vCD CLI: Easy command line administration for vCloud Director

Easy consumption and developer friendliness are hallmarks of the cloud computing revolution.  On the vCloud Director team we know the market demands tools to make it easy for partners to manage clouds based on vSphere and for their customers to consume them.  With this in mind it is our pleasure to introduce vCD CLI, a Python CLI to administer vCloud Director using short, easy-to-remember commands.

vCD CLI derives from Python code developed for vCloud Air, which was based on vCloud Director.  Starting in 2017 our colleague Paco Gomez began to reinvigorate the CLI code to support new vCloud Director versions up through version 9.1, the latest GA release.  CLI code is now divided into two Github projects: vCD CLI and pyvcloud, a Python library for vCloud Director administration. More significantly, Paco enlisted the vCD engineering team to help. Thanks to work by a number of engineers led by Aashima Goel, the vCD CLI covers a substantial chunk of basic administrative operations.  In the process we dropped vCloud Air support and standardized on Python3.  Our goal is quick and easy-to-understand administration on a code base that can evolve rapidly to support new features.

vCD CLI is fully open source and licensed under the Apache 2.0 license. You can install with just a couple of commands on most platforms.  For gory details look at INSTALL.md, which has detailed installation instructions for Mac OS X, Linux, and Windows.  Meanwhile, here’s a typical example of deployment on Ubuntu.

# Install on Ubuntu 16.04 LTS.
sudo apt-get install python3-pip gcc -y
pip3 install --user vcd-cli

Once you have the code installed it’s time to login and start looking around.  vCD CLI has a wealth of commands for showing organizations, VDCs, vApps, catalogs, and the like, which makes it very helpful for navigating vCloud Director installations.  The following example logs in and gets a list of organizations.

$ vcd login vcd-91.test.vmware.com System administrator -i -w
Password: 
administrator logged in, org: 'System', vdc: ''
$ vcd org list
in_use   logged_in   name
-------- ----------- ------
True     True        System
False    False       Test1

As a side note, the preceding example used ‘vcd login’ with -i and -w options.  These suppress errors from self-signed certificates.  You don’t need them if your vCloud Director installation certificate is signed by a public CA.

Once logged in, we can select a particular organization with ‘vcd org use’ and dig down into its resources.  The following example shows commands to list VDCs and vApps.

$ vcd org use Test1
now using org: 'Test1', vdc: 'VDC-A', vApp: ''.
$ vcd vdc list
in_use   name   org
-------- ------ -----
True     VDC-A  Test1
$ vcd vapp list
isDeployed   isEnabled   memoryAllocationMB   name            numberOfCpus   numberOfVMs   ownerName   status      storageKB   vdcName
------------ ----------- -------------------- --------------- -------------- ------------- ----------- ----------- ----------- ---------
true         true                          48 vApp-Tiny-Linux              1             1 system      POWERED_OFF     1048576 VDC-A

Scrolling over a bit we see that our vApp is powered off.  Let’s fix that right away by issuing a power-on command, which is ‘vcd vapp power-on.’  As you can see, vCD CLI commands are hierarchical with the form ‘vcd <entity> [ <subentity> … ] <operation> <arguments>.’  In the case of ‘vcd vapp’ alone there are over 20 commands, so you have a wide range of management operations available.

$ vcd vapp power-on vApp-Tiny-Linux
vappDeploy: Starting Virtual Application vApp-Tiny-Linux(66d7f94f-4bbc-4597-a5fe-70f35b05acfb)
...
vappDeploy: Running Virtual Application vApp-Tiny-Linux(66d7f94f-4bbc-4597-a5fe-task: e88f9ed8-67fe-4d8d-af20-8edb510051c7, 
Running Virtual Application vApp-Tiny-Linux(66d7f94f-4bbc-4597-a5fe-70f35b05acfb), result: success

Speaking of management, being able to set permissions easily on resources like vApps or catalog items is a long-standing request from vCloud Director users.  vCD CLI delivers a solution.  Here’s a simple example of sharing a catalog with the rest of the organization.

$ vcd catalog acl list My-Catalog
subject_name       subject_type   access_level
------------------ -------------- --------------
Test1 (org_in_use) org            None
$ vcd catalog acl share My-Catalog
Catalog shared to all members of the org 'Test1'.
$ vcd catalog acl list My-Catalog
subject_name       subject_type   access_level
------------------ -------------- --------------
Test1 (org_in_use) org            ReadOnly

vCD CLI has even more fine-grained control over ACLs than this example shows.  Run ‘vcd catalog acl -h’ or ‘vcd vapp acl -h’ to see the richness of available commands.  You can also manage rights and roles using ‘vcd right’ and ‘vcd role’.  There’s a lot of power here to do operations that would take far longer going through the vCloud Director GUI.

Speaking of powerful commands, it would be remiss to omit my favorite vCD CLI operation, namely uploading OVA files directly into vCloud Director catalogs. ‘vcd catalog upload’ allows you to skip installation of ovftool and upload using intuitive options. Here’s an example of loading an OVA and starting it as a vApp.

$ vcd catalog upload My-Catalog photon-custom-hw11-2.0-304b817.ova 
upload 113,169,920 of 113,169,920 bytes, 100%
property   value
---------- ----------------------------------
file       photon-custom-hw11-2.0-304b817.ova
size 113207424
$ vcd catalog list My-Catalog
catalogName   entityType   isPublished   name                               ownerName   status   storageKB   vdcName
------------- ------------ ------------- ---------------------------------- ----------- -------- ----------- ---------
My-Catalog    vapptemplate false         photon-custom-hw11-2.0-304b817.ova system      RESOLVED       16384 VDC-A
My-Catalog    vapptemplate false         Tiny-Linux                         system      RESOLVED        1024 VDC-A
$ vcd vapp create Photon-2.0-Vapp \
  --description 'Test vApp' --catalog My-Catalog \
  --template photon-custom-hw11-2.0-304b817.ova \
  --network isolated-network-1 --ip-allocation-mode pool \
  --accept-all-eulas

Finally a quick word about scripting.  vCD CLI commands return standard Unix-style return codes with 0 for success and non-zero for failures. You can embed command in shell scripts and use techniques like the Bash  ‘set -e’ command to terminate automatically on failure.  For example, the following script will exit at the ‘vcd org use’ command if the organization does not exist.

#!/bin/bash
ORG=$1
set -e
vcd login vcd-91.test.vmware.com System administrator -i -w --password='my-pass'
vcd org use ${ORG}
vcd user list

There are so many commands available in vCD CLI that it is not possible to do them justice in a brief article like this one. Instead, have a look at the following documentation sources.

  • CLI help, which is available on all vcd commands.  ‘vcd -h’ shows all commands, ‘vcd vapp -h’ shows all vApp commands, etc.
  • The vCD CLI Site, which has abundant documentation for all commands as well as procedures like installation.
  • The vCD CLI Github project.  The Python3 sources are quite readable.

We are actively working on vCD CLI as well as the underlying pyvcloud library. You can expect to see new features, especially around networking and edge router management.  You may also see a bug or two, as they like to live in new code.  If you do hit a problem just log an issue on GitHub or–even better–fix it yourself in the code and send us a pull request.  The details for both are in CONTRIBUTING.md.

We hope you enjoy using vCD CLI.  Send us feedback and fixes–we look forward to hearing from you!