Skip to content

Commit c50d817

Browse files
onitakeonitake
authored
cloud-init and UserData service documentation cleanup (apache#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 caf374e (DHCP lease path) for user-data overhaul
1 parent 111a553 commit c50d817

File tree

1 file changed

+89
-40
lines changed

1 file changed

+89
-40
lines changed

‎source/adminguide/virtual_machines/user-data.rst‎

Lines changed: 89 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -17,35 +17,39 @@
1717
User-Data and Meta-Data
1818
-----------------------
1919

20-
CloudStack provides API access to attach up to 2KB of data after base64 encoding
21-
to a deployed VM. Using HTTP POST(via POST body), you can send up to 32K of data
22-
after base64 encoding. Deployed VMs also have access to instance metadata via
23-
the virtual router.
20+
CloudStack provides APIs to attach up to 32KB of user-data to a deployed VM.
2421

25-
Create virtual machine thru the API: `deployVirtualMachine <http://cloudstack.apache.org/docs/api/apidocs-4.5/user/deployVirtualMachine.html>`_
26-
using the parameter ``userdata=`` to include user-data formated in
27-
`base64 <https://www.base64encode.org/>`_.
22+
There are two CloudStack APIs that can be used to store user-data:
23+
`deployVirtualMachine <http://cloudstack.apache.org/docs/api/apidocs-4.14/user/deployVirtualMachine.html>`_
24+
and
25+
`updateVirtualMachine <http://cloudstack.apache.org/docs/api/apidocs-4.14/user/updateVirtualMachine.html>`_
26+
They both support the parameter ``userdata=``. The value for this parameter
27+
must be a `base64 <https://www.base64encode.org/>`_-encoded multi-part MIME
28+
message. See further below for an example of what this should look like.
2829

29-
Accessed user-data from VM. Once the IP address of the virtual router is
30-
known, use the following steps to retrieve user-data:
30+
HTTP GET parameters are limited to a length of 2048 bytes, but it is possible
31+
to store larger user-data blobs by sending them in the body via HTTP POST
32+
instead of GET.
3133

32-
#. Run the following command to find the virtual router.
34+
From inside the VM, the user-data is accessible via the virtual router,
35+
if the UserData service is enabled on the network offering.
3336

34-
.. code:: bash
37+
If you are using the DNS service of the virtual router, a special hostname
38+
called `data-server.` is provided, that will point to a valid user-data server.
3539

36-
# cat /var/lib/dhcp/dhclient.eth0.leases | grep dhcp-server-identifier | tail -1
40+
Otherwise you have to determine the virtual router address via other means,
41+
such as DHCP leases. Be careful to scan all routers if you have multiple
42+
networks attached to a VM, in case not all of them have the UserData service
43+
enabled.
3744

38-
#. Access user-data by running the following command using the result of
39-
the above command
45+
User-data is available from the URL ``http://data-server./latest/user-data``
46+
and can be fetched via curl or other HTTP client.
4047

41-
.. code:: bash
48+
It is also possible to fetch VM metadata from the same service, via the URL
49+
``http://data-server./latest/{metadata type}``. For backwards compatibility,
50+
the previous URL ``http://data-server./latest/{metadata type}`` is also supported.
4251

43-
# curl http://10.1.1.1/latest/user-data
44-
45-
Meta Data can be accessed similarly, using a URL of the form
46-
``http://10.1.1.1/latest/meta-data/{metadata type}``. (For backwards
47-
compatibility, the previous URL ``http://10.1.1.1/latest/{metadata type}``
48-
is also supported.) For metadata type, use one of the following:
52+
For metadata type, use one of the following:
4953

5054
- ``service-offering``. A description of the VMs service offering
5155

@@ -55,31 +59,61 @@ is also supported.) For metadata type, use one of the following:
5559

5660
- ``local-hostname``. The hostname of the VM
5761

58-
- ``public-ipv4``. The first public IP for the router. (E.g. the first IP
59-
of eth2)
62+
- ``public-ipv4``. The first public IP for the router.
6063

6164
- ``public-hostname``. This is the same as public-ipv4
6265

6366
- ``instance-id``. The instance name of the VM
6467

6568

66-
Using Cloud-Init
69+
Determining the virtual router address without DNS
70+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
71+
72+
If can't or don't want to use the virtual router's DNS service, it's also
73+
possible to determine the user-data server from a DHCP lease.
74+
75+
#. Run the following command to find the virtual router.
76+
77+
.. code:: bash
78+
79+
# cat /var/lib/dhcp/dhclient.eth0.leases | grep dhcp-server-identifier | tail -1
80+
81+
#. Access the data-server via its IP
82+
83+
.. code:: bash
84+
85+
# curl http://10.1.1.1/latest/user-data
86+
87+
88+
Fetching user-data via the API
89+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
90+
91+
User-data is not included with the normal VM state for historic reasons.
92+
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>`_
93+
API call:
94+
95+
.. code:: bash
96+
97+
cmk get virtualmachineuserdata virtualmachineid=8fd996b6-a102-11ea-ba47-23394b299ae9
98+
99+
100+
Using cloud-init
67101
~~~~~~~~~~~~~~~~
68102

69-
`Cloud-Init <https://cloudinit.readthedocs.org/en/latest>`_ can be use to access
70-
an interpret user-data from virtual machines. Cloud-Init be installed into
71-
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
72-
``resetSSHKeyForVirtualMachine`` API are not yet supported by cloud-init.
103+
`cloud-init <https://cloudinit.readthedocs.org/en/latest>`_ can be used to access
104+
and interpret user-data inside virtual machines. If you install cloud-init into your
105+
VM templates, it will allow you to store SSH keys and user passwords on each new
106+
VM deployment automatically (:ref:`adding-password-management-to-templates` and `using ssh keys <virtual_machines.html#using-ssh-keys-for-authentication>`_).
73107

