Repository: cloudstack-docs-admin Updated Branches: refs/heads/master 8f4c7dcc1 -> e51a1a4c2
CLOUDSTACK-489: add user-data and cloud-init documentation into virtual-machine Project: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/repo Commit: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/commit/e51a1a4c Tree: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/tree/e51a1a4c Diff: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/diff/e51a1a4c Branch: refs/heads/master Commit: e51a1a4c26b8d84e58048254ae591dd7fe5ff7db Parents: 8f4c7dc Author: Pierre-Luc Dion <[email protected]> Authored: Sat Mar 7 20:57:35 2015 -0500 Committer: Pierre-Luc Dion <[email protected]> Committed: Sat Mar 7 20:57:35 2015 -0500 ---------------------------------------------------------------------- source/virtual_machines.rst | 2 + source/virtual_machines/user-data.rst | 119 +++++++++++++++++++++++++++++ 2 files changed, 121 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/e51a1a4c/source/virtual_machines.rst ---------------------------------------------------------------------- diff --git a/source/virtual_machines.rst b/source/virtual_machines.rst index a4db70f..5296204 100644 --- a/source/virtual_machines.rst +++ b/source/virtual_machines.rst @@ -1167,6 +1167,8 @@ compromised SSH keypair can be changed, and the user can access the VM by using the new keypair. Just create or register a new keypair, then call resetSSHKeyForVirtualMachine. +.. include:: virtual_machines/user-data.rst + .. |basic-deployment.png| image:: _static/images/basic-deployment.png :alt: Basic two-machine CloudStack deployment http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/e51a1a4c/source/virtual_machines/user-data.rst ---------------------------------------------------------------------- diff --git a/source/virtual_machines/user-data.rst b/source/virtual_machines/user-data.rst new file mode 100644 index 0000000..49c2c1b --- /dev/null +++ b/source/virtual_machines/user-data.rst @@ -0,0 +1,119 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information# + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + + +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. + +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/>`_. + +Accessed user-data from VM. Once the IP address of the virtual router is +known, use the following steps to retrieve user-data: + +#. Run the following command to find the virtual router. + + .. code:: bash + + # cat /var/lib/dhclient/dhclient-eth0.leases | grep dhcp-server-identifier | tail -1 + +#. Access user-data by running the following command using the result of + the above command + + .. code:: bash + + # 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: + +- ``service-offering``. A description of the VMs service offering + +- ``availability-zone``. The Zone name + +- ``local-ipv4``. The guest IP of the VM + +- ``local-hostname``. The hostname of the VM + +- ``public-ipv4``. The first public IP for the router. (E.g. the first IP + of eth2) + +- ``public-hostname``. This is the same as public-ipv4 + +- ``instance-id``. The instance name of the VM + + +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. + +#. Install cloud-init package into a template: + + .. code:: bash + + # yum install cloud-init + or + $ sudo apt-get install cloud-init + +#. Create datasource configuration file: ``/etc/cloud/cloud.cfg.d/99_cloudstack.cfg`` + + .. code:: yaml + + datasource: + CloudStack: {} + None: {} + datasource_list: + - CloudStack + + +user-data example +~~~~~~~~~~~~~~~~~ + +This example use cloud-init to Upgrade Operating-System of the newly created VM: + +.. code:: yaml + + #cloud-config + + # Upgrade the instance on first boot + # (ie run apt-get upgrade) + # + # Default: false + # Aliases: apt_upgrade + package_upgrade: true + + +base64 formated: + +.. code:: bash + + I2Nsb3VkLWNvbmZpZw0KDQojIFVwZ3JhZGUgdGhlIGluc3RhbmNlIG9uIGZpcnN0IGJvb3QNCiMgKGllIHJ1biBhcHQtZ2V0IHVwZ3JhZGUpDQojDQojIERlZmF1bHQ6IGZhbHNlDQojIEFsaWFzZXM6IGFwdF91cGdyYWRlDQpwYWNrYWdlX3VwZ3JhZGU6IHRydWUNCg== + +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 +datasource are not supported by Apache CloudStack community. +
