27.45. vmware-lib - VMware Library

The following documentation is for VMware Library (vmware-lib) content package at version v4.3.0.

27.45.1. VMware Library

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

27.45.1.1. 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 ESXi and vCenter).

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.

27.45.1.1.1. GoVC Context

The GoVC context implements a RackN Context Container with the Agent (runner, drpcli binary) inside of it. By use of setting Param values, govc commands can be executed against vSphere resources.

27.45.1.1.2. 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.

  • Install the “Docker (OCI) Execution Context” (docker-context) plugin via the Catalog * can run drpcli catalog item install docker-context from the command line
  • Create the docker container for the Runner and GoVC tools * See the tools/build-docker.sh script to build the containers
  • Upload the containers and enable them in drpcli * See the tools/drpcli-commands.sh script to do this
  • Create the Runner fake machines to start Workflow from * See the tools/drpcli-create-machines.sh script to do this
  • 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/$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:

27.45.1.1.3. Prepare the VCSA JSON Deployment Template

The Param govc/template-json defines the name of a Template that you must provide with the configuration details for the deployed VCSA instance. This template can be a standard Digital Rebar template, provided via another Content Pack, or you can upload a one-off template for the job. See the templates/govc-*EXAMPLE*.json 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 fake Runner Machine that the Workflow is run on.

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

27.45.1.1.4. 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.

27.45.2. Object Specific Documentation

27.45.2.1. params

The content package provides the following params.

27.45.2.1.1. govc/url

The full VMware ESXi or vCenter URL resource to connect to, to execute a govc/command against.

Example: root:RocketSkates@192.168.1.10

You must include the user:pass credentials if you sue this format.

There are two paths to configure the Resource URL, either this Param, or leave this Param empty, and specify all three required Param values, and the one optional:

All three required if govc/url is not used:

govc/username:  user
govc/password:  s3cr3t
govc/node: 192.168.1.10

Optional (defaults to ‘443’):

govc/port: 1443

By default this Param has an empty value.

27.45.2.1.2. vcsa-deploy/command

vcsa-deploy command to run

Defaults to vcsa-deploy --help command.

Example of a valid command:

install /tmp/template.json --accept-eula --acknowledge-ceip --verbose --log-dir /tmp/vcsa-deploy-logs --no-esx-ssl-verify

/tmp/template.json would be the template instantiated JSON config file that describes the deployment options.

27.45.2.1.3. vcsa-deploy/template-json

Render the template named in this Param, to the vcsa-deploy context container.

This template will be rendered to /tmp/template.json inside the container for use by the vcsa-deploy/command. For example, to deploy an OVA, save your OVA JSON template to the DRP system, assign the template name to this Param, and then set the vcsa-deploy/template-json Param accordingly.

Example:
set Param ``vcsa-deploy/template-json`` to: ``vcsa-esxi-uefi.json``
# which will be rendered to:  ``/tmp/template.json``
set Param ``vcsa-deploy/command``:  ``vcsa-deploy install /tmp/template.json <OPTIONS>``

27.45.2.1.4. govc/command

govc command to run - simply pass the value of this Param to the govc command in the container context.

Defaults to govc about command.

As an example, you can print the govc environment which affects the runtime operation of the govc command, using govc env. To use this command, set the Param to the value env (do not specify govc ifself).

27.45.2.1.5. govc/insecure

If set to true, then accept self signed certificates of the VMware ESXi or vCenter resource.

By default this value is set to true.

27.45.2.1.6. govc/network

Network of the ESXi/vCenter instance to use when deploying OVAs via the govc command.

For example, set to something like VM Network.

Defaults to an empty (unused) value.

27.45.2.1.7. govc/node

The hostname or IP address of the VMware ESXi or vCenter URL to connect to, to execute a govc/command against.

Has an empty value by default.

27.45.2.1.8. govc/resource-pool

Resource Pool to use for the govc deployed OVA.

For example, set to something like */Resources.

Defaults to empty (unused) value.

27.45.2.1.9. govc/datastore

Datastore that subsequent govc commands will use, if required.

For example set this to something like datastore1.

Defaults to an empty (unused) value.

27.45.2.1.10. govc/password