74-
#. Install cloud-init package into a template:
108+
#. Install cloud-init package into a VM template:
75109

76110
.. code:: bash
77111
78112
# yum install cloud-init
79113
or
80114
$ sudo apt-get install cloud-init
81115
82-
#. Create datasource configuration file: ``/etc/cloud/cloud.cfg.d/99_cloudstack.cfg``
116+
#. Create a datasource configuration file in the VM template: ``/etc/cloud/cloud.cfg.d/99_cloudstack.cfg``
83117

84118
.. code:: yaml
85119
@@ -90,13 +124,25 @@ templates and also require CloudStack password and sshkey scripts (:ref:`adding-
90124
- CloudStack
91125
92126
93-
user-data example
94-
~~~~~~~~~~~~~~~~~
127+
Custom user-data example
128+
~~~~~~~~~~~~~~~~~~~~~~~~
95129

96-
This example use cloud-init to Upgrade Operating-System of the newly created VM:
130+
This example uses cloud-init to automatically update all OS packages on the first launch.
97131

98-
.. code:: yaml
132+
#. Create user-data, wrapped into a multi-part MIME message and encoded in base64:
99133

134+
.. code:: bash
135+
136+
base64 <<EOF
137+
Content-Type: multipart/mixed; boundary="//"
138+
MIME-Version: 1.0
139+
140+
--//
141+
Content-Type: text/cloud-config; charset="us-ascii"
142+
MIME-Version: 1.0
143+
Content-Transfer-Encoding: 7bit
144+
Content-Disposition: attachment; filename="cloud-config.txt"
145+
100146
#cloud-config
101147
102148
# Upgrade the instance on first boot
@@ -105,15 +151,18 @@ This example use cloud-init to Upgrade Operating-System of the newly created VM:
105151
# Default: false
106152
# Aliases: apt_upgrade
107153
package_upgrade: true
154+
EOF
155+
156+
#. Deploy a VM with this user-data:
108157
158+
.. code:: bash
109159
110-
base64 formated:
160+
cmk deploy virtualmachine name=..... userdata=Q29udGVudC1UeXBlOiBtdWx0aXBhcnQvbWl4ZWQ7IGJvdW5kYXJ5PSIvLyIKTUlNRS1WZXJzaW9uOiAxLjAKCi0tLy8KQ29udGVudC1UeXBlOiB0ZXh0L2Nsb3VkLWNvbmZpZzsgY2hhcnNldD0idXMtYXNjaWkiCk1JTUUtVmVyc2lvbjogMS4wCkNvbnRlbnQtVHJhbnNmZXItRW5jb2Rpbmc6IDdiaXQKQ29udGVudC1EaXNwb3NpdGlvbjogYXR0YWNobWVudDsgZmlsZW5hbWU9ImNsb3VkLWNvbmZpZy50eHQiCgojY2xvdWQtY29uZmlnCgojIFVwZ3JhZGUgdGhlIGluc3RhbmNlIG9uIGZpcnN0IGJvb3QKIyAoaWUgcnVuIGFwdC1nZXQgdXBncmFkZSkKIwojIERlZmF1bHQ6IGZhbHNlCiMgQWxpYXNlczogYXB0X3VwZ3JhZGUKcGFja2FnZV91cGdyYWRlOiB0cnVlCg==
111161
112-
.. code:: bash
113162
114-
I2Nsb3VkLWNvbmZpZw0KDQojIFVwZ3JhZGUgdGhlIGluc3RhbmNlIG9uIGZpcnN0IGJvb3QNCiMgKGllIHJ1biBhcHQtZ2V0IHVwZ3JhZGUpDQojDQojIERlZmF1bHQ6IGZhbHNlDQojIEFsaWFzZXM6IGFwdF91cGdyYWRlDQpwYWNrYWdlX3VwZ3JhZGU6IHRydWUNCg==
163+
Disclaimer
164+
~~~~~~~~~~
115165
116-
Refer to `Cloud-Init CloudStack datasource <http://cloudinit.readthedocs.org/en/latest/topics/datasources.html#cloudstack>`_
117-
documentation for latest capabilities. Cloud-Init and Cloud-Init CloudStack
166+
Refer to the `cloud-init CloudStack datasource <http://cloudinit.readthedocs.org/en/latest/topics/datasources.html#cloudstack>`_
167+
documentation for latest capabilities. cloud-init and the cloud-init CloudStack
118168
datasource are not supported by Apache CloudStack community.
119-

0 commit comments

Comments
 (0)