You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cloudstack.apache.org by ra...@apache.org on 2014/09/10 08:42:23 UTC
[09/43] Fixed formatting by Will stevens
http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/68c20df4/source/usage.rst
----------------------------------------------------------------------
diff --git a/source/usage.rst b/source/usage.rst
index 16d6e9c..6324bbb 100644
--- a/source/usage.rst
+++ b/source/usage.rst
@@ -29,48 +29,35 @@ template storage space, consumed by guest instances.
The Usage Server runs at least once per day. It can be configured to run
multiple times per day.
+
Configuring the Usage Server
----------------------------
To configure the usage server:
-#.
-
- Be sure the Usage Server has been installed. This requires extra
+#. Be sure the Usage Server has been installed. This requires extra
steps beyond just installing the CloudStack software. See Installing
the Usage Server (Optional) in the Advanced Installation Guide.
-#.
-
- Log in to the CloudStack UI as administrator.
-
-#.
-
- Click Global Settings.
+#. Log in to the CloudStack UI as administrator.
-#.
+#. Click Global Settings.
- In Search, type usage. Find the configuration parameter that controls
+#. In Search, type usage. Find the configuration parameter that controls
the behavior you want to set. See the table below for a description
of the available parameters.
-#.
+#. In Actions, click the Edit icon.
- In Actions, click the Edit icon.
+#. Type the desired value and click the Save icon.
-#.
-
- Type the desired value and click the Save icon.
-
-#.
-
- Restart the Management Server (as usual with any global configuration
+#. Restart the Management Server (as usual with any global configuration
change) and also the Usage Server:
.. code:: bash
- # service cloudstack-management restart
- # service cloudstack-usage restart
+ # service cloudstack-management restart
+ # service cloudstack-usage restart
The following table shows the global configuration settings that control
the behavior of the Usage Server.
@@ -88,18 +75,20 @@ for the 24 hours from 00:00:00 GMT to 23:59:59 GMT:
.. code:: bash
- usage.stats.job.exec.time = 00:15
- usage.execution.timezone = PST
- usage.aggregation.timezone = GMT
+ usage.stats.job.exec.time = 00:15
+ usage.execution.timezone = PST
+ usage.aggregation.timezone = GMT
-Valid values for the time zone are specified in `Appendix A, *Time Zones* <http://docs.cloudstack.apache.org/en/latest/dev.html?highlight=time%20zones#time-zones>`_
+Valid values for the time zone are specified in `Appendix A, *Time Zones*
+<http://docs.cloudstack.apache.org/en/latest/dev.html?highlight=time%20zones#time-zones>`_
Default: GMT
usage.execution.timezone
The time zone of usage.stats.job.exec.time. Valid values for the time
-zone are specified in `Appendix A, *Time Zones* <http://docs.cloudstack.apache.org/en/latest/dev.html?highlight=time%20zones#time-zones>`_
+zone are specified in `Appendix A, *Time Zones*
+<http://docs.cloudstack.apache.org/en/latest/dev.html?highlight=time%20zones#time-zones>`_
Default: The time zone of the management server.
@@ -150,33 +139,26 @@ predominantly in the East Coast of the United States, and you would like
to process usage records every night at 2 AM local (EST) time. Choose
these settings:
--
-
- enable.usage.server = true
-
--
+- enable.usage.server = true
- usage.execution.timezone = America/New\_York
+- usage.execution.timezone = America/New\_York
--
-
- usage.stats.job.exec.time = 07:00. This will run the Usage job at
+- usage.stats.job.exec.time = 07:00. This will run the Usage job at
2:00 AM EST. Note that this will shift by an hour as the East Coast
of the U.S. enters and exits Daylight Savings Time.
--
-
- usage.stats.job.aggregation.range = 1440
+- usage.stats.job.aggregation.range = 1440
With this configuration, the Usage job will run every night at 2 AM EST
and will process records for the previous day’s midnight-midnight as
defined by the EST (America/New\_York) time zone.
.. note::
- Because the special value 1440 has been used for
- usage.stats.job.aggregation.range, the Usage Server will ignore the data
- between midnight and 2 AM. That data will be included in the next day's
- run.
+ Because the special value 1440 has been used for
+ usage.stats.job.aggregation.range, the Usage Server will ignore the data
+ between midnight and 2 AM. That data will be included in the next day's
+ run.
+
Setting Usage Limits
--------------------
@@ -186,6 +168,7 @@ resource usage by users. Some of these limits are global configuration
parameters. Others are applied at the ROOT domain and may be overridden
on a per-account basis.
+
Globally Configured Limits
~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -241,21 +224,13 @@ classified as CPU, RAM, Primary storage, and Secondary storage. The root
administrator is able to impose resource usage limit by the following
resource types for Domain, Project, and Accounts.
--
-
- CPUs
+- CPUs
--
+- Memory (RAM)
- Memory (RAM)
+- Primary Storage (Volumes)
--
-
- Primary Storage (Volumes)
-
--
-
- Secondary Storage (Snapshots, Templates, ISOs)
+- Secondary Storage (Snapshots, Templates, ISOs)
To control the behaviour of this feature, the following configuration
parameters have been added:
@@ -281,6 +256,7 @@ max.project.secondary.storage (GB) Maximum secondary storage space that can be
Default is 400.
=================================== =================================================================
+
User Permission
~~~~~~~~~~~~~~~
@@ -288,53 +264,38 @@ The root administrator, domain administrators and users are able to list
resources. Ensure that proper logs are maintained in the ``vmops.log``
and ``api.log`` files.
--
-
- The root admin will have the privilege to list and update resource
+- The root admin will have the privilege to list and update resource
limits.
--
-
- The domain administrators are allowed to list and change these
+- The domain administrators are allowed to list and change these
resource limits only for the sub-domains and accounts under their own
domain or the sub-domains.
--
-
- The end users will the privilege to list resource limits. Use the
+- The end users will the privilege to list resource limits. Use the
listResourceLimits API.
+
Limit Usage Considerations
~~~~~~~~~~~~~~~~~~~~~~~~~~
--
-
- Primary or Secondary storage space refers to the stated size of the
+- Primary or Secondary storage space refers to the stated size of the
volume and not the physical size— the actual consumed size on disk in
case of thin provisioning.
--
-
- If the admin reduces the resource limit for an account and set it to
+- If the admin reduces the resource limit for an account and set it to
less than the resources that are currently being consumed, the
existing VMs/templates/volumes are not destroyed. Limits are imposed
only if the user under that account tries to execute a new operation
using any of these resources. For example, the existing behavior in
the case of a VM are:
- -
-
- migrateVirtualMachine: The users under that account will be able
+ - migrateVirtualMachine: The users under that account will be able
to migrate the running VM into any other host without facing any
limit issue.
- -
-
- recoverVirtualMachine: Destroyed VMs cannot be recovered.
-
--
+ - recoverVirtualMachine: Destroyed VMs cannot be recovered.
- For any resource type, if a domain has limit X, sub-domains or
+- For any resource type, if a domain has limit X, sub-domains or
accounts under that domain can have there own limits. However, the
sum of resource allocated to a sub-domain or accounts under the
domain at any point of time should not exceed the value X.
@@ -344,15 +305,14 @@ Limit Usage Considerations
time the resource allocated to D1 and A1 should not exceed the limit
of 40.
--
-
- If any operation needs to pass through two of more resource limit
+- If any operation needs to pass through two of more resource limit
check, then the lower of 2 limits will be enforced, For example: if
an account has the VM limit of 10 and CPU limit of 20, and a user
under that account requests 5 VMs of 4 CPUs each. The user can deploy
5 more VMs because VM limit is 10. However, the user cannot deploy
any more instances because the CPU limit has been exhausted.
+
Limiting Resource Usage in a Domain
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -367,76 +327,65 @@ domain.
To set a domain limit:
-#.
-
- Log in to the CloudStack UI.
-
-#.
-
- In the left navigation tree, click Domains.
+#. Log in to the CloudStack UI.
-#.
+#. In the left navigation tree, click Domains.
- Select the domain you want to modify. The current domain limits are
+#. Select the domain you want to modify. The current domain limits are
displayed.
A value of -1 shows that there is no limit in place.
-#.
+#. Click the Edit button |editbutton.png|
- Click the Edit button |editbutton.png|
+#. Edit the following as per your requirement:
-#.
+ - Parameter Name
- Edit the following as per your requirement:
+ - Description
- Parameter Name
+ - Instance Limits
- Description
+ The number of instances that can be used in a domain.
- Instance Limits
+ - Public IP Limits
- The number of instances that can be used in a domain.
+ The number of public IP addresses that can be used in a domain.
- Public IP Limits
+ - Volume Limits
- The number of public IP addresses that can be used in a domain.
+ The number of disk volumes that can be created in a domain.
- Volume Limits
+ - Snapshot Limits
- The number of disk volumes that can be created in a domain.
+ The number of snapshots that can be created in a domain.
- Snapshot Limits
+ - Template Limits
- The number of snapshots that can be created in a domain.
+ The number of templates that can be registered in a domain.
- Template Limits
+ - VPC limits
- The number of templates that can be registered in a domain.
+ The number of VPCs that can be created in a domain.
- VPC limits
+ - CPU limits
- The number of VPCs that can be created in a domain.
+ The number of CPU cores that can be used for a domain.
- CPU limits
+ - Memory limits (MB)
- The number of CPU cores that can be used for a domain.
+ The number of RAM that can be used for a domain.
- Memory limits (MB)
+ - Primary Storage limits (GB)
- The number of RAM that can be used for a domain.
+ The primary storage space that can be used for a domain.
- Primary Storage limits (GB)
+ - Secondary Storage limits (GB)
- The primary storage space that can be used for a domain.
+ The secondary storage space that can be used for a domain.
- Secondary Storage limits (GB)
+#. Click Apply.
- The secondary storage space that can be used for a domain.
-
-#.
-
- Click Apply.
Default Account Resource Limits
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -449,96 +398,84 @@ max.account, for example: max.account.snapshots.
To override a default limit for a particular account, set a per-account
resource limit.
-#.
-
- Log in to the CloudStack UI.
-
-#.
+#. Log in to the CloudStack UI.
- In the left navigation tree, click Accounts.
+#. In the left navigation tree, click Accounts.
-#.
-
- Select the account you want to modify. The current limits are
+#. Select the account you want to modify. The current limits are
displayed.
A value of -1 shows that there is no limit in place.
-#.
-
- Click the Edit button. |editbutton.png|
-
-#.
+#. Click the Edit button. |editbutton.png|
- Edit the following as per your requirement:
+#. Edit the following as per your requirement:
- Parameter Name
+ - Parameter Name
- Description
+ - Description
- Instance Limits
+ - Instance Limits
- The number of instances that can be used in an account.
+ The number of instances that can be used in an account.
- The default is 20.
+ The default is 20.
- Public IP Limits
+ - Public IP Limits
- The number of public IP addresses that can be used in an account.
+ The number of public IP addresses that can be used in an account.
- The default is 20.
+ The default is 20.
- Volume Limits
+ - Volume Limits
- The number of disk volumes that can be created in an account.
+ The number of disk volumes that can be created in an account.
- The default is 20.
+ The default is 20.
- Snapshot Limits
+ - Snapshot Limits
- The number of snapshots that can be created in an account.
+ The number of snapshots that can be created in an account.
- The default is 20.
+ The default is 20.
- Template Limits
+ - Template Limits
- The number of templates that can be registered in an account.
+ The number of templates that can be registered in an account.
- The default is 20.
+ The default is 20.
- VPC limits
+ - VPC limits
- The number of VPCs that can be created in an account.
+ The number of VPCs that can be created in an account.
- The default is 20.
+ The default is 20.
- CPU limits
+ - CPU limits
- The number of CPU cores that can be used for an account.
+ The number of CPU cores that can be used for an account.
- The default is 40.
+ The default is 40.
- Memory limits (MB)
+ - Memory limits (MB)
- The number of RAM that can be used for an account.
+ The number of RAM that can be used for an account.
- The default is 40960.
+ The default is 40960.
- Primary Storage limits (GB)
+ - Primary Storage limits (GB)
- The primary storage space that can be used for an account.
+ The primary storage space that can be used for an account.
- The default is 200.
+ The default is 200.
- Secondary Storage limits (GB)
+ - Secondary Storage limits (GB)
- The secondary storage space that can be used for an account.
+ The secondary storage space that can be used for an account.
- The default is 400.
+ The default is 400.
-#.
-
- Click Apply.
+#. Click Apply.
Usage Record Format
@@ -550,450 +487,257 @@ Virtual Machine Usage Record Format
For running and allocated virtual machine usage, the following fields
exist in a usage record:
--
-
- account – name of the account
-
--
-
- accountid – ID of the account
-
--
-
- domainid – ID of the domain in which this account resides
-
--
+- account – name of the account
- zoneid – Zone where the usage occurred
+- accountid – ID of the account
--
+- domainid – ID of the domain in which this account resides
- description – A string describing what the usage record is tracking
+- zoneid – Zone where the usage occurred
--
+- description – A string describing what the usage record is tracking
- usage – String representation of the usage, including the units of
+- usage – String representation of the usage, including the units of
usage (e.g. 'Hrs' for VM running time)
--
+- usagetype – A number representing the usage type (see Usage Types)
- usagetype – A number representing the usage type (see Usage Types)
+- rawusage – A number representing the actual usage in hours
--
+- virtualMachineId – The ID of the virtual machine
- rawusage – A number representing the actual usage in hours
+- name – The name of the virtual machine
--
+- offeringid – The ID of the service offering
- virtualMachineId – The ID of the virtual machine
-
--
-
- name – The name of the virtual machine
-
--
-
- offeringid – The ID of the service offering
-
--
-
- templateid – The ID of the template or the ID of the parent template.
+- templateid – The ID of the template or the ID of the parent template.
The parent template value is present when the current template was
created from a volume.
--
-
- usageid – Virtual machine
-
--
-
- type – Hypervisor
+- usageid – Virtual machine
--
+- type – Hypervisor
- startdate, enddate – The range of time for which the usage is
+- startdate, enddate – The range of time for which the usage is
aggregated; see Dates in the Usage Record
+
Network Usage Record Format
~~~~~~~~~~~~~~~~~~~~~~~~~~~
For network usage (bytes sent/received), the following fields exist in a
usage record.
--
-
- account – name of the account
-
--
-
- accountid – ID of the account
-
--
-
- domainid – ID of the domain in which this account resides
-
--
-
- zoneid – Zone where the usage occurred
-
--
+- account – name of the account
- description – A string describing what the usage record is tracking
+- accountid – ID of the account
--
+- domainid – ID of the domain in which this account resides
- usagetype – A number representing the usage type (see Usage Types)
+- zoneid – Zone where the usage occurred
--
+- description – A string describing what the usage record is tracking
- rawusage – A number representing the actual usage in hours
+- usagetype – A number representing the usage type (see Usage Types)
--
+- rawusage – A number representing the actual usage in hours
- usageid – Device ID (virtual router ID or external device ID)
+- usageid – Device ID (virtual router ID or external device ID)
--
+- type – Device type (domain router, external load balancer, etc.)
- type – Device type (domain router, external load balancer, etc.)
-
--
-
- startdate, enddate – The range of time for which the usage is
+- startdate, enddate – The range of time for which the usage is
aggregated; see Dates in the Usage Record
+
IP Address Usage Record Format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For IP address usage the following fields exist in a usage record.
--
-
- account - name of the account
-
--
-
- accountid - ID of the account
-
--
-
- domainid - ID of the domain in which this account resides
-
--
+- account - name of the account
- zoneid - Zone where the usage occurred
+- accountid - ID of the account
--
+- domainid - ID of the domain in which this account resides
- description - A string describing what the usage record is tracking
+- zoneid - Zone where the usage occurred
--
+- description - A string describing what the usage record is tracking
- usage - String representation of the usage, including the units of
+- usage - String representation of the usage, including the units of
usage
--
+- usagetype - A number representing the usage type (see Usage Types)
- usagetype - A number representing the usage type (see Usage Types)
+- rawusage - A number representing the actual usage in hours
--
+- usageid - IP address ID
- rawusage - A number representing the actual usage in hours
-
--
-
- usageid - IP address ID
-
--
-
- startdate, enddate - The range of time for which the usage is
+- startdate, enddate - The range of time for which the usage is
aggregated; see Dates in the Usage Record
--
-
- issourcenat - Whether source NAT is enabled for the IP address
+- issourcenat - Whether source NAT is enabled for the IP address
--
+- iselastic - True if the IP address is elastic.
- iselastic - True if the IP address is elastic.
Disk Volume Usage Record Format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For disk volumes, the following fields exist in a usage record.
--
-
- account – name of the account
-
--
-
- accountid – ID of the account
-
--
-
- domainid – ID of the domain in which this account resides
+- account – name of the account
--
+- accountid – ID of the account
- zoneid – Zone where the usage occurred
+- domainid – ID of the domain in which this account resides
--
+- zoneid – Zone where the usage occurred
- description – A string describing what the usage record is tracking
+- description – A string describing what the usage record is tracking
--
-
- usage – String representation of the usage, including the units of
+- usage – String representation of the usage, including the units of
usage (e.g. 'Hrs' for hours)
--
-
- usagetype – A number representing the usage type (see Usage Types)
-
--
-
- rawusage – A number representing the actual usage in hours
-
--
-
- usageid – The volume ID
-
--
-
- offeringid – The ID of the disk offering
-
--
+- usagetype – A number representing the usage type (see Usage Types)
- type – Hypervisor
+- rawusage – A number representing the actual usage in hours
--
+- usageid – The volume ID
- templateid – ROOT template ID
+- offeringid – The ID of the disk offering
--
+- type – Hypervisor
- size – The amount of storage allocated
+- templateid – ROOT template ID
--
+- size – The amount of storage allocated
- startdate, enddate – The range of time for which the usage is
+- startdate, enddate – The range of time for which the usage is
aggregated; see Dates in the Usage Record
+
Template, ISO, and Snapshot Usage Record Format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--
-
- account – name of the account
-
--
-
- accountid – ID of the account
-
--
+- account – name of the account
- domainid – ID of the domain in which this account resides
+- accountid – ID of the account
--
+- domainid – ID of the domain in which this account resides
- zoneid – Zone where the usage occurred
+- zoneid – Zone where the usage occurred
--
+- description – A string describing what the usage record is tracking
- description – A string describing what the usage record is tracking
-
--
-
- usage – String representation of the usage, including the units of
+- usage – String representation of the usage, including the units of
usage (e.g. 'Hrs' for hours)
--
-
- usagetype – A number representing the usage type (see Usage Types)
-
--
+- usagetype – A number representing the usage type (see Usage Types)
- rawusage – A number representing the actual usage in hours
+- rawusage – A number representing the actual usage in hours
--
+- usageid – The ID of the the template, ISO, or snapshot
- usageid – The ID of the the template, ISO, or snapshot
+- offeringid – The ID of the disk offering
--
-
- offeringid – The ID of the disk offering
-
--
-
- templateid – – Included only for templates (usage type 7). Source
+- templateid – – Included only for templates (usage type 7). Source
template ID.
--
-
- size – Size of the template, ISO, or snapshot
-
--
+- size – Size of the template, ISO, or snapshot
- startdate, enddate – The range of time for which the usage is
+- startdate, enddate – The range of time for which the usage is
aggregated; see Dates in the Usage Record
+
Load Balancer Policy or Port Forwarding Rule Usage Record Format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--
-
- account - name of the account
-
--
-
- accountid - ID of the account
+- account - name of the account
--
+- accountid - ID of the account
- domainid - ID of the domain in which this account resides
+- domainid - ID of the domain in which this account resides
--
+- zoneid - Zone where the usage occurred
- zoneid - Zone where the usage occurred
+- description - A string describing what the usage record is tracking
--
-
- description - A string describing what the usage record is tracking
-
--
-
- usage - String representation of the usage, including the units of
+- usage - String representation of the usage, including the units of
usage (e.g. 'Hrs' for hours)
--
-
- usagetype - A number representing the usage type (see Usage Types)
-
--
+- usagetype - A number representing the usage type (see Usage Types)
- rawusage - A number representing the actual usage in hours
+- rawusage - A number representing the actual usage in hours
--
+- usageid - ID of the load balancer policy or port forwarding rule
- usageid - ID of the load balancer policy or port forwarding rule
+- usagetype - A number representing the usage type (see Usage Types)
--
-
- usagetype - A number representing the usage type (see Usage Types)
-
--
-
- startdate, enddate - The range of time for which the usage is
+- startdate, enddate - The range of time for which the usage is
aggregated; see Dates in the Usage Record
+
Network Offering Usage Record Format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--
-
- account – name of the account
+- account – name of the account
--
+- accountid – ID of the account
- accountid – ID of the account
+- domainid – ID of the domain in which this account resides
--
+- zoneid – Zone where the usage occurred
- domainid – ID of the domain in which this account resides
+- description – A string describing what the usage record is tracking
--
-
- zoneid – Zone where the usage occurred
-
--
-
- description – A string describing what the usage record is tracking
-
--
-
- usage – String representation of the usage, including the units of
+- usage – String representation of the usage, including the units of
usage (e.g. 'Hrs' for hours)
--
-
- usagetype – A number representing the usage type (see Usage Types)
-
--
-
- rawusage – A number representing the actual usage in hours
-
--
+- usagetype – A number representing the usage type (see Usage Types)
- usageid – ID of the network offering
+- rawusage – A number representing the actual usage in hours
--
+- usageid – ID of the network offering
- usagetype – A number representing the usage type (see Usage Types)
+- usagetype – A number representing the usage type (see Usage Types)
--
+- offeringid – Network offering ID
- offeringid – Network offering ID
+- virtualMachineId – The ID of the virtual machine
--
+- virtualMachineId – The ID of the virtual machine
- virtualMachineId – The ID of the virtual machine
-
--
-
- virtualMachineId – The ID of the virtual machine
-
--
-
- startdate, enddate – The range of time for which the usage is
+- startdate, enddate – The range of time for which the usage is
aggregated; see Dates in the Usage Record
+
VPN User Usage Record Format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--
-
- account – name of the account
-
--
-
- accountid – ID of the account
-
--
+- account – name of the account
- domainid – ID of the domain in which this account resides
+- accountid – ID of the account
--
+- domainid – ID of the domain in which this account resides
- zoneid – Zone where the usage occurred
+- zoneid – Zone where the usage occurred
--
+- description – A string describing what the usage record is tracking
- description – A string describing what the usage record is tracking
-
--
-
- usage – String representation of the usage, including the units of
+- usage – String representation of the usage, including the units of
usage (e.g. 'Hrs' for hours)
--
-
- usagetype – A number representing the usage type (see Usage Types)
-
--
-
- rawusage – A number representing the actual usage in hours
+- usagetype – A number representing the usage type (see Usage Types)
--
+- rawusage – A number representing the actual usage in hours
- usageid – VPN user ID
+- usageid – VPN user ID
--
+- usagetype – A number representing the usage type (see Usage Types)
- usagetype – A number representing the usage type (see Usage Types)
-
--
-
- startdate, enddate – The range of time for which the usage is
+- startdate, enddate – The range of time for which the usage is
aggregated; see Dates in the Usage Record
@@ -1115,29 +859,30 @@ the following whether in HTTP or HTTPS:
::
- <listusagerecordsresponse>
- <count>1816</count>
- <usagerecord>
- <account>user5</account>
- <accountid>10004</accountid>
- <domainid>1</domainid>
- <zoneid>1</zoneid>
- <description>i-3-4-WC running time (ServiceOffering: 1) (Template: 3)</description>
- <usage>2.95288 Hrs</usage>
- <usagetype>1</usagetype>
- <rawusage>2.95288</rawusage>
- <virtualmachineid>4</virtualmachineid>
- <name>i-3-4-WC</name>
- <offeringid>1</offeringid>
- <templateid>3</templateid>
- <usageid>245554</usageid>
- <type>XenServer</type>
- <startdate>2009-09-15T00:00:00-0700</startdate>
- <enddate>2009-09-18T16:14:26-0700</enddate>
- </usagerecord>
-
- … (1,815 more usage records)
- </listusagerecordsresponse>
+ <listusagerecordsresponse>
+ <count>1816</count>
+ <usagerecord>
+ <account>user5</account>
+ <accountid>10004</accountid>
+ <domainid>1</domainid>
+ <zoneid>1</zoneid>
+ <description>i-3-4-WC running time (ServiceOffering: 1) (Template: 3)</description>
+ <usage>2.95288 Hrs</usage>
+ <usagetype>1</usagetype>
+ <rawusage>2.95288</rawusage>
+ <virtualmachineid>4</virtualmachineid>
+ <name>i-3-4-WC</name>
+ <offeringid>1</offeringid>
+ <templateid>3</templateid>
+ <usageid>245554</usageid>
+ <type>XenServer</type>
+ <startdate>2009-09-15T00:00:00-0700</startdate>
+ <enddate>2009-09-18T16:14:26-0700</enddate>
+ </usagerecord>
+
+ … (1,815 more usage records)
+ </listusagerecordsresponse>
+
Dates in the Usage Record
-------------------------
@@ -1174,5 +919,6 @@ date and time of the earliest event. For other types of usage, such as
IP addresses and VMs, the old unprocessed data is not included in daily
aggregation.
+
.. |editbutton.png| image:: _static/images/edit-icon.png
:alt: edits the settings.
http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/68c20df4/source/virtual_machines.rst
----------------------------------------------------------------------
diff --git a/source/virtual_machines.rst b/source/virtual_machines.rst
index 2c9e8a3..a4db70f 100644
--- a/source/virtual_machines.rst
+++ b/source/virtual_machines.rst
@@ -30,24 +30,20 @@ CloudStack and are available for end users to organize their VMs. Each
VM can have three names for use in different contexts. Only two of these
names can be controlled by the user:
--
-
- Instance name – a unique, immutable ID that is generated by
+- Instance name – a unique, immutable ID that is generated by
CloudStack and can not be modified by the user. This name conforms to
the requirements in IETF RFC 1123.
--
-
- Display name – the name displayed in the CloudStack web UI. Can be
+- Display name – the name displayed in the CloudStack web UI. Can be
set by the user. Defaults to instance name.
--
-
- Name – host name that the DHCP server assigns to the VM. Can be set
+- Name – host name that the DHCP server assigns to the VM. Can be set
by the user. Defaults to instance name
.. note::
- You can append the display name of a guest VM to its internal name. For more information, see `“Appending a Display Name to the Guest VM’s Internal Name” <#appending-a-display-name-to-the-guest-vms-internal-name>`_.
+ You can append the display name of a guest VM to its internal name.
+ For more information, see `“Appending a Display Name to the Guest VM’s
+ Internal Name” <#appending-a-display-name-to-the-guest-vms-internal-name>`_.
Guest VMs can be configured to be Highly Available (HA). An HA-enabled
VM is monitored by the system. If the system detects that the VM is
@@ -74,10 +70,13 @@ unexpectedly. If an HA-enabled VM is shut down from inside the VM,
CloudStack will restart it. To shut down an HA-enabled VM, you must go
through the CloudStack UI or API.
+
Best Practices for Virtual Machines
-----------------------------------
-For VMs to work as expected and provide excellent service, follow these guidelines.
+For VMs to work as expected and provide excellent service, follow these
+guidelines.
+
Monitor VMs for Max Capacity
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -99,45 +98,37 @@ cluster is at most (N-1) \* (per-host-limit). Once a cluster reaches
this number of VMs, use the CloudStack UI to disable allocation of more
VMs to the cluster.
+
Install Required Tools and Drivers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Be sure the following are installed on each VM:
--
-
- For XenServer, install PV drivers and Xen tools on each VM. This will
+- For XenServer, install PV drivers and Xen tools on each VM. This will
enable live migration and clean guest shutdown. Xen tools are
required in order for dynamic CPU and RAM scaling to work.
--
-
- For vSphere, install VMware Tools on each VM. This will enable
+- For vSphere, install VMware Tools on each VM. This will enable
console view to work properly. VMware Tools are required in order for
dynamic CPU and RAM scaling to work.
To be sure that Xen tools or VMware Tools is installed, use one of the
following techniques:
--
-
- Create each VM from a template that already has the tools installed;
+- Create each VM from a template that already has the tools installed;
or,
--
-
- When registering a new template, the administrator or user can
+- When registering a new template, the administrator or user can
indicate whether tools are installed on the template. This can be
done through the UI or using the updateTemplate API; or,
--
-
- If a user deploys a virtual machine with a template that does not
+- If a user deploys a virtual machine with a template that does not
have Xen tools or VMware Tools, and later installs the tools on the
VM, then the user can inform CloudStack using the
updateVirtualMachine API. After installing the tools and updating the
virtual machine, stop and start the VM.
+
VM Lifecycle
------------
@@ -171,6 +162,7 @@ The user can manually restart the virtual machine from the down state.
The system will start the virtual machine from the down state
automatically if the virtual machine is marked as HA-enabled.
+
Creating VMs
------------
@@ -180,72 +172,55 @@ machine without an OS template. Users can attach an ISO file and install
the OS from the CD/DVD-ROM.
.. note::
- You can create a VM without starting it. You can determine whether the VM needs to be started as part of the VM deployment. A request parameter, startVM, in the deployVm API provides this feature. For more information, see the Developer's Guide.
+ You can create a VM without starting it. You can determine whether the
+ VM needs to be started as part of the VM deployment. A request parameter,
+ startVM, in the deployVm API provides this feature. For more information,
+ see the Developer's Guide.
To create a VM from a template:
-#.
-
- Log in to the CloudStack UI as an administrator or user.
-
-#.
-
- In the left navigation bar, click Instances.
-
-#.
+#. Log in to the CloudStack UI as an administrator or user.
- Click Add Instance.
+#. In the left navigation bar, click Instances.
-#.
+#. Click Add Instance.
- Select a zone.
+#. Select a zone.
-#.
-
- Select a template, then follow the steps in the wizard. For more
+#. Select a template, then follow the steps in the wizard. For more
information about how the templates came to be in this list, see
`*Working with Templates* <templates.html>`_.
-#.
-
- Be sure that the hardware you have allows starting the selected
+#. Be sure that the hardware you have allows starting the selected
service offering.
-#.
-
- Click Submit and your VM will be created and started.
+#. Click Submit and your VM will be created and started.
.. note::
- For security reason, the internal name of the VM is visible only to the root admin.
+ For security reason, the internal name of the VM is visible
+ only to the root admin.
To create a VM from an ISO:
.. note::
- (XenServer) Windows VMs running on XenServer require PV drivers, which may be provided in the template or added after the VM is created. The PV drivers are necessary for essential management functions such as mounting additional volumes and ISO images, live migration, and graceful shutdown.
-
-#.
-
- Log in to the CloudStack UI as an administrator or user.
+ (XenServer) Windows VMs running on XenServer require PV drivers,
+ which may be provided in the template or added after the VM is
+ created. The PV drivers are necessary for essential management
+ functions such as mounting additional volumes and ISO images,
+ live migration, and graceful shutdown.
-#.
+#. Log in to the CloudStack UI as an administrator or user.
- In the left navigation bar, click Instances.
+#. In the left navigation bar, click Instances.
-#.
+#. Click Add Instance.
- Click Add Instance.
+#. Select a zone.
-#.
+#. Select ISO Boot, and follow the steps in the wizard.
- Select a zone.
+#. Click Submit and your VM will be created and started.
-#.
-
- Select ISO Boot, and follow the steps in the wizard.
-
-#.
-
- Click Submit and your VM will be created and started.
Accessing VMs
-------------
@@ -255,43 +230,32 @@ access all VMs running in the cloud.
To access a VM through the CloudStack UI:
-#.
-
- Log in to the CloudStack UI as a user or admin.
-
-#.
-
- Click Instances, then click the name of a running VM.
+#. Log in to the CloudStack UI as a user or admin.
-#.
+#. Click Instances, then click the name of a running VM.
- Click the View Console button |console-icon.png|.
+#. Click the View Console button |console-icon.png|.
To access a VM directly over the network:
-#.
-
- The VM must have some port open to incoming traffic. For example, in
+#. The VM must have some port open to incoming traffic. For example, in
a basic zone, a new VM might be assigned to a security group which
allows incoming traffic. This depends on what security group you
picked when creating the VM. In other cases, you can open a port by
setting up a port forwarding policy. See `“IP
Forwarding and Firewalling” <networking2.html#ip-forwarding-and-firewalling>`_.
-#.
-
- If a port is open but you can not access the VM using ssh, it’s
+#. If a port is open but you can not access the VM using ssh, it’s
possible that ssh is not already enabled on the VM. This will depend
on whether ssh is enabled in the template you picked when creating
the VM. Access the VM through the CloudStack UI and enable ssh on the
machine using the commands for the VM’s operating system.
-#.
-
- If the network has an external firewall device, you will need to
+#. If the network has an external firewall device, you will need to
create a firewall rule to allow access. See `“IP
Forwarding and Firewalling” <networking2.html#ip-forwarding-and-firewalling>`_.
+
Stopping and Starting VMs
-------------------------
@@ -299,6 +263,7 @@ Once a VM instance is created, you can stop, restart, or delete it as
needed. In the CloudStack UI, click Instances, select the VM, and use
the Stop, Start, Reboot, and Destroy buttons.
+
Assigning VMs to Hosts
----------------------
@@ -306,14 +271,10 @@ At any point in time, each virtual machine instance is running on a
single host. How does CloudStack determine which host to place a VM on?
There are several ways:
--
-
- Automatic default host allocation. CloudStack can automatically pick
+- Automatic default host allocation. CloudStack can automatically pick
the most appropriate host to run each virtual machine.
--
-
- Instance type preferences. CloudStack administrators can specify that
+- Instance type preferences. CloudStack administrators can specify that
certain hosts should have a preference for particular types of guest
instances. For example, an administrator could state that a host
should have a preference to run Windows guests. The default host
@@ -321,41 +282,32 @@ There are several ways:
first. If no such host is available, the allocator will place the
instance wherever there is sufficient physical capacity.
--
-
- Vertical and horizontal allocation. Vertical allocation consumes all
+- Vertical and horizontal allocation. Vertical allocation consumes all
the resources of a given host before allocating any guests on a
second host. This reduces power consumption in the cloud. Horizontal
allocation places a guest on each host in a round-robin fashion. This
may yield better performance to the guests in some cases.
--
-
- End user preferences. Users can not control exactly which host will
+- End user preferences. Users can not control exactly which host will
run a given VM instance, but they can specify a zone for the VM.
CloudStack is then restricted to allocating the VM only to one of the
hosts in that zone.
--
-
- Host tags. The administrator can assign tags to hosts. These tags can
+- Host tags. The administrator can assign tags to hosts. These tags can
be used to specify which host a VM should use. The CloudStack
administrator decides whether to define host tags, then create a
service offering using those tags and offer it to the user.
--
-
- Affinity groups. By defining affinity groups and assigning VMs to
+- Affinity groups. By defining affinity groups and assigning VMs to
them, the user or administrator can influence (but not dictate) which
VMs should run on separate hosts. This feature is to let users
specify that certain VMs won't be on the same host.
--
-
- CloudStack also provides a pluggable interface for adding new
+- CloudStack also provides a pluggable interface for adding new
allocators. These custom allocators can provide any policy the
administrator desires.
+
Affinity Groups
~~~~~~~~~~~~~~~
@@ -369,77 +321,57 @@ running on another host.
The scope of an affinity group is per user account.
+
Creating a New Affinity Group
'''''''''''''''''''''''''''''
To add an affinity group:
-#.
-
- Log in to the CloudStack UI as an administrator or user.
-
-#.
+#. Log in to the CloudStack UI as an administrator or user.
- In the left navigation bar, click Affinity Groups.
+#. In the left navigation bar, click Affinity Groups.
-#.
-
- Click Add affinity group. In the dialog box, fill in the following
+#. Click Add affinity group. In the dialog box, fill in the following
fields:
- -
-
- Name. Give the group a name.
-
- -
+ - Name. Give the group a name.
- Description. Any desired text to tell more about the purpose of
+ - Description. Any desired text to tell more about the purpose of
the group.
- -
-
- Type. The only supported type shipped with CloudStack is Host
+ - Type. The only supported type shipped with CloudStack is Host
Anti-Affinity. This indicates that the VMs in this group should
avoid being placed on the same host with each other. If you see
other types in this list, it means that your installation of
CloudStack has been extended with customized affinity group
plugins.
+
Assign a New VM to an Affinity Group
''''''''''''''''''''''''''''''''''''
To assign a new VM to an affinity group:
--
+- Create the VM as usual, as described in `“Creating
+ VMs” <virtual_machines.html#creating-vms>`_. In the Add Instance
+ wizard, there is a new Affinity tab where you can select the
+ affinity group.
- Create the VM as usual, as described in `“Creating
- VMs” <virtual_machines.html#creating-vms>`_. In the Add Instance wizard, there is a new
- Affinity tab where you can select the affinity group.
Change Affinity Group for an Existing VM
''''''''''''''''''''''''''''''''''''''''
To assign an existing VM to an affinity group:
-#.
-
- Log in to the CloudStack UI as an administrator or user.
+#. Log in to the CloudStack UI as an administrator or user.
-#.
+#. In the left navigation bar, click Instances.
- In the left navigation bar, click Instances.
+#. Click the name of the VM you want to work with.
-#.
+#. Stop the VM by clicking the Stop button.
- Click the name of the VM you want to work with.
-
-#.
-
- Stop the VM by clicking the Stop button.
-
-#.
-
- Click the Change Affinity button. |change-affinity-button.png|
+#. Click the Change Affinity button. |change-affinity-button.png|
View Members of an Affinity Group
@@ -447,37 +379,26 @@ View Members of an Affinity Group
To see which VMs are currently assigned to a particular affinity group:
-#.
-
- In the left navigation bar, click Affinity Groups.
+#. In the left navigation bar, click Affinity Groups.
-#.
+#. Click the name of the group you are interested in.
- Click the name of the group you are interested in.
-
-#.
-
- Click View Instances. The members of the group are listed.
+#. Click View Instances. The members of the group are listed.
From here, you can click the name of any VM in the list to access all
its details and controls.
+
Delete an Affinity Group
''''''''''''''''''''''''
To delete an affinity group:
-#.
-
- In the left navigation bar, click Affinity Groups.
-
-#.
-
- Click the name of the group you are interested in.
+#. In the left navigation bar, click Affinity Groups.
-#.
+#. Click the name of the group you are interested in.
- Click Delete.
+#. Click Delete.
Any VM that is a member of the affinity group will be disassociated
from the group. The former group members will continue to run
@@ -485,6 +406,7 @@ To delete an affinity group:
longer follow the host allocation rules from its former affinity
group.
+
Virtual Machine Snapshots
-------------------------
@@ -515,37 +437,31 @@ original.
If you need more information about VM snapshots on VMware, check out the
VMware documentation and the VMware Knowledge Base, especially
-`Understanding virtual machine
-snapshots <http://kb.vmware.com/selfservice/microsites/search.do?cmd=displayKC&externalId=1015180>`_.
+`Understanding virtual machine snapshots
+<http://kb.vmware.com/selfservice/microsites/search.do?cmd=displayKC&externalId=1015180>`_.
+
Limitations on VM Snapshots
~~~~~~~~~~~~~~~~~~~~~~~~~~~
--
-
- If a VM has some stored snapshots, you can't attach new volume to the
+- If a VM has some stored snapshots, you can't attach new volume to the
VM or delete any existing volumes. If you change the volumes on the
VM, it would become impossible to restore the VM snapshot which was
created with the previous volume structure. If you want to attach a
volume to such a VM, first delete its snapshots.
--
-
- VM snapshots which include both data volumes and memory can't be kept
+- VM snapshots which include both data volumes and memory can't be kept
if you change the VM's service offering. Any existing VM snapshots of
this type will be discarded.
--
-
- You can't make a VM snapshot at the same time as you are taking a
+- You can't make a VM snapshot at the same time as you are taking a
volume snapshot.
--
-
- You should use only CloudStack to create VM snapshots on hosts
+- You should use only CloudStack to create VM snapshots on hosts
managed by CloudStack. Any snapshots that you make directly on the
hypervisor will not be tracked in CloudStack.
+
Configuring VM Snapshots
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -570,45 +486,34 @@ vmsnapshot.create.wait
Number of seconds to wait for a snapshot job to succeed before declaring
failure and issuing an error.
+
Using VM Snapshots
~~~~~~~~~~~~~~~~~~
To create a VM snapshot using the CloudStack UI:
-#.
-
- Log in to the CloudStack UI as a user or administrator.
-
-#.
-
- Click Instances.
+#. Log in to the CloudStack UI as a user or administrator.
-#.
+#. Click Instances.
- Click the name of the VM you want to snapshot.
+#. Click the name of the VM you want to snapshot.
-#.
+#. Click the Take VM Snapshot button. |VMSnapshotButton.png|
- Click the Take VM Snapshot button. |VMSnapshotButton.png|
-
- .. note:: If a snapshot is already in progress, then clicking this button will have no effect.
-
-#.
+ .. note::
+ If a snapshot is already in progress, then clicking this button
+ will have no effect.
- Provide a name and description. These will be displayed in the VM
+#. Provide a name and description. These will be displayed in the VM
Snapshots list.
-#.
-
- (For running VMs only) If you want to include the VM's memory in the
+#. (For running VMs only) If you want to include the VM's memory in the
snapshot, click the Memory checkbox. This saves the CPU and memory
state of the virtual machine. If you don't check this box, then only
the current state of the VM disk is saved. Checking this box makes
the snapshot take longer.
-#.
-
- Quiesce VM: check this box if you want to quiesce the file system on
+#. Quiesce VM: check this box if you want to quiesce the file system on
the VM before taking the snapshot. Not supported on XenServer when
used with CloudStack-provided primary storage.
@@ -618,35 +523,28 @@ To create a VM snapshot using the CloudStack UI:
vendor's plugin, the quiesce operation is provided according to the
vendor's implementation.
-#.
-
- Click OK.
+#. Click OK.
To delete a snapshot or restore a VM to the state saved in a particular
snapshot:
-#.
-
- Navigate to the VM as described in the earlier steps.
-
-#.
+#. Navigate to the VM as described in the earlier steps.
- Click View VM Snapshots.
+#. Click View VM Snapshots.
-#.
-
- In the list of snapshots, click the name of the snapshot you want to
+#. In the list of snapshots, click the name of the snapshot you want to
work with.
-#.
-
- Depending on what you want to do:
+#. Depending on what you want to do:
To delete the snapshot, click the Delete button. |delete-button.png|
To revert to the snapshot, click the Revert button. |revert-vm.png|
-.. note:: VM snapshots are deleted automatically when a VM is destroyed. You don't have to manually delete the snapshots in this case.
+.. note::
+ VM snapshots are deleted automatically when a VM is destroyed. You don't
+ have to manually delete the snapshots in this case.
+
Changing the VM Name, OS, or Group
----------------------------------
@@ -656,46 +554,27 @@ system, and the group it belongs to.
To access a VM through the CloudStack UI:
-#.
-
- Log in to the CloudStack UI as a user or admin.
-
-#.
-
- In the left navigation, click Instances.
-
-#.
+#. Log in to the CloudStack UI as a user or admin.
- Select the VM that you want to modify.
+#. In the left navigation, click Instances.
-#.
+#. Select the VM that you want to modify.
- Click the Stop button to stop the VM. |StopButton.png|
-
-#.
-
- Click Edit. |EditButton.png|
+#. Click the Stop button to stop the VM. |StopButton.png|
-#.
+#. Click Edit. |EditButton.png|
- Make the desired changes to the following:
+#. Make the desired changes to the following:
-#.
-
- **Display name**: Enter a new display name if you want to change the
+#. **Display name**: Enter a new display name if you want to change the
name of the VM.
-#.
-
- **OS Type**: Select the desired operating system.
-
-#.
+#. **OS Type**: Select the desired operating system.
- **Group**: Enter the group name for the VM.
+#. **Group**: Enter the group name for the VM.
-#.
+#. Click Apply.
- Click Apply.
Appending a Display Name to the Guest VM’s Internal Name
--------------------------------------------------------
@@ -736,38 +615,25 @@ Changing the Service Offering for a VM
To upgrade or downgrade the level of compute resources available to a
virtual machine, you can change the VM's compute offering.
-#.
+#. Log in to the CloudStack UI as a user or admin.
- Log in to the CloudStack UI as a user or admin.
+#. In the left navigation, click Instances.
-#.
+#. Choose the VM that you want to work with.
- In the left navigation, click Instances.
-
-#.
-
- Choose the VM that you want to work with.
-
-#.
-
- (Skip this step if you have enabled dynamic VM scaling; see
+#. (Skip this step if you have enabled dynamic VM scaling; see
:ref:`cpu-and-memory-scaling`.)
Click the Stop button to stop the VM. |StopButton.png|
-#.
-
- Click the Change Service button. |ChangeServiceButton.png|
+#. Click the Change Service button. |ChangeServiceButton.png|
The Change service dialog box is displayed.
-#.
+#. Select the offering you want to apply to the selected VM.
- Select the offering you want to apply to the selected VM.
+#. Click OK.
-#.
-
- Click OK.
.. _cpu-and-memory-scaling:
@@ -784,32 +650,23 @@ without incurring any downtime.
Dynamic CPU and RAM scaling can be used in the following cases:
--
-
- User VMs on hosts running VMware and XenServer.
-
--
+- User VMs on hosts running VMware and XenServer.
- System VMs on VMware.
+- System VMs on VMware.
--
-
- VMware Tools or XenServer Tools must be installed on the virtual
+- VMware Tools or XenServer Tools must be installed on the virtual
machine.
--
-
- The new requested CPU and RAM values must be within the constraints
+- The new requested CPU and RAM values must be within the constraints
allowed by the hypervisor and the VM operating system.
--
-
- New VMs that are created after the installation of CloudStack 4.2 can
+- New VMs that are created after the installation of CloudStack 4.2 can
use the dynamic scaling feature. If you are upgrading from a previous
version of CloudStack, your existing VMs created with previous
versions will not have the dynamic scaling capability unless you
update them using the following procedure.
+
Updating Existing VMs
~~~~~~~~~~~~~~~~~~~~~
@@ -817,37 +674,24 @@ If you are upgrading from a previous version of CloudStack, and you want
your existing VMs created with previous versions to have the dynamic
scaling capability, update the VMs using the following steps:
-#.
-
- Make sure the zone-level setting enable.dynamic.scale.vm is set to
+#. Make sure the zone-level setting enable.dynamic.scale.vm is set to
true. In the left navigation bar of the CloudStack UI, click
Infrastructure, then click Zones, click the zone you want, and click
the Settings tab.
-#.
-
- Install Xen tools (for XenServer hosts) or VMware Tools (for VMware
+#. Install Xen tools (for XenServer hosts) or VMware Tools (for VMware
hosts) on each VM if they are not already installed.
-#.
-
- Stop the VM.
-
-#.
+#. Stop the VM.
- Click the Edit button.
+#. Click the Edit button.
-#.
+#. Click the Dynamically Scalable checkbox.
- Click the Dynamically Scalable checkbox.
+#. Click Apply.
-#.
+#. Restart the VM.
- Click Apply.
-
-#.
-
- Restart the VM.
Configuring Dynamic CPU and RAM Scaling
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -855,16 +699,13 @@ Configuring Dynamic CPU and RAM Scaling
To configure this feature, use the following new global configuration
variables:
--
-
- enable.dynamic.scale.vm: Set to True to enable the feature. By
+- enable.dynamic.scale.vm: Set to True to enable the feature. By
default, the feature is turned off.
--
-
- scale.retry: How many times to attempt the scaling operation. Default
+- scale.retry: How many times to attempt the scaling operation. Default
= 2.
+
How to Dynamically Scale CPU and RAM
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -883,42 +724,34 @@ cluster. If there is no host in the cluster that can fulfill the
requested level of CPU and RAM, the scaling operation will fail. The VM
will continue to run as it was before.
+
Limitations
~~~~~~~~~~~
--
+- You can not do dynamic scaling for system VMs on XenServer.
- You can not do dynamic scaling for system VMs on XenServer.
-
--
-
- CloudStack will not check to be sure that the new CPU and RAM levels
+- CloudStack will not check to be sure that the new CPU and RAM levels
are compatible with the OS running on the VM.
--
-
- When scaling memory or CPU for a Linux VM on VMware, you might need
+- When scaling memory or CPU for a Linux VM on VMware, you might need
to run scripts in addition to the other steps mentioned above. For
more information, see `Hot adding memory in Linux
(1012764) <http://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=1012764>`_
in the VMware Knowledge Base.
--
-
- (VMware) If resources are not available on the current host, scaling
+- (VMware) If resources are not available on the current host, scaling
up will fail on VMware because of a known issue where CloudStack and
vCenter calculate the available capacity differently. For more
information, see
`https://issues.apache.org/jira/browse/CLOUDSTACK-1809 <https://issues.apache.org/jira/browse/CLOUDSTACK-1809>`_.
--
-
- On VMs running Linux 64-bit and Windows 7 32-bit operating systems,
+- On VMs running Linux 64-bit and Windows 7 32-bit operating systems,
if the VM is initially assigned a RAM of less than 3 GB, it can be
dynamically scaled up to 3 GB, but not more. This is due to a known
issue with these operating systems, which will freeze if an attempt
is made to dynamically scale from less than 3 GB to more than 3 GB.
+
Resetting the Virtual Machine Root Volume on Reboot
---------------------------------------------------
@@ -927,6 +760,7 @@ across reboots, you can reset the root disk. For more information, see
`“Reset VM to New Root Disk on
Reboot” <storage.html#reset-vm-to-new-root-disk-on-reboot>`_.
+
Moving VMs Between Hosts (Manual Live Migration)
------------------------------------------------
@@ -935,63 +769,44 @@ another without interrupting service to users or going into maintenance
mode. This is called manual live migration, and can be done under the
following conditions:
--
-
- The root administrator is logged in. Domain admins and users can not
+- The root administrator is logged in. Domain admins and users can not
perform manual live migration of VMs.
--
+- The VM is running. Stopped VMs can not be live migrated.
- The VM is running. Stopped VMs can not be live migrated.
-
--
-
- The destination host must have enough available capacity. If not, the
+- The destination host must have enough available capacity. If not, the
VM will remain in the "migrating" state until memory becomes
available.
--
-
- (KVM) The VM must not be using local disk storage. (On XenServer and
+- (KVM) The VM must not be using local disk storage. (On XenServer and
VMware, VM live migration with local disk is enabled by CloudStack
support for XenMotion and vMotion.)
--
-
- (KVM) The destination host must be in the same cluster as the
+- (KVM) The destination host must be in the same cluster as the
original host. (On XenServer and VMware, VM live migration from one
cluster to another is enabled by CloudStack support for XenMotion and
vMotion.)
To manually live migrate a virtual machine
-#.
-
- Log in to the CloudStack UI as a user or admin.
-
-#.
-
- In the left navigation, click Instances.
-
-#.
+#. Log in to the CloudStack UI as a user or admin.
- Choose the VM that you want to migrate.
+#. In the left navigation, click Instances.
-#.
+#. Choose the VM that you want to migrate.
- Click the Migrate Instance button. |Migrateinstance.png|
+#. Click the Migrate Instance button. |Migrateinstance.png|
-#.
-
- From the list of suitable hosts, choose the one to which you want to
+#. From the list of suitable hosts, choose the one to which you want to
move the VM.
.. note::
- If the VM's storage has to be migrated along with the VM, this will be noted in the host list. CloudStack will take care of the storage migration for you.
+ If the VM's storage has to be migrated along with the VM, this will
+ be noted in the host list. CloudStack will take care of the storage
+ migration for you.
-#.
+#. Click OK.
- Click OK.
Deleting VMs
------------
@@ -1002,21 +817,14 @@ any virtual machines.
To delete a virtual machine:
-#.
-
- Log in to the CloudStack UI as a user or admin.
-
-#.
+#. Log in to the CloudStack UI as a user or admin.
- In the left navigation, click Instances.
+#. In the left navigation, click Instances.
-#.
+#. Choose the VM that you want to delete.
- Choose the VM that you want to delete.
+#. Click the Destroy Instance button. |Destroyinstance.png|
-#.
-
- Click the Destroy Instance button. |Destroyinstance.png|
Working with ISOs
-----------------
@@ -1041,6 +849,7 @@ can also attach ISO images to guest VMs. For example, this enables
installing PV drivers into Windows. ISO images are not
hypervisor-specific.
+
Adding an ISO
~~~~~~~~~~~~~
@@ -1050,166 +859,121 @@ an operating system image, but you can also add ISOs for other types of
software, such as desktop applications that you want to be installed as
part of a template.
-#.
-
- Log in to the CloudStack UI as an administrator or end user.
-
-#.
-
- In the left navigation bar, click Templates.
-
-#.
-
- In Select View, choose ISOs.
-
-#.
+#. Log in to the CloudStack UI as an administrator or end user.
- Click Add ISO.
+#. In the left navigation bar, click Templates.
-#.
+#. In Select View, choose ISOs.
- In the Add ISO screen, provide the following:
+#. Click Add ISO.
- -
+#. In the Add ISO screen, provide the following:
- **Name**: Short name for the ISO image. For example, CentOS 6.2
+ - **Name**: Short name for the ISO image. For example, CentOS 6.2
64-bit.
- -
-
- **Description**: Display test for the ISO image. For example,
+ - **Description**: Display test for the ISO image. For example,
CentOS 6.2 64-bit.
- -
-
- **URL**: The URL that hosts the ISO image. The Management Server
+ - **URL**: The URL that hosts the ISO image. The Management Server
must be able to access this location via HTTP. If needed you can
place the ISO image directly on the Management Server
- -
-
- **Zone**: Choose the zone where you want the ISO to be available,
+ - **Zone**: Choose the zone where you want the ISO to be available,
or All Zones to make it available throughout CloudStack.
- -
-
- **Bootable**: Whether or not a guest could boot off this ISO
+ - **Bootable**: Whether or not a guest could boot off this ISO
image. For example, a CentOS ISO is bootable, a Microsoft Office
ISO is not bootable.
- -
-
- **OS Type**: This helps CloudStack and the hypervisor perform
+ - **OS Type**: This helps CloudStack and the hypervisor perform
certain operations and make assumptions that improve the
performance of the guest. Select one of the following.
- -
-
- If the operating system of your desired ISO image is listed,
+ - If the operating system of your desired ISO image is listed,
choose it.
- -
-
- If the OS Type of the ISO is not listed or if the ISO is not
+ - If the OS Type of the ISO is not listed or if the ISO is not
bootable, choose Other.
- -
-
- (XenServer only) If you want to boot from this ISO in PV mode,
+ - (XenServer only) If you want to boot from this ISO in PV mode,
choose Other PV (32-bit) or Other PV (64-bit)
- -
-
- (KVM only) If you choose an OS that is PV-enabled, the VMs
+ - (KVM only) If you choose an OS that is PV-enabled, the VMs
created from this ISO will have a SCSI (virtio) root disk. If
the OS is not PV-enabled, the VMs will have an IDE root disk.
The PV-enabled types are:
- Fedora 13
+ - Fedora 13
- Fedora 12
+ - Fedora 12
- Fedora 11
+ - Fedora 11
- Fedora 10
+ - Fedora 10
- Fedora 9
+ - Fedora 9
- Other PV
+ - Other PV
- Debian GNU/Linux
+ - Debian GNU/Linux
- CentOS 5.3
+ - CentOS 5.3
- CentOS 5.4
+ - CentOS 5.4
- CentOS 5.5
+ - CentOS 5.5
- Red Hat Enterprise Linux 5.3
+ - Red Hat Enterprise Linux 5.3
- Red Hat Enterprise Linux 5.4
+ - Red Hat Enterprise Linux 5.4
- Red Hat Enterprise Linux 5.5
+ - Red Hat Enterprise Linux 5.5
- Red Hat Enterprise Linux 6
+ - Red Hat Enterprise Linux 6
.. note::
- It is not recommended to choose an older version of the OS than the version in the image. For example, choosing CentOS 5.4 to support a CentOS 6.2 image will usually not work. In these cases, choose Other.
+ It is not recommended to choose an older version of the OS than
+ the version in the image. For example, choosing CentOS 5.4 to
+ support a CentOS 6.2 image will usually not work. In these
+ cases, choose Other.
- -
-
- **Extractable**: Choose Yes if the ISO should be available for
+ - **Extractable**: Choose Yes if the ISO should be available for
extraction.
- -
-
- **Public**: Choose Yes if this ISO should be available to other
+ - **Public**: Choose Yes if this ISO should be available to other
users.
- -
-
- **Featured**: Choose Yes if you would like this ISO to be more
+ - **Featured**: Choose Yes if you would like this ISO to be more
prominent for users to select. The ISO will appear in the Featured
ISOs list. Only an administrator can make an ISO Featured.
-#.
-
- Click OK.
+#. Click OK.
The Management Server will download the ISO. Depending on the size of
the ISO, this may take a long time. The ISO status column will
display Ready once it has been successfully downloaded into secondary
storage. Clicking Refresh updates the download percentage.
-#.
-
- **Important**: Wait for the ISO to finish downloading. If you move on
+#. **Important**: Wait for the ISO to finish downloading. If you move on
to the next task and try to use the ISO right away, it will appear to
fail. The entire ISO must be available before CloudStack can work
with it.
+
Attaching an ISO to a VM
~~~~~~~~~~~~~~~~~~~~~~~~~
-#.
-
- In the left navigation, click Instances.
-
-#.
+#. In the left navigation, click Instances.
- Choose the virtual machine you want to work with.
+#. Choose the virtual machine you want to work with.
-#.
+#. Click the Attach ISO button. |iso.png|
- Click the Attach ISO button. |iso.png|
+#. In the Attach ISO dialog box, select the desired ISO.
-#.
+#. Click OK.
- In the Attach ISO dialog box, select the desired ISO.
-
-#.
-
- Click OK.
Changing a VM's Base Image
~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1243,6 +1007,7 @@ restoreVirtualMachine call. In this case, the VM's root disk is
destroyed and recreated, but from the same template or ISO that was
already in use by the VM.
+
Using SSH Keys for Authentication
---------------------------------
@@ -1255,52 +1020,44 @@ Because each cloud user has their own SSH key, one cloud user cannot log
in to another cloud user's instances unless they share their SSH key
files. Using a single SSH key pair, you can manage multiple instances.
+
Creating an Instance Template that Supports SSH Keys
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Create an instance template that supports SSH Keys.
-#.
-
- Create a new instance by using the template provided by cloudstack.
+#. Create a new instance by using the template provided by cloudstack.
For more information on creating a new instance, see
-#.
-
- Download the cloudstack script from `The SSH Key Gen Script <http://sourceforge.net/projects/cloudstack/files/SSH%20Key%20Gen%20Script/>`_ to the instance you have created.
+#. Download the cloudstack script from `The SSH Key Gen Script
+ <http://sourceforge.net/projects/cloudstack/files/SSH%20Key%20Gen%20Script/>`_
+ to the instance you have created.
.. sourcecode:: bash
- wget http://downloads.sourceforge.net/project/cloudstack/SSH%20Key%20Gen%20Script/cloud-set-guest-sshkey.in?r=http%3A%2F%2Fsourceforge.net%2Fprojects%2Fcloudstack%2Ffiles%2FSSH%2520Key%2520Gen%2520Script%2F&ts=1331225219&use_mirror=iweb
-
-#.
+ wget http://downloads.sourceforge.net/project/cloudstack/SSH%20Key%20Gen%20Script/cloud-set-guest-sshkey.in?r=http%3A%2F%2Fsourceforge.net%2Fprojects%2Fcloudstack%2Ffiles%2FSSH%2520Key%2520Gen%2520Script%2F&ts=1331225219&use_mirror=iweb
- Copy the file to /etc/init.d.
+#. Copy the file to /etc/init.d.
.. sourcecode:: bash
- cp cloud-set-guest-sshkey.in /etc/init.d/
-
-#.
+ cp cloud-set-guest-sshkey.in /etc/init.d/
- Give the necessary permissions on the script:
+#. Give the necessary permissions on the script:
.. sourcecode:: bash
- chmod +x /etc/init.d/cloud-set-guest-sshkey.in
+ chmod +x /etc/init.d/cloud-set-guest-sshkey.in
-#.
-
- Run the script while starting up the operating system:
+#. Run the script while starting up the operating system:
.. sourcecode:: bash
- chkconfig --add cloud-set-guest-sshkey.in
+ chkconfig --add cloud-set-guest-sshkey.in
-#.
+#. Stop the instance.
- Stop the instance.
Creating the SSH Keypair
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1313,56 +1070,53 @@ For example, make a call from the cloudstack server to create a SSH
keypair called "keypair-doc" for the admin account in the root domain:
.. note::
- Ensure that you adjust these values to meet your needs. If you are making the API call from a different server, your URL/PORT will be different, and you will need to use the API keys.
-
-#.
+ Ensure that you adjust these values to meet your needs. If you are
+ making the API call from a different server, your URL/PORT will be
+ different, and you will need to use the API keys.
- Run the following curl command:
+#. Run the following curl command:
.. sourcecode:: bash
- curl --globoff "http://localhost:8096/?command=createSSHKeyPair&name=keypair-doc&account=admin&domainid=5163440e-c44b-42b5-9109-ad75cae8e8a2"
+ curl --globoff "http://localhost:8096/?command=createSSHKeyPair&name=keypair-doc&account=admin&domainid=5163440e-c44b-42b5-9109-ad75cae8e8a2"
The output is something similar to what is given below:
.. sourcecode:: bash
- <?xml version="1.0" encoding="ISO-8859-1"?><createsshkeypairresponse cloud-stack-version="3.0.0.20120228045507"><keypair><name>keypair-doc</name><fingerprint>f6:77:39:d5:5e:77:02:22:6a:d8:7f:ce:ab:cd:b3:56</fingerprint><privatekey>-----BEGIN RSA PRIVATE KEY-----
- MIICXQIBAAKBgQCSydmnQ67jP6lNoXdX3noZjQdrMAWNQZ7y5SrEu4wDxplvhYci
- dXYBeZVwakDVsU2MLGl/K+wefwefwefwefwefJyKJaogMKn7BperPD6n1wIDAQAB
- AoGAdXaJ7uyZKeRDoy6wA0UmF0kSPbMZCR+UTIHNkS/E0/4U+6lhMokmFSHtu
- mfDZ1kGGDYhMsdytjDBztljawfawfeawefawfawfawQQDCjEsoRdgkduTy
- QpbSGDIa11Jsc+XNDx2fgRinDsxXI/zJYXTKRhSl/LIPHBw/brW8vzxhOlSOrwm7
- VvemkkgpAkEAwSeEw394LYZiEVv395ar9MLRVTVLwpo54jC4tsOxQCBlloocK
- lYaocpk0yBqqOUSBawfIiDCuLXSdvBo1Xz5ICTM19vgvEp/+kMuECQBzm
- nVo8b2Gvyagqt/KEQo8wzH2THghZ1qQ1QRhIeJG2aissEacF6bGB2oZ7Igim5L14
- 4KR7OeEToyCLC2k+02UCQQCrniSnWKtDVoVqeK/zbB32JhW3Wullv5p5zUEcd
- KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3
- -----END RSA PRIVATE KEY-----
- </privatekey></keypair></createsshkeypairresponse>
-
-#.
-
- Copy the key data into a file. The file looks like this:
+ <?xml version="1.0" encoding="ISO-8859-1"?><createsshkeypairresponse cloud-stack-version="3.0.0.20120228045507"><keypair><name>keypair-doc</name><fingerprint>f6:77:39:d5:5e:77:02:22:6a:d8:7f:ce:ab:cd:b3:56</fingerprint><privatekey>-----BEGIN RSA PRIVATE KEY-----
+ MIICXQIBAAKBgQCSydmnQ67jP6lNoXdX3noZjQdrMAWNQZ7y5SrEu4wDxplvhYci
+ dXYBeZVwakDVsU2MLGl/K+wefwefwefwefwefJyKJaogMKn7BperPD6n1wIDAQAB
+ AoGAdXaJ7uyZKeRDoy6wA0UmF0kSPbMZCR+UTIHNkS/E0/4U+6lhMokmFSHtu
+ mfDZ1kGGDYhMsdytjDBztljawfawfeawefawfawfawQQDCjEsoRdgkduTy
+ QpbSGDIa11Jsc+XNDx2fgRinDsxXI/zJYXTKRhSl/LIPHBw/brW8vzxhOlSOrwm7
+ VvemkkgpAkEAwSeEw394LYZiEVv395ar9MLRVTVLwpo54jC4tsOxQCBlloocK
+ lYaocpk0yBqqOUSBawfIiDCuLXSdvBo1Xz5ICTM19vgvEp/+kMuECQBzm
+ nVo8b2Gvyagqt/KEQo8wzH2THghZ1qQ1QRhIeJG2aissEacF6bGB2oZ7Igim5L14
+ 4KR7OeEToyCLC2k+02UCQQCrniSnWKtDVoVqeK/zbB32JhW3Wullv5p5zUEcd
+ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3
+ -----END RSA PRIVATE KEY-----
+ </privatekey></keypair></createsshkeypairresponse>
+
+#. Copy the key data into a file. The file looks like this:
.. sourcecode:: bash
- -----BEGIN RSA PRIVATE KEY-----
- MIICXQIBAAKBgQCSydmnQ67jP6lNoXdX3noZjQdrMAWNQZ7y5SrEu4wDxplvhYci
- dXYBeZVwakDVsU2MLGl/K+wefwefwefwefwefJyKJaogMKn7BperPD6n1wIDAQAB
- AoGAdXaJ7uyZKeRDoy6wA0UmF0kSPbMZCR+UTIHNkS/E0/4U+6lhMokmFSHtu
- mfDZ1kGGDYhMsdytjDBztljawfawfeawefawfawfawQQDCjEsoRdgkduTy
- QpbSGDIa11Jsc+XNDx2fgRinDsxXI/zJYXTKRhSl/LIPHBw/brW8vzxhOlSOrwm7
- VvemkkgpAkEAwSeEw394LYZiEVv395ar9MLRVTVLwpo54jC4tsOxQCBlloocK
- lYaocpk0yBqqOUSBawfIiDCuLXSdvBo1Xz5ICTM19vgvEp/+kMuECQBzm
- nVo8b2Gvyagqt/KEQo8wzH2THghZ1qQ1QRhIeJG2aissEacF6bGB2oZ7Igim5L14
- 4KR7OeEToyCLC2k+02UCQQCrniSnWKtDVoVqeK/zbB32JhW3Wullv5p5zUEcd
- KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3
- -----END RSA PRIVATE KEY-----
+ -----BEGIN RSA PRIVATE KEY-----
+ MIICXQIBAAKBgQCSydmnQ67jP6lNoXdX3noZjQdrMAWNQZ7y5SrEu4wDxplvhYci
+ dXYBeZVwakDVsU2MLGl/K+wefwefwefwefwefJyKJaogMKn7BperPD6n1wIDAQAB
+ AoGAdXaJ7uyZKeRDoy6wA0UmF0kSPbMZCR+UTIHNkS/E0/4U+6lhMokmFSHtu
+ mfDZ1kGGDYhMsdytjDBztljawfawfeawefawfawfawQQDCjEsoRdgkduTy
+ QpbSGDIa11Jsc+XNDx2fgRinDsxXI/zJYXTKRhSl/LIPHBw/brW8vzxhOlSOrwm7
+ VvemkkgpAkEAwSeEw394LYZiEVv395ar9MLRVTVLwpo54jC4tsOxQCBlloocK
+ lYaocpk0yBqqOUSBawfIiDCuLXSdvBo1Xz5ICTM19vgvEp/+kMuECQBzm
+ nVo8b2Gvyagqt/KEQo8wzH2THghZ1qQ1QRhIeJG2aissEacF6bGB2oZ7Igim5L14
+ 4KR7OeEToyCLC2k+02UCQQCrniSnWKtDVoVqeK/zbB32JhW3Wullv5p5zUEcd
+ KfEEuzcCUIxtJYTahJ1pvlFkQ8anpuxjSEDp8x/18bq3
+ -----END RSA PRIVATE KEY-----
-#.
+#. Save the file.
- Save the file.
Creating an Instance
~~~~~~~~~~~~~~~~~~~~
@@ -1374,19 +1128,20 @@ Ensure that you use the same SSH key name that you created at
`Section 5.2.2, “Creating the SSH Keypair” <#create-ssh-keypair>`__.
.. note::
-
- You cannot create the instance by using the GUI at this time and associate the instance with the newly created SSH keypair.
+ You cannot create the instance by using the GUI at this time and
+ associate the instance with the newly created SSH keypair.
A sample curl command to create a new instance is:
.. sourcecode:: bash
- curl --globoff http://localhost:<port number>/?command=deployVirtualMachine\&zoneId=1\&serviceOfferingId=18727021-7556-4110-9322-d625b52e0813\&templateId=e899c18a-ce13-4bbf-98a9-625c5026e0b5\&securitygroupids=ff03f02f-9e3b-48f8-834d-91b822da40c5\&account=admin\&domainid=1\&keypair=keypair-doc
+ curl --globoff http://localhost:<port number>/?command=deployVirtualMachine\&zoneId=1\&serviceOfferingId=18727021-7556-4110-9322-d625b52e0813\&templateId=e899c18a-ce13-4bbf-98a9-625c5026e0b5\&securitygroupids=ff03f02f-9e3b-48f8-834d-91b822da40c5\&account=admin\&domainid=1\&keypair=keypair-doc
Substitute the template, service offering and security group IDs (if you
are using the security group feature) that are in your cloud
environment.
+
Logging In Using the SSH Keypair
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1397,11 +1152,12 @@ For example, from a Linux OS, run:
.. sourcecode:: bash
- ssh -i ~/.ssh/keypair-doc <ip address>
+ ssh -i ~/.ssh/keypair-doc <ip address>
The -i parameter tells the ssh client to use a ssh key found at
~/.ssh/keypair-doc.
+
Resetting SSH Keys
~~~~~~~~~~~~~~~~~~
@@ -1411,6 +1167,7 @@ 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.
+
.. |basic-deployment.png| image:: _static/images/basic-deployment.png
:alt: Basic two-machine CloudStack deployment
.. |VMSnapshotButton.png| image:: _static/images/VMSnapshotButton.png