Introduction

 Purpose

This is the feature specification proposal for CLOUDSTACK-1026.

To enable more sophisticated VM deployments and blueprint (CLOUDSTACK-576) deployments, cloudstack developers and system administrators need a mechanism to perform additional guest customisation. This would include:

• installing files to an instance
• executing commands on a VM post-boot

Initially this would be from a Java API, then likely offering a REST API and GUI controls.

References

• Issue References
  • This corresponds to the the In-Guest Customization feature CLOUDSTACK-1026
  • This supports Blueprints feature CLOUDSTACK-576
• Code/Branch
  • Proposed work will be collated in `ahgittin/incubator-cloudstack` fork at github, `guest-customize` branch (here)
  • It is TBD where and how this will be plugged in to CloudStack.

 Document History

• 21 Jan 2013: Initial draft

Glossary

None yet

Feature Specifications

A java API available to plugins and associated resources in CloudStack, to perform the following against target VM's:

• copy files to machine
• execute commands

The following items may be addressed as features in the future but are not presently in scope for this work:

• Guest VM command execution and file management exposed through a REST API
• GUI conveniences for installing files, running commands,

Use Cases

The primary use case driving this is the "Blueprints" feature (CLOUDSTACK-576).

• Developers writing other CloudStack modules require the ability to customize individual VM's as part of creating a composite application blueprint. This means installing files, executing commands, and getting the output of those commands.

We can envisage other use cases, although the demand for them is uncertain:

• An application consumer the REST API wants to perform customizations on a VM after deployment, to automate a richer deployment. (The demand for this is uncertain as they can connect to the VM's by other means, e.g. scp/ssh.)

• A GUI user wants to specify certain commands to run or files to install. (Again demand for this is uncertain as this could be done through the usual non-CloudStack mechanisms, e.g. scp/ssh. The ability to specify this as part of a Blueprint Designer might be a cleaner fit maximising re-use.)

Architecture and Design Description

Slightly expanded list of requirements:

• copy files to machine, to arbitrary locations, with permissions and owners (supporting a supplied byte array or a URL; using an `InputStream` should permit either)
• execute commands, including files which have been installed, and track those executions (i.e. tail the relevant stdout and stderr)

Initially we will concentrate on a java API which takes information on a created VM and performs these operations.

Internally these will be execution tasks whose status can be monitored, and in the case of executing commands, the stdout and stderr streams accessed.

TBD whether there are other components which should be annotated that such tasks are ongoing (e.g. note on the VM that operations are active).

Appendix

Appendix A: Java API Psueodocde (Very Early Draft)

    class VmGuestCustomizer {
      class Builder {
        Builder vmDetails(...);
        VmGuestCustomizer build();
      }
      Task installFile(InputStream data, String owner, String group, int permissions);
      TaskWithOutputStreams executeCommand(String command);
    }