Skip to content

VMware Library

The Vmware Library provides additional content that enables capabilities for interacting with VMware ESXi, vSphere, and VCF (VMware Cloud Foundation) environments.

This content provides Software Defined Data Center (SDDC) build and operational management workflows.

Some examples of operations that can be achieved with this workflow:

  • create custom ESXi ISOs from Offline Bundle (OLB) depots
  • deploy vCenter on one or more ESXi nodes
  • create a Datacenter construct in vCenter
  • create a Cluster construct in vCenter
  • enroll specified ESXi machines in to the Cluster
  • configure VSAN datastore capabilities
  • claim disks in to the VSAN datastore
  • deploy arbitrary OVA appliance devices
  • deploy VMware Cloud Foundations VCF clusters via Cloud Builder deployed OVA

  • create and manage other vSphere/vCenter related resources, like:

    • Virtual Switches and Distributed Virtual Switches (DVS/vDS)
    • Portgroup create/destroy/management
    • Rename objects in vCenter inventory
    • Guest Virtual Machine management
    • Pools, Roles, Sessions, Snapshot management
    • Any govc (GoVMOMI library) based commands, documented at: https://github.com/vmware/govmomi/blob/master/govc/USAGE.md

This content pack utilizes Digital Rebar Provision (DRP) Context containers to perform most of the heavy lifting work. For general use, start by creating a Context Machine (Machine that is backed by a Context / BaseContext), to utilize the tooling to execute API actions against the vSpher/VCF target(s).

It is recommended to create a Context container that correlates to a given resource that is being managed. This allows for ongoing lifecycle management of the managed service.

It is possible to move many of the functions in to WorkOrders and Blueprints, however, this work has not been done in the vmware-lib content pack yet.

There are several tools which are available and used, based on the tools capabilities, and the required job at hand:

  • govc - a Golang compiled binary which implements the GoVMOMI library
  • VMware's Python SDK
  • VMware's Ansible Galaxy modules, which utilize PyVMOMI and Python SDK libraries
  • OVFTool
  • etc.

All of the content provided in vmware-lib builds upon, and requires the vmware plugin to be installed, and generally relies on ESXi nodes to be built by a workflow like the esxi-install workflow. It is feasible that setting the appropriate Param values will allow this content to work on non-DRP built ESXi nodes; however this is not tested nor advised.

The govc context container is well suited for managing ongoing operations (in addition to initial creation operations). The only primary downside to use of the govc binary and API interactions is related to the poor and inconsistent exit code handling of the various different sub-commands.

Prerequisites

The following prerequisites must be met to support the vmware-lib capabilities. Note that this is in addition to the necessary VMware vSphere/VCF/vCenter infrastructure that is being automated and orchestrated.

  • DRP Endpoint version v4.8.0 or newer
  • DRP Community Content v4.8.0 or newer
  • VMware Plugin v4.8.0 or newer
  • VMware Library (vmware-lib) v4.8.0 or newer
  • the govc context installed and bootstrapped (1)
  • the vmware-tools context installed and bootstrapped (1)

Note 1: Both context containers should be installed and tested (eg run the hello-world workflow in a test Machine backed by the Context). Please see Install Context Containers with 'drpcli' for instructions on how to ensure the Context containers are installed and working.

GoVC General Information

GoVC is a Golang binary that implements the VMOMI library of capabilities. The primary benefit is it's a single statically compiled binary (stand alone) that has no external dependencies. It implements API interaction with vSphere and services (eg vSphere ESXi, vSphere vCenter, VMWare Cloud Foundations/VCF).

The GoVC binary (govc) is compiled from the GoVMOMI project, which can be found at:

The GoVC tool is capable of an extremely broad and complete set of control plane interactions with vSphere (ESXi and vCenter) services. Please review the examples directory in the above referenced Repo for more details.

For usage examples of the govc binary in use inside the govc context container, please see:

Context Usage

The vmware-lib tooling utilizes two primary Context containers that have the embedded VMware tooling in them. They are:

  • govc: lightweight container with just govc binary (based on GoVMOMI library)
  • vmware-tools: big fat bloated container with everything and the kitchen sink

Both context containers implement a RackN Context with the Agent (runner, drpcli binary) and the associated binaries and libraries in them. By use of setting Param values, govc commands can be executed against vSphere resources.

Please see Install Context Containers with 'drpcli' for setup instructions. Ensure that the govc and vmware-tools Contexts are fully installed based on these instructions.

Creating Custom ESXi ISOs from Offline Bundle (OLB) Depots

The vmware-lib Content Bundle also provides operators the ability to take VMware Offline Bundle (OLB) depots, add VIBs (modules) to the Bundle, and generate a new Custom ESXi installable ISO.

