This is an automated email from the ASF dual-hosted git repository.
rohit pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/cloudstack-documentation.git
The following commit(s) were added to refs/heads/main by this push:
new 6757fe3 Added documentation for the first class resource userdata
(#273)
6757fe3 is described below
commit 6757fe346d1e48968f2be7aa9ccba80b73e8d6ae
Author: Harikrishna <[email protected]>
AuthorDate: Sat Oct 15 23:18:21 2022 +0530
Added documentation for the first class resource userdata (#273)
* Added documentation for the userdata, which can be treated as a first
class resource
* Added content to explain the usage of variables in userdata during
registration and vm deployment
* fixed a code snippet in userdata section
---
source/_static/images/deployvm_userdata.png | Bin 0 -> 28071 bytes
.../images/deployvm_userdata_with_variables.png | Bin 0 -> 32033 bytes
source/_static/images/register_userdata.png | Bin 0 -> 31148 bytes
.../images/register_userdata_with_variables.png | Bin 0 -> 33407 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 | 168 +++++++++++++++++----
9 files changed, 143 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..bcc249d
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 0000000..59089c1
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 0000000..8ac4fcc
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 0000000..463baac
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 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..d863859 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
<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
+
+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
<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 +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 <<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
+ 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
- # 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
~~~~~~~~~~
