diff --git a/source/adminguide/virtual_machines/user-data.rst b/source/adminguide/virtual_machines/user-data.rst index 3a84ea16fd..24285e9246 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 `_ -using the parameter ``userdata=`` to include user-data formated in -`base64 `_. +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. -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 `_ +API call: + +.. code:: bash + + cmk get virtualmachineuserdata virtualmachineid=8fd996b6-a102-11ea-ba47-23394b299ae9 + + +Using cloud-init ~~~~~~~~~~~~~~~~ -`Cloud-Init `_ 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 `_). User password management and -``resetSSHKeyForVirtualMachine`` API are not yet supported by cloud-init. +`cloud-init `_ 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 `_). -#. 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 <`_ -documentation for latest capabilities. Cloud-Init and Cloud-Init CloudStack +Refer to the `cloud-init CloudStack datasource `_ +documentation for latest capabilities. cloud-init and the cloud-init CloudStack datasource are not supported by Apache CloudStack community. -