The process uses a DRP Machine backed by the vmware-tools Context Container, along with a Blueprint to build new ISOs. Configuration is provided by Params placed on the builder machine; typically grouped in a Profile for convenience.

More than one OLB Depot can be built in a single pass, and one or more VIB/Modules can be installed in all of the defined OLB Depots. The resulting output will be saved on the DRP Endpoint that is managing the builder machine. The objects created include:

  • Custom ESXi installable ISOs, saved to the DRP ISOs API/file location
  • New OLB Depots for each Custom ISO tha this built with the new VIB/Modules in them
  • A Digital Rebar Platform (DRP) Profile for each ISO that contains the necessary bootenv-customize definition for installation

To use this capability a Blueprint has been created that will build a new Machine that is set to use the vmware-tools context container for it's runner, along with the EXAMPLE profile cloned and saved on the Machine object.

Follow these steps to create and use this capability:

  • On the "Self Runner" Machine, run the Blueprint named esxi-build-isos-create-builder-machine (optionally set the Param esxi-build-isos/builder-machine-name to rename the Machine from the default of esxi-isos-builder)
  • Modify the Profile on the newly built Machine - review each of the Params documentations field for further details
  • Run the Blueprint esxi-build-isos-from-bundles on the newly created ESXi ISOs Builder machine
  • Observe the Job Log output for details on the created assets locations

Note that if continual runs of the Blueprint occur, there may be a large build up of OLB Depots saved to the Files server space of the DRP Endpoint. You may want to clean these up.

This feature requires the following versions of DRP components:

  • vmware-lib content bundle version v4.15.0 or newer
  • vmware plugin version v4.15.0 or newer
  • vmware-tools Context container runner v1.2.18 or newer installed (defined in vmware-lib v4.15.0)

To update the vmware-tools Context Container version, ensure that the vmware Plugin and vmware-tools content bundles as defined above are installed on your DRP Endpoint. Also ensure that you have a "Self Runner" Machine (a Machine with the same name as your DRP Endpoint) created.

Add the Profile bootstrap-vmwarelib to the Self Runner machine, then run the Work_Order rebootstrap-drp or the universal-bootstrap Workflow. To verify the Context Container version, login to the Context Container Machine:

UUID="<UUID_of_the_created_Machine_for_creating_Custom_ISOS>"
# from the DRP Endpoint host operating system shell:
CTR="<docker-or-podman>"
$IMG=$($CTR ps | grep $UUID | cut -f 1)
$CTR exec -it $IMG /bin/bash

and cat /etc/rackn-context-release.

If not rackn-context-release file exists, your container image is woefully out of date. Otherwise, you should see something similar to:

# RackN context container build information
RACKN_CONTEXT_VERSION=v1.2.18
RACKN_CONTEXT_NAME=vmware-tools-runner
RACKN_CONTEXT_BUILD_DATE=Thu Mar 20 03:41:31 PM UTC 2025

Some very important notes about the operation of the ISO create process to be aware of:

Warning

  • created Custom ISOs will upload and overwrite ISOs of the same name without warning
  • you can prefix the build time ISO, depot, and profile names with the esxi-build-isos/bootenv-override param to get a custom named set of objects
  • if a Profile is created that exists on the DRP Endpoint already, then it will be removed if it is RW (ReadOnly: false) and replaced with the new on
  • if the newly created Profile exists on other Objects (eg assigned to a Machine), the Task WILL FAIL as it can not be removed; remove the in use Profiles first, then rerun the build operations
  • multiple operational runs of the build process may produce a lot of OLB Depot (software bundles) in the Files server space defined by the Param esxi-build-isos/upload-bundle-path
  • the Depots can be deleted/removed if not needed for building additional ISOs from the newly generated depot, set the Param to an empty value to prevent uploading them to DRP
  • the vmware Plugin Provider must be updated to v4.15.0 or newer for the newly enhanced build_iso.ps1 PowerShell/PowerCLI script, an alternate location can be specified with the Param

GoVC and VCSA Deployment

VCSA (vCenter Server Appliance) can be deployed via the GoVC tool. The operator must perform the following preparotry tasks to enable the Context environment to operate the govc binary in the RackN Context Container. This setup must be performed on the DRP Endpoint. In the future, the bootstrap workflows will be available to help set up these environments.

Setup Instructions

  • The VCSA OVA must be staged on an HTTP server for the tooling to download

    • Obtain the VMware provide VCSA ISO image and extract the OVA from the ISO
    • example download location - https://my.vmware.com/web/vmware/details?productId=742&rPId=39682&downloadGroup=VC67U3B
    • can be extracted with bsdtar like: bsdtar -xvf VMware-VCSA-all-6.7.0-15132721.iso vcsa/*.ova
    • upload with drpcli like: export N=$(ls -1 vcsa/*.ova); drpcli files upload $N as images/vcsa/$N
    • reference this location on the DRP endpoint as: {{.ProvisionerURL}}/files/images/vcsa/{...name...}

  • Prepare the Template JSON file that GoVC will use to deploy the OVA (see below)

  • Set the Param values on your Runner fake machine (either directly. or as a Profile)
  • Run the Workflow govc-vcenter-create

Scripts referenced in this document should be available from:

Use of govc/debug Param

The govc/debug Param can be set to add more logging output to Jobs Logs, without setting the rs-debug-enable, which can be a lot of debugging. Not all tasks support enhanced Job Log output via govc/debug, but many do.

Warning

In many cases, username and password values WILL BE revealed in Job Logs when govc/debug is set. This allows password credential debugging in those cases. Care must be taken when using this feature.

vCenter Complete Note

If install vCenter 7.x - the govc connect URL method seems to have changed. AS of 2020/07/01 - the Stage govc-wait-for-vcenter will not complete successfully. You will have to monitor the VAMI web interface (on port 5480 by default), to determine when it has successfully finished.

The workflow will error out after 60 minutes in this case. Either force remove the Workflow from the Context Machine, or ignore the status stage error.

Prepare the VCSA JSON Deployment Param

The Param ova/param-json provides the JSON data configuration used during the OVA deployment process, to configure the OVA. See the Profile EXAMPLE-govc-vcsa-vc01.yaml examples in the vmware-lib content pack for an example template.

Once you have prepared the Template JSON file and uploaded it, you must set the Param to point to it. This param will be set on the Context Runner Machine that the Workflow is run on.

In addition to the Template JSON Param, you must provide a vSphere resource (eg ESXi) node to execute the deployment to. Set these Params as defined in the below section.

Define the Deployment Target

You must define the vSphere deployment target (eg ESXi node) to deploy the VCSA OVA to. This is done by specifying the URL directly as a single Param, or the individual Param values for the Username, Password, Node, and optionally Port. See the Param documentation for these values.

These values can all be combined in to a single Profile along with the Template JSON Param defined above for easier add/remove on the Machine object.

Example Profile for vCenter deployment:

---
Name: "vcsa-govc-esxi-ewr1"
Description: "EXAMPLE PROFILE - CHANGE VALUES !!!!"
Documentation: |
  Change these values to match the JSON template details, the
  uploaded OVA, and related network information for your vCenter
  deployment.

  govc/* params are for the target Node (vSphere ESXi) to deploy the
  vCenter VCSA OVA on.  The JSON Template defines the vCenter
  installation details.

Meta:
  color: "blue"
  icon: "hdd"
  title: "Digital Rebar"
Profiles: []
Params:
  govc/datastore: "datastore1"
  govc/datastore-skip-create: false
  govc/insecure: true
  govc/node: "10.75.75.250"
  govc/ova-location: "{{.ProvisionerURL}}/files/images/vcsa/VMware-vCenter-Server-Appliance-7.0.0.10300-16189094_OVF10.ova"
  govc/username: "root"
  govc/password: "VMware123"
  ova/param-json: |
    ...JSON data structure here...
    ...see profiles/EXAMPLES-govc-vcsa-vc01.yaml for an example...

Save the above to file, and use drpcli to add to your Endpoint (eg drpcli profiles create vcenter.yaml, then add the Profile to the Context Machine that will deploy the vCenter VCSA OVA.

Example GOVC Usage

A (begining of) a collection of useful resources for understanding how to use govc to manage vSphere resources.

VCF Cloud Builder cluster bootstrap

This content supports VMware Cloud Foundations (VCF) bootstrap bringup via use of the Cloud Builder virtual machine appliance. The process is generally tackled with the following content components:

  • operator must construct a valid bringup.json spec file for the final VCF cluster build
  • construct the appropriate govc/* Params, and JSON Template config for the Cloud Builder deployment
  • deploy the Cloud Builder OVA with the esxi-sddc-ovftool-deploy workflow to an ESXi host
  • start the bootstrap process of the VCF cluster with esxi-sddc-manage workflow, see the Task of the same name for supported Operations (eg about, validate, create, create_retry, etc)

The following example content esists to help guide with this process:

  • Profile EXAMEPLE-vcf-sddc-cloud-builder.yaml - contains Cloud Builder OVA deployment and operation config
  • Templates EXAMPLE-gamble-vcf-bringup.json.tmpl - VCF Cluster bringup JSON spec