ConfigurationStrategies

Summary

Today, while the image creator is in the best position to describe what is required to activate an image, it is the deployer's responsibility to provide this information at deploy time. This blueprint introduces a mechanism for the image creator to augment an image in OpenStack with metadata describing what must be present to configure an image. It also provides the and implementations to present that data to the guest for OVF-compliant and sysprep-based configuration.

Assumptions and Constraints


 * Implementation should not change current OpenStack behavior
 * The deployer is NOT in in the best position to describe how an image is to be configured at deploy time (Image Administrator or Image Creator is).
 * Image configuration metadata should follow to all derivatives of the image (e.g. snapshots, clones)
 * nova.virt drivers should not have knowledge of configuration strategies (the only responsibility is mapping presented devices)

Rationale

Sysprep, for Windows images, and OVF, for PowerVM, activations are popular configuration strategies in enterprise environments. However, neither one works in OpenStack today. Currently, OpenStack supports two activation strategies: metadata URL and config-drive. While both allow user-specific data to be passed to the guest, they are rigid in their format (i.e. all images get the same metadata format) and are primarily targeted at cloud-init based activations.

One method to pass arbitrary data to a guest is called user-data. User-data is opaque, provides no structure, and cannot convey to the end-user what is required. For example, while an unattend.xml file contents could be passed as user-data, it requires the deployer to know the exact format and contents for the file, something a deployer is not likely to want to know nor understand. Rather, what is needed is the ability for the image creator - who has the in-depth understanding of the configuration strategy and requirements  - to add metadata to the image that conveys what must be presented to the guest at initial boot.

Use Cases


 * As a service provider, I want to support OVF-based activations.
 * As a service provider, I want to support Sysprep-based activations.
 * As an image creator, I want to specify the configuration strategy (e.g. sysprep, ovf, config-drive) in use for my image.
 * As an image creator, I want to provide a template activation file and specify the mapping of data into it.
 * As a deployer, I want to deploy an image. <- UNCHANGED

Design

The design has two distinct components: 1) image definition in Glance containing the configuration strategy and metadata and 2) implementation in Nova that executes the strategy and presents to the guest. Glance Glance carries the definition of the configuration strategy and metadata to execute on it as image properties with the Image Administrator responsible for the initial population. Current OpenStack behavior retains these image properties on snapshot enabling subsequent deploys to succeed. The activation strategy details the engine or method in use and, in the case of OVF and Sysprep, provides a base activation file and the mapping of system and user data into it. The strategy is optional and not required for standard metadata URL or config-drive activations. Mapping "source" values represent a finite set of keys (exception is "server.metadata" entries that map to the user-supplied metadata keys). target is resolved specific to the configuration strategy and is documented there. (OVF and sysprep use xPath targets) The following JSON example illustrates these concepts:

"properties": { "configuration_strategy": { "type": "ovf", "template": "", "mapping": [ { "source": "server.metadata.ntp-server ", "target": "com.ibm.vsae.2_1.ntp-client.ntp-server"}, { "source": " server.network.1.v4.address", "target": "com.ibm.vsae.2_1.network-interface.ipaddr"}, { "source": " server.network.1.v4.gateway ", "target": com.ibm.vsae.2_1.network-interface.gateway"}         ]      }   } }

sysprep - the base unattend.xml file is included as the template and type set to "sysprep"

In addition to existing config-drive options, type of "config-drive" would be supported.

Nova

When creating a new server, the API user could optionally analyze the mappings to search for "server.metadata" entries available. From the above example ntp-server would be passed like:

{ "server": { "flavorRef": "http://openstack.example.com/openstack/flavors/1", "imageRef": "http://openstack.example.com/openstack/images/70a599e0-31e7-49b7-b260-868f441e862b", "metadata": { "ntp-server": "pool.ntp.org", },       "name": "new-server-test" } }

During the deployment flow, Nova must identify images with the custom configuration_strategy and handle them accordingly. A common superclass builds up the map of available values (source values). Strategy specific implementations use the source map and build the strategy specific output. For both OVF and Sysprep, the values are written to a predetermined file name (ovf-env.xml and unattaned.xml respectively) using xPath. Once the configuration file is created, the implemenation uses a modified version of the config_drive implementation - expose add_file, support for attach as CD-ROM in addition to HDD - to provide a hypervisor-agnostic way of presenting the block device to the guest.

Strategy Details

The following three activation strategies are supported:


 * config-drive - external interface is unchanged; internally, re-factored to use same flow as other configuration strategies.
 * ovf - create ovf-env.xml containing all key/values with default values extracted from the .ovf XML file (from Glance "template" property), for "target" keys present in the .ovf XML file, map value from source key into ovf-env.xml; ovf-env.xml is then added to a "config_drive" and presented to the guest as an additional block device using existing block_device_mapping.
 * sysprep - unattend.xml is retrieved from Glance in "template" property all the mappings are iterated over and set in the unattend.xml; unattend.xml is then added to a "config_drive" and presented to the guest as a CD-ROM device using existing block_device_mapping support.