Introduction
When launching a new Instance on Apache CloudStack, users can set a UserData script to be executed by cloud-init during the boot process. The ‘CloudStack Managed UserData’ feature extends this functionality allowing one to automate the installation of packages, update the instance’s OS, and configure applications during instance deployment.
Introduced in Apache CloudStack 4.18, Managed UserData enables users to register and manage their own UserData script(s) as a CloudStack resource. It can be associated with a CloudStack Template/ISO, or when a new Instance is being deployed.
Managed UserData
This new feature makes the following operations available via API or UI:
• Register, list and remove stored UserData.
• Deploying a new Instance, users can select a registered UserData script and optionally set a custom key-value parameter map to provide variable keys to the UserData content.
• Reset and update UserData for an existing Instance, similar to the reset SSH key API/feature. The reset/update can be done using updateVirtualMachine or resetUserDataForVirtualMachine API.
• UserData can be linked with a Template during Template registration/upload/editing using linkUserDataToTemplate API call. The same API can be used to unlink UserData and Templates.
• Users should specify the policy used to link UserData and Templates:
| Allow Override | Allow users to override UserData linked to the Template during Instance deployment or reset. This is the default override policy if not specified. |
| Deny Override | Override of UserData isn’t allowed during Instance deployment or on reset. |
| Append Only | Don’t allow users to override linked UserData but allow users to pass UserData content or ID that should be appended to the linked UserData of the template. |
• Passing the registered UserData UUID and the existing API parameter to the UserData content is not allowed.
Custom UserData parameters
During registration of a new UserData script, users can define custom parameters. These parameters are used as variables in UserData scripts. While deploying an Instance and upon selecting the UserData, users pass the values to these custom parameters. The keys/value referring to the UserData parameter map must be considered if using the API.
The Custom UserData details passed as key/value map, are saved as meta-data files in both, config drive and VR, which in turn could support cloud-init jinja-based instance meta-data, refer to https://cloudinit.readthedocs.io/en/latest/topics/instancedata.html.
UI changes
The following UI changes have been made to support managed UserData operations:
- A new sub-section under Compute tab was introduced where users can register, list, and remove stored UserData:
- The following form is used to register a new UserData and to set UserData custom parameters:
- New fields introduced in the “Register Template” and “Register ISO” form to link a stored UserData:
- New fields introduced in the “Edit Template” and “Edit ISO” form to link/unlink UserData:
- In the “Add Instance” wizard > “Advanced Mode” , was added a new list “Stored UserData”.
• When a UserData containing custom parameters was selected in the “Add Instance” wizard, new fields are dynamically built, enabling the user to set the related variables:
API Changes
The following API changes have been made to support managed UserData operations:
| API name | Parameters |
| registerUserData | name: name of the userdatauserdata: userdata content encoded using base64
params: (optional) comma separated list of variables declared in userdata content |
| listUserData | id: (optional) UUID of the userdataname: (optional) name of the userdata |
| deleteUserData | id: UUID of the userdata |
| linkUserDataToTemplate | templateid: UUID of the templateuserdataid: (optional) UUID of the userdata. If not provided, existing userdata will be unlinked from the template |
| resetUserDataForVirtualMachine | id: UUID of the virtual machineuserdataid: (optional) UUID of the userdata
userdatadetails: (optional) key value pairs map to specify the values for the variables declared in userdata content userdata: (optional) userdata content encoded using base64 |
Existing APIs:
| API name | Parameters |
| deployVirtualMachine | userdataid: (optional) UUID of the userdatauserdatadetails: (optional) key value pairs map to specify the values for the variables declared in userdata content |
| updateVirtualMachine | userdataid: (optional) UUID of the userdatauserdatadetails: (optional) key value pairs map to specify the values for the variables declared in userdata content |
Conclusion
The new ‘Managed UserData’ feature (available as of Apache CloudStack 4.18) simplifies the process of the initial Instances configuration, reducing the time spent creating UserData scripts, in addition allowing the use of custom variables during the process of deploying new Instances with cloud-init.
Regarding automation, this new feature makes it easy to manage UserData script collections, centralizing IaaS resources in a single endpoint.
Harikrishna works at ShapeBlue as a Software Engineer, and is also engaged with active development of new features and capabilities for the Apache CloudStack project. He has been working on CloudStack since 2012 and is a committer in this project. Before joining ShapeBlue, Harikrishna worked for Citrix Systems and Accelerite. He holds an M.Tech in Computer Science and Engineering from IIT-Madras.
You can learn more about Harikrishna and his background by reading his Meet The Team blog.
