diff --git a/source/_static/images/deployvm_userdata.png b/source/_static/images/deployvm_userdata.png new file mode 100644 index 0000000000..bcc249d59d Binary files /dev/null and b/source/_static/images/deployvm_userdata.png differ diff --git a/source/_static/images/deployvm_userdata_with_variables.png b/source/_static/images/deployvm_userdata_with_variables.png new file mode 100644 index 0000000000..59089c1cdd Binary files /dev/null and b/source/_static/images/deployvm_userdata_with_variables.png differ diff --git a/source/_static/images/register_userdata.png b/source/_static/images/register_userdata.png new file mode 100644 index 0000000000..8ac4fcccb4 Binary files /dev/null and b/source/_static/images/register_userdata.png differ diff --git a/source/_static/images/register_userdata_with_variables.png b/source/_static/images/register_userdata_with_variables.png new file mode 100644 index 0000000000..463baac3e5 Binary files /dev/null and b/source/_static/images/register_userdata_with_variables.png differ diff --git a/source/_static/images/template-upload-from-local.png b/source/_static/images/template-upload-from-local.png index 27b477c9df..e147848b0f 100644 Binary files a/source/_static/images/template-upload-from-local.png and b/source/_static/images/template-upload-from-local.png differ diff --git a/source/_static/images/upload-iso-from-local.png b/source/_static/images/upload-iso-from-local.png index ea0b9e2eff..19e8c175d5 100644 Binary files a/source/_static/images/upload-iso-from-local.png and b/source/_static/images/upload-iso-from-local.png differ diff --git a/source/_static/images/userdata_template_link.png b/source/_static/images/userdata_template_link.png new file mode 100644 index 0000000000..5138393ee8 Binary files /dev/null and b/source/_static/images/userdata_template_link.png differ diff --git a/source/adminguide/templates.rst b/source/adminguide/templates.rst index e15272ab5a..1e51658988 100644 --- a/source/adminguide/templates.rst +++ b/source/adminguide/templates.rst @@ -268,6 +268,13 @@ To upload a template: selecting an OS Type when registering a template if the option 'Read VM settings from OVA' is selected. In this case, the OS Type is obtained from the template after it is registered. + - **Userdata**: The registered Userdata are listed. Select the + desired one. + + - **Userdata link policy**: Select the userdata override policy as required. + For more information on userdata and override link policy, please check `Userdata section `_. + + - **Hypervisor**: The supported hypervisors are listed. Select the desired one. diff --git a/source/adminguide/virtual_machines/user-data.rst b/source/adminguide/virtual_machines/user-data.rst index 3fe6511649..d863859024 100644 --- a/source/adminguide/virtual_machines/user-data.rst +++ b/source/adminguide/virtual_machines/user-data.rst @@ -17,15 +17,113 @@ User-Data and Meta-Data ----------------------- -CloudStack provides APIs to attach up to 32KB of user-data to a deployed VM. +Users can register userdata in CloudStack and refer the registered userdata while +deploying or editing or reset userdata on a VM. The userdata content can also be +directly provided while deploying the VM. Userdata content length can be up to 32kb. -There are two CloudStack APIs that can be used to store user-data: -`deployVirtualMachine `_ -and -`updateVirtualMachine `_ -They both support the parameter ``userdata=``. The value for this parameter -must be a `base64 `_-encoded multi-part MIME -message. See further below for an example of what this should look like. +To register a new userdata: + +#. Log in to the CloudStack UI. + +#. In the left navigation bar, click Compute and then User Data. + +#. Click Register a userdata. + +#. In the dialog, make the following choices: + + - **Name**: Any desired name for the userdata. + + - **Userdata**: Plain userdata content. CloudStack UI does base64 encoding. + + - **Userdata parameters**: Comma separated list of variables which (if any) declared + in userdata content. + + - **Domain**: An optional domain for the userdata. + + - **Account**: An optional account for the userdata. + +.. image:: /_static/images/register_userdata.png + :width: 400px + :align: center + :alt: Regiser userdata dialog box + +If userdata content has variables declared in it, user can register the Userdata +with userdata parameters. + +For example, if userdata content is like below having a custom variable "variable1" + + .. code:: bash + + ## template: jinja + #cloud-config + runcmd: + - echo 'TestVariable {{ ds.meta_data.variable1 }}' >> /tmp/variable + - echo 'Hostname {{ ds.meta_data.public_hostname }}' > /tmp/hostname + +Userdata has to be registered with userdata parameter "variable1" like below + +.. image:: /_static/images/register_userdata_with_variables.png + :width: 400px + :align: center + :alt: Regiser userdata with variables dialog box + +If the variables in userdata content are of a predefined metadata like "public_hostname" +or "instance_id", then userdata parameters should not declare these variables. That is +the reason in the above example "public_hostname" is not declared. + +There are three CloudStack APIs that can be used to provide user-data to VM: +deployVirtualMachine, updateVirtualMachine and resetUserDataForVirtualMachine. +These APIs accepts parameters ``userdataid`` and ``userdatadetails``. +userdatadetails is to specify the custom values for the variables which are declared +in userdata in a key value parameter map details. + +.. image:: /_static/images/deployvm_userdata.png + :width: 400px + :align: center + :alt: Provide userdata id or userdata text dialog box + +If the userdata contains variables that are declared during registration then those values +has to be specified like below, + +.. image:: /_static/images/deployvm_userdata_with_variables.png + :width: 400px + :align: center + :alt: Provide userdata id or userdata with variables text dialog box + +These details will be saved as meta-data file(s) in both config drive and virtual router, +which in turn support jinja based instance meta-data feature of cloud-init, +refer to https://cloudinit.readthedocs.io/en/latest/topics/instancedata.html. + +These APIs also support the parameter ``userdata=`` to provide the userdata content +directly. The value for this parameter must be a `base64 `_-encoded +multi-part MIME message. See further below for an example of what this should look like. + +The registered UserData can be linked to a template or ISO on registration/upload/editing +using linkUserDataToTemplate API. The same API can be used to unlink the mapping of userdata and template. + +While linking userData to a template/ISO userdata override policy has to be specified. +Following are the override policies available: + +Allow Override: Allow users to override UserData for the template during VM deployment or on reset. + This is the default override policy if not specified + +Deny Override: Override of UserData isn’t allowed during VM 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. + +This is how it looks like in template/ISO register/upload/edit forms. + +.. image:: /_static/images/userdata_template_link.png + :width: 400px + :align: center + :alt: Linking userdata to template/ISO + +Based on these override policies, "Add Instance" UI form provides relevant options to either +override or append. If it is "Deny Override" then "Add Instance" will not allow adding user specific userdata + +Storing and accessing userdata +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ HTTP GET parameters are limited to a length of 2048 bytes, but it is possible to store larger user-data blobs by sending them in the body via HTTP POST @@ -124,36 +222,42 @@ Custom user-data example This example uses cloud-init to automatically update all OS packages on the first launch. -#. Create user-data, wrapped into a multi-part MIME message and encoded in base64: +#. Register the following user-data in CloudStack. If APIs are used to register userdata or to + provide direct userdata text then userdata needs to be wrapped into a multi-part MIME message + and encoded in base64: -.. code:: bash + .. code:: bash - base64 < Disclaimer ~~~~~~~~~~