This page is an introduction to vApp Properties support with the CloudControl API:
vApp Support is Currently API Only
The current implementation of vApp Properties is "API Only", meaning the existence and/or settings associated with vApp Properties is not visible in the UI. You must use the CloudControl API in order to view and/or manage vApp Properties.
vApp Properties (formerly called "OVF Properties") are a VMware feature that provides a mechanism for making the Guest OS aware of information that is needed for the server to configure itself. Two main use cases:
- OVF Images and appliances from third parties such as Cisco or VMWare come with various predefined vApp Properties where the user is expected to provide the “values” for the properties so that the first time the server is started, it can configure itself.
- DevOps scripting (Ansible, Chef, etc.) where the engineer has a script that will run in the OS wants to be able to create both the properties and values that can be read by the script for similar purposes.
Once defined, these properties and values can be read from the Guest OS either using VMware Tools or via an ISO that vSphere will attach to a CD ROM device on the server.
Implementation - Cloud Servers Only
CloudControl currently only tracks the existence of vApp Properties on Cloud Servers. The system does not track the existence or values of vApp Properties on Images, though vApp Properties and settings may exist on an Image. Once a server is deployed from the image, whatever vApp Properties exist on the image will be visible on the server through the API . In the case of images and appliances that require the vApp properties to be set in order to function, it is recommend that users deploy the server in a stopped state, then set the values via API before powering on the server.
Enablement and Transport Options
In order to use vApp Properties, support for vApp Property must be enabled on the server. In addition, users must choose at least one "transport option" that defines how the vApp Properties will be exposed to the Guest OS. There are two methods that are set using vApp Properties Transport flags:
- VMWare Transport Flag
- If enabled, this flag will make the vApp Properties available to the Guest OS through the use of VM Tools through the guestinfo.ovfEnv variable. Obviously, the server must be running VM Tools in order to use this method.
- ISO Transport Flag
- If enabled, this flag will result in VMWare generating an ISO on Server startup and attaching it to the first available CD-ROM device on that server. Obviously, the server need a CD-ROM device in order to use this feature.
- A few notes about this feature:
- CloudControl will treat the resulting ISO like any other ISO, meaning it will identify and generate storage usage for the ISO
- The Cloud Snapshot feature is currently incompatible with ISO's so this method cannot be used on a server with Cloud Snapshots enabled.
If the Image used to deploy the Server has vApp Properties enabled, that enablement and whatever transport flags are defined will be passed to any Cloud Servers deployed from the Image. Alternately, the feature and transport method can be defined using the CloudControl API after server deployment.
A few other notes about the transports methods:
- Both Transports can be enabled or disabled independently, so the user can enable both Transports, one, or neither.
- vApp Properties can be Disabled at any time on a Server, but this will result in all existing vApp Properties being irreversibly deleted. If re-enabled, the old vApp Properties will no longer exist on that Server.
- If you're looking for a quick overview as to how to read the vApp properties within the OS, see the blog article OVF Runtime Environment
Setting Values and Defining vApp Properties
In addition to exposing the vApp Properties, CloudControl will also allow users the use the API to:
- Set values on existing vApp Properties based on the defined schema for the property
- NOTE: Any value you set must follow the rules defined by the schema - i.e. if the type is int(0..255), then the value must be an integer from 0 to 255
- Create new vApp Properties including a defined schema
- Modify the schema of an existing vApp Property
- Delete a vApp Property
In all cases, the schema attributes follow the standard VMWare 6.5 compliant schema of metadata attributes consisting of the following elements
Complete details on how to perform these functions are available in the CloudControl API documentation at API 2 - Documentation Downloads.
Note there are three unsupported scheme types marked in red in the table below. These three exceptions are rare and are unsupported as they would not be expected to work properly in the MCP 2.0 environment. These unsupported schema elements:
- Cannot be assigned to a vApp Property using the CloudControl API
- If they are "found" on a Cloud Server (because the source image had them set), the type will be returned in the CloudControl API as UNSUPPORTED_TYPE and the description in the API will be populated with the type that has been found
- The actual server will still have the actual "unsupported" type and will return as such in the transport mechanism, but the expectation is the resulting value will be unusable.
vSphere 6.5 Schema Attributes
|key||Yes||xsd:int||Unique integer key for the property.|
|category||No||xsd:string||A user-visible description of the category the property belongs to.|
|label||No||xsd:string||Property display name.|
|classId||No||xsd:string||Property class name.|
|instanceId||No||xsd:string||Property class/instance name.|
|typeReference||No||xsd:string||Extra configuration data depending on the property type.|
|userConfigurable||No||xsd:boolean||If True, the property is user-configurable. If False, the property is not user-configurable and is considered to be a system property.|
|defaultValue||No||xsd:string||Default property value, used if the property value is an empty string.|
Type of the property value defined as one of the following strings:
|value||No||xsd:string||Value of the property. If type is specified, the value must meet the requirements of the defined type as described above.|