This is an automated email from the ASF dual-hosted git repository. harikrishna pushed a commit to branch userdataAsFirstClassResource in repository https://gitbox.apache.org/repos/asf/cloudstack-documentation.git
commit ff94383205d6bae992b4f731d83e189a7940935e Author: Harikrishna Patnala <[email protected]> AuthorDate: Fri May 27 12:14:30 2022 +0530 Added documentation for the userdata, which can be treated as a first class resource --- source/_static/images/deployvm_userdata.png | Bin 0 -> 32656 bytes source/_static/images/register_userdata.png | Bin 0 -> 31148 bytes .../_static/images/template-upload-from-local.png | Bin 39246 -> 60194 bytes source/_static/images/upload-iso-from-local.png | Bin 41764 -> 53133 bytes source/_static/images/userdata_template_link.png | Bin 0 -> 64782 bytes source/adminguide/templates.rst | 7 ++ source/adminguide/virtual_machines/user-data.rst | 137 ++++++++++++++++----- 7 files changed, 112 insertions(+), 32 deletions(-) diff --git a/source/_static/images/deployvm_userdata.png b/source/_static/images/deployvm_userdata.png new file mode 100644 index 0000000..33e5517 Binary files /dev/null and b/source/_static/images/deployvm_userdata.png differ diff --git a/source/_static/images/register_userdata.png b/source/_static/images/register_userdata.png new file mode 100644 index 0000000..8ac4fcc Binary files /dev/null and b/source/_static/images/register_userdata.png differ diff --git a/source/_static/images/template-upload-from-local.png b/source/_static/images/template-upload-from-local.png index 27b477c..e147848 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 ea0b9e2..19e8c17 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 0000000..5138393 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 e15272a..1e51658 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 <virtual_machines.html#user-data-and-meta-data>`_. + + - **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 3fe6511..da44ed7 100644 --- a/source/adminguide/virtual_machines/user-data.rst +++ b/source/adminguide/virtual_machines/user-data.rst @@ -17,15 +17,82 @@ 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 <https://cloudstack.apache.org/docs/api/apidocs-4.14/user/deployVirtualMachine.html>`_ -and -`updateVirtualMachine <https://cloudstack.apache.org/docs/api/apidocs-4.14/user/updateVirtualMachine.html>`_ -They both support the parameter ``userdata=``. The value for this parameter -must be a `base64 <https://www.base64encode.org/>`_-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 + + +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 + +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 <https://www.base64encode.org/>`_-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 +191,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 <<EOF - Content-Type: multipart/mixed; boundary="//" - MIME-Version: 1.0 - - --// - Content-Type: text/cloud-config; charset="us-ascii" - MIME-Version: 1.0 - Content-Transfer-Encoding: 7bit - Content-Disposition: attachment; filename="cloud-config.txt" - - #cloud-config - - # Upgrade the instance on first boot - # (ie run apt-get upgrade) - # - # Default: false - # Aliases: apt_upgrade - package_upgrade: true - EOF + base64 <<EOF + Content-Type: multipart/mixed; boundary="//" + MIME-Version: 1.0 + + --// + Content-Type: text/cloud-config; charset="us-ascii" + MIME-Version: 1.0 + Content-Transfer-Encoding: 7bit + Content-Disposition: attachment; filename="cloud-config.txt" + + #cloud-config + + # Upgrade the instance on first boot + # (ie run apt-get upgrade) + # + # Default: false + # Aliases: apt_upgrade + package_upgrade: true + EOF -#. Deploy a VM with this user-data: +#. Deploy a VM with this user-data either by providing the UUID of the registerd userdata + or by providing base64 encoded userdata: -.. code:: bash + .. code:: bash - cmk deploy virtualmachine name=..... userdata=Q29udGVudC1UeXBlOiBtdWx0aXBhcnQvbWl4ZWQ7IGJvdW5kYXJ5PSIvLyIKTUlNRS1WZXJzaW9uOiAxLjAKCi0tLy8KQ29udGVudC1UeXBlOiB0ZXh0L2Nsb3VkLWNvbmZpZzsgY2hhcnNldD0idXMtYXNjaWkiCk1JTUUtVmVyc2lvbjogMS4wCkNvbnRlbnQtVHJhbnNmZXItRW5jb2Rpbmc6IDdiaXQKQ29udGVudC1EaXNwb3NpdGlvbjogYXR0YWNobWVudDsgZmlsZW5hbWU9ImNsb3VkLWNvbmZpZy50eHQiCgojY2xvdWQtY29uZmlnCgojIFVwZ3JhZGUgdGhlIGluc3RhbmNlIG9uIGZpcnN0IGJvb3QKIyAoaWUgcnVuIGFwdC1nZXQgdXBncmFkZSkKIwojIERlZmF1bHQ6IGZhbHNlCiM [...] + cmk deploy virtualmachine name=..... userdata=Q29udGVudC1UeXBlOiBtdWx0aXBhcnQvbWl4ZWQ7IGJvdW5kYXJ5PSIvLyIKTUlNRS1WZXJzaW9uOiAxLjAKCi0tLy8KQ29udGVudC1UeXBlOiB0ZXh0L2Nsb3VkLWNvbmZpZzsgY2hhcnNldD0idXMtYXNjaWkiCk1JTUUtVmVyc2lvbjogMS4wCkNvbnRlbnQtVHJhbnNmZXItRW5jb2Rpbmc6IDdiaXQKQ29udGVudC1EaXNwb3NpdGlvbjogYXR0YWNobWVudDsgZmlsZW5hbWU9ImNsb3VkLWNvbmZpZy50eHQiCgojY2xvdWQtY29uZmlnCgojIFVwZ3JhZGUgdGhlIGluc3RhbmNlIG9uIGZpcnN0IGJvb3QKIyAoaWUgcnVuIGFwdC1nZXQgdXBncmFkZSkKIwojIERlZmF1bHQ6IGZhbHNl [...] + + .. code:: bash + cmk deploy virtualmachine name=..... userdataid=<Userdata UUID> Disclaimer ~~~~~~~~~~