Password (secure) of the govc/username to authenticate against on the VMware ESXi or vCenter URL.

Defaults to RackN root default password for ESXi.

27.45.2.1.11. govc/port

Sets the Port number of the VMware ESXi or vCenter resource, if it has been relocated from the default (443).

27.45.2.1.12. govc/template-json

Render the template named in this Param, to the govc context container. Several of the govc commands require a config file passed in to the command. For example, the OVA deploy option requires a JSON template to configure the deployed OVA.

This template will be rendered to /tmp/template.json inside the container for use by the govc/command. For example, to deploy an OVA, save your OVA JSON template to the DRP system, assign the template name to this Param, and then set the govc/template accordingly.

Example:
set Param ``govc/template-json`` to: ``vcsa-esxi-uefi.json``
which will be rendered to:  ``/tmp/template.json``
govc/command reference:  ``govc import.ova -options=/tmp/template.json OVA_LOCATION``
OVA_LOCATION: would be the resource URL for the ``user:[email protected]`` of ESXi or vCenter

Unfortunately, it appears the GoVC command is not able to utilize a remote HTTP path as the JSON template input. This is true at least up until version 0.22.0 of GoVC.

27.45.2.1.13. govc/username

Username of the VMware ESXi or vCenter account to authenticate for the govc/command.

Defaults to RackN default ESXi username of root.

27.45.2.2. profiles

The content package provides the following profiles.

27.45.2.2.1. govc-about-test

Runs the simple govc about command on a test ESXi instance.

27.45.2.2.2. govc-vcsa-test

Runs govc to deploy a test VCSA deployment. Requires that the VCSA configuration JSON file be saved to to the context container as /tmp/template.json prior to the command being run.

27.45.2.2.3. govc-vcsa-vc01

Runs govc to deploy a test VCSA deployment. Requires that the VCSA configuration JSON file be saved to the context container as /tmp/template.json prior to the command being run.

The govc-command task reads the govc/template-json Param and writes the referenced template to the temporary json location.

27.45.2.2.4. vcsa-deploy-pungent

Runs vcsa-deploy to deploy a test VCSA deployment. Requires that the VCSA configuration JSON file be saved to the context container as /tmp/template.json prior to the command being run.

The vcsa-deploy-command task reads the vcsa-deploy/template-json Param and writes the referenced template to the temporary json location.

27.45.2.3. tasks

The content package provides the following tasks.

27.45.2.3.1. context-clear

Clears the Context on the Machine. Needed to return to the main Workflow when we jump Contexts.

27.45.2.3.2. context-runner

Sets the Machine BaseContext to “runner”, which returns it back to the fake machine runner when a Workflow is not being executed on a real Machine.

27.45.2.3.3. govc-command

This task executes a given govc call in a container context. The govc command is defined via the Param govc/command, which is required for this task.

The operator must also specify the remote vSphere ESXi or vCenter resource to connect to, to execute govc commands against. This is accomplished either by setting the govc/url Param, or the individual govc/username, govc/password, govc/node, and optionally govc/port (if using a non-standrd Port. See the documentation for each of those Params for more details.

Many of the GoVC commands require a JSON configuration that defines more the values for customizing. In these cases, use the govc/template-json param to define the Template to render inside of the GoVC container context.

27.45.2.3.4. govc-wait-for-vcenter

Simple task to wait until the remote vSphere deployed resource responds correctly to a govc about request call.

27.45.2.4. workflows

The content package provides the following workflows.

27.45.2.4.1. govc-command

Requires that operator has created a Contexts for runner and govc that can run DRP Angent and govc. The runner context is used for starting the workflow on a fake machine, and the govc context is responsible for executing the govc command and tooling.

Leaves the machines in a Runner Context not on the machine

27.45.2.4.2. govc-create-vcenter

Creates a vCenter instance via the govc command. Then waits for the API services to become available in vCenter, which should signal that it is finally up and running. This process can take upwards of 60 minutes to complete.

27.45.2.4.3. vcsa-deploy-command

Requires that operator has created a Contexts for “runner” and “vcsa-deploy” that can run DRP Angent and vcsa-deploy.

Leaves the machines in a Runner Context not on the machine