You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cloudstack.apache.org by pd...@apache.org on 2015/03/08 02:57:53 UTC
cloudstack-docs-admin git commit: CLOUDSTACK-489: add user-data and
cloud-init documentation into virtual-machine
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 <pd...@apache.org>
Authored: Sat Mar 7 20:57:35 2015 -0500
Committer: Pierre-Luc Dion <pd...@apache.org>
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.
+