| .. 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. |
| |