Skip to end of metadata
Go to start of metadata

Description

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.

Overview

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:

  1. 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. 
  2. 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:

  1. VMWare Transport Flag
    1. 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.  
  2. ISO Transport Flag
    1. 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. 
    2. A few notes about this feature:
      1. CloudControl will treat the resulting ISO like any other ISO, meaning it will identify and generate storage usage for the ISO
      2. 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:

  1. 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
  2. Create new vApp Properties including a defined schema
  3. Modify the schema of an existing vApp Property
  4. 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:

  1. Cannot be assigned to a vApp Property using the CloudControl API
  2. 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
  3. 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

Schema AttributeRequiredTypeDescription
keyYesxsd:intUnique integer key for the property.
idYesxsd:stringProperty name.
categoryNoxsd:stringA user-visible description of the category the property belongs to.
labelNoxsd:stringProperty display name.
descriptionNoxsd:stringProperty description.
classIdNoxsd:stringProperty class name.
instanceIdNoxsd:stringProperty class/instance name.
typeReferenceNoxsd:stringExtra configuration data depending on the property type.
userConfigurableNoxsd:booleanIf True, the property is user-configurable. If False, the property is not user-configurable and is considered to be a system property.
defaultValueNoxsd:stringDefault property value, used if the property value is an empty string.
typeNoxsd:string

Type of the property value defined as one of the following strings:

  1. string: A generic string. Max length 65535 (64 kilobytes).
    1. string(x..): A string with minimum character length x.
    2. string(..y): A string with maximum character length y.
    3. string(x..y): A string with minimum character length x and maximum character length y.
    4. string["choice1", "choice2", "choice3"] : A set of choices. " inside a choice must be either \" or ' e.g "start\"middle\"end" or "start'middle'end" and a \ inside a string choice must be encoded as \\ e.g. "start\\end".
  2. int: An integer value. Is semantically equivalent to int(-2147483648..2147483647) e.g. signed int32.
    1. int(x..y): An integer value with a minimum size x and a maximum size y. For example, int(0..255) is a number between 0 and 255 both incl. This is also a way to specify that the number must be a uint8. There is always a lower and lower bound. Max number of digits is 100 including any sign. If exported to OVF the value will be truncated to a max of uint64 or int64.
  3. real: IEEE 8-byte floating-point value.
    1. real(x..y): IEEE 8-byte floating-point value with a minimum size x and a maximum size y. For example, real(-1.5..1.5) must be a number between -1.5 and 1.5. Because of the nature of the real type some conversions can truncate the value. Real must be encoded according to CIM: RealValue = [ "+" | "-" } *decimalDigit "." 1*decimalDigit [ ("e" | "E" ) [ "+" | "-" ] 1*decimalDigit ] ].
  4. boolean: The value can be True or False.
  5. password: For properties of type 'password', the value field and defaultValue field will always be returned as an empty string when queried. Thus, it is a write-only property. Typically, a client application will also render these as a text field with hidden text and double prompting. Variations of this field are:
    1. password: A generic string. Max length 65535 (64k).
    2. password(x..): A string with minimum character length x.
    3. password(..y): A string with maximum character length y.
    4. password(x..y): A string with minimum character length x and maximum character length y.
  6. expression: The default value specifies an expression that is calculated by the system. 
  7. ip: An IPv4 address in dot-decimal notation or an IPv6 address in colon-hexadecimal notation. The ip types are typically used to specify an IP address to an external system. Thus, these are not used by a virtual ethernet adapter within the Guest OS itself. CloudControl supports one of three possible ways of specifying IP addresses:
    1. ip: An IPv4 address in dot-decimal notation or an IPv6 address in colon-hexadecimal notation.
    2. ${ip:network} expression
    3. ip:network : An IP address in dot-notation (IPv4) and colon-hexadecimal (IPv6) on a particular network. 
valueNoxsd:stringValue of the property. If type is specified, the value must meet the requirements of the defined type as described above.