This is an automated email from the ASF dual-hosted git repository.
rohit pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cloudstack-documentation.git
The following commit(s) were added to refs/heads/master by this push:
new c50d817 cloud-init and UserData service documentation cleanup (#132)
c50d817 is described below
commit c50d81755c8076810dd6b8519fc678da6b8a9ebb
Author: Gregor Riepl <[email protected]>
AuthorDate: Mon Jan 11 11:24:08 2021 +0100
cloud-init and UserData service documentation cleanup (#132)
* Update and clean up the cloud-init documentation
* Replace more instances of explicit IPs
* Document getVirtualMachineUserData usage
* Add MIME header to example user-data
* Adapt caf374e167940b65a695b741a4ec263b474d2016 (DHCP lease path) for
user-data overhaul
---
source/adminguide/virtual_machines/user-data.rst | 129 ++++++++++++++++-------
1 file changed, 89 insertions(+), 40 deletions(-)
diff --git a/source/adminguide/virtual_machines/user-data.rst
b/source/adminguide/virtual_machines/user-data.rst
index 3a84ea1..24285e9 100644
--- a/source/adminguide/virtual_machines/user-data.rst
+++ b/source/adminguide/virtual_machines/user-data.rst
@@ -17,35 +17,39 @@
User-Data and Meta-Data
-----------------------
-CloudStack provides API access to attach up to 2KB of data after base64
encoding
-to a deployed VM. Using HTTP POST(via POST body), you can send up to 32K of
data
-after base64 encoding. Deployed VMs also have access to instance metadata via
-the virtual router.
+CloudStack provides APIs to attach up to 32KB of user-data to a deployed VM.
-Create virtual machine thru the API: `deployVirtualMachine
<http://cloudstack.apache.org/docs/api/apidocs-4.5/user/deployVirtualMachine.html>`_
-using the parameter ``userdata=`` to include user-data formated in
-`base64 <https://www.base64encode.org/>`_.
+There are two CloudStack APIs that can be used to store user-data:
+`deployVirtualMachine
<http://cloudstack.apache.org/docs/api/apidocs-4.14/user/deployVirtualMachine.html>`_
+and
+`updateVirtualMachine
<http://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.
-Accessed user-data from VM. Once the IP address of the virtual router is
-known, use the following steps to retrieve user-data:
+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
+instead of GET.
-#. Run the following command to find the virtual router.
+From inside the VM, the user-data is accessible via the virtual router,
+if the UserData service is enabled on the network offering.
- .. code:: bash
+If you are using the DNS service of the virtual router, a special hostname
+called `data-server.` is provided, that will point to a valid user-data server.
- # cat /var/lib/dhcp/dhclient.eth0.leases | grep dhcp-server-identifier |
tail -1
+Otherwise you have to determine the virtual router address via other means,
+such as DHCP leases. Be careful to scan all routers if you have multiple
+networks attached to a VM, in case not all of them have the UserData service
+enabled.
-#. Access user-data by running the following command using the result of
- the above command
+User-data is available from the URL ``http://data-server./latest/user-data``
+and can be fetched via curl or other HTTP client.
- .. code:: bash
+It is also possible to fetch VM metadata from the same service, via the URL
+``http://data-server./latest/{metadata type}``. For backwards compatibility,
+the previous URL ``http://data-server./latest/{metadata type}`` is also
supported.
- # curl http://10.1.1.1/latest/user-data
-
-Meta Data can be accessed similarly, using a URL of the form
-``http://10.1.1.1/latest/meta-data/{metadata type}``. (For backwards
-compatibility, the previous URL ``http://10.1.1.1/latest/{metadata type}``
-is also supported.) For metadata type, use one of the following:
+For metadata type, use one of the following:
- ``service-offering``. A description of the VMs service offering
@@ -55,23 +59,53 @@ is also supported.) For metadata type, use one of the
following:
- ``local-hostname``. The hostname of the VM
-- ``public-ipv4``. The first public IP for the router. (E.g. the first IP
- of eth2)
+- ``public-ipv4``. The first public IP for the router.
- ``public-hostname``. This is the same as public-ipv4
- ``instance-id``. The instance name of the VM
-Using Cloud-Init
+Determining the virtual router address without DNS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If can't or don't want to use the virtual router's DNS service, it's also
+possible to determine the user-data server from a DHCP lease.
+
+#. Run the following command to find the virtual router.
+
+ .. code:: bash
+
+ # cat /var/lib/dhcp/dhclient.eth0.leases | grep dhcp-server-identifier |
tail -1
+
+#. Access the data-server via its IP
+
+ .. code:: bash
+
+ # curl http://10.1.1.1/latest/user-data
+
+
+Fetching user-data via the API
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+User-data is not included with the normal VM state for historic reasons.
+To read out the base64-encoded user-data via the API, use the
`getVirtualMachineUserData
<http://cloudstack.apache.org/docs/api/apidocs-4.14/user/getVirtualMachineUserData.html>`_
+API call:
+
+.. code:: bash
+
+ cmk get virtualmachineuserdata
virtualmachineid=8fd996b6-a102-11ea-ba47-23394b299ae9
+
+
+Using cloud-init
~~~~~~~~~~~~~~~~
-`Cloud-Init <https://cloudinit.readthedocs.org/en/latest>`_ can be use to
access
-an interpret user-data from virtual machines. Cloud-Init be installed into
-templates and also require CloudStack password and sshkey scripts
(:ref:`adding-password-management-to-templates` and `using ssh keys
<virtual_machines.html#using-ssh-keys-for-authentication>`_). User password
management and
-``resetSSHKeyForVirtualMachine`` API are not yet supported by cloud-init.
+`cloud-init <https://cloudinit.readthedocs.org/en/latest>`_ can be used to
access
+and interpret user-data inside virtual machines. If you install cloud-init
into your
+VM templates, it will allow you to store SSH keys and user passwords on each
new
+VM deployment automatically (:ref:`adding-password-management-to-templates`
and `using ssh keys
<virtual_machines.html#using-ssh-keys-for-authentication>`_).
-#. Install cloud-init package into a template:
+#. Install cloud-init package into a VM template:
.. code:: bash
@@ -79,7 +113,7 @@ templates and also require CloudStack password and sshkey
scripts (:ref:`adding-
or
$ sudo apt-get install cloud-init
-#. Create datasource configuration file:
``/etc/cloud/cloud.cfg.d/99_cloudstack.cfg``
+#. Create a datasource configuration file in the VM template:
``/etc/cloud/cloud.cfg.d/99_cloudstack.cfg``
.. code:: yaml
@@ -90,13 +124,25 @@ templates and also require CloudStack password and sshkey
scripts (:ref:`adding-
- CloudStack
-user-data example
-~~~~~~~~~~~~~~~~~
+Custom user-data example
+~~~~~~~~~~~~~~~~~~~~~~~~
-This example use cloud-init to Upgrade Operating-System of the newly created
VM:
+This example uses cloud-init to automatically update all OS packages on the
first launch.
-.. code:: yaml
+#. Create user-data, wrapped into a multi-part MIME message and encoded in
base64:
+.. 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
@@ -105,15 +151,18 @@ This example use cloud-init to Upgrade Operating-System
of the newly created VM:
# Default: false
# Aliases: apt_upgrade
package_upgrade: true
+ EOF
+
+#. Deploy a VM with this user-data:
+.. code:: bash
-base64 formated:
+ cmk deploy virtualmachine name=.....
userdata=Q29udGVudC1UeXBlOiBtdWx0aXBhcnQvbWl4ZWQ7IGJvdW5kYXJ5PSIvLyIKTUlNRS1WZXJzaW9uOiAxLjAKCi0tLy8KQ29udGVudC1UeXBlOiB0ZXh0L2Nsb3VkLWNvbmZpZzsgY2hhcnNldD0idXMtYXNjaWkiCk1JTUUtVmVyc2lvbjogMS4wCkNvbnRlbnQtVHJhbnNmZXItRW5jb2Rpbmc6IDdiaXQKQ29udGVudC1EaXNwb3NpdGlvbjogYXR0YWNobWVudDsgZmlsZW5hbWU9ImNsb3VkLWNvbmZpZy50eHQiCgojY2xvdWQtY29uZmlnCgojIFVwZ3JhZGUgdGhlIGluc3RhbmNlIG9uIGZpcnN0IGJvb3QKIyAoaWUgcnVuIGFwdC1nZXQgdXBncmFkZSkKIwojIERlZmF1bHQ6IGZhbHNlCiM
[...]
-.. code:: bash
-
I2Nsb3VkLWNvbmZpZw0KDQojIFVwZ3JhZGUgdGhlIGluc3RhbmNlIG9uIGZpcnN0IGJvb3QNCiMgKGllIHJ1biBhcHQtZ2V0IHVwZ3JhZGUpDQojDQojIERlZmF1bHQ6IGZhbHNlDQojIEFsaWFzZXM6IGFwdF91cGdyYWRlDQpwYWNrYWdlX3VwZ3JhZGU6IHRydWUNCg==
+Disclaimer
+~~~~~~~~~~
-Refer to `Cloud-Init CloudStack datasource
<http://cloudinit.readthedocs.org/en/latest/topics/datasources.html#cloudstack>`_
-documentation for latest capabilities. Cloud-Init and Cloud-Init CloudStack
+Refer to the `cloud-init CloudStack datasource
<http://cloudinit.readthedocs.org/en/latest/topics/datasources.html#cloudstack>`_
+documentation for latest capabilities. cloud-init and the cloud-init CloudStack
datasource are not supported by Apache CloudStack community.
-
