Updated Branches: refs/heads/master 5a0f4b633 -> 2f67dae71
CLOUDSTACK-713 Project: http://git-wip-us.apache.org/repos/asf/cloudstack/repo Commit: http://git-wip-us.apache.org/repos/asf/cloudstack/commit/2f67dae7 Tree: http://git-wip-us.apache.org/repos/asf/cloudstack/tree/2f67dae7 Diff: http://git-wip-us.apache.org/repos/asf/cloudstack/diff/2f67dae7 Branch: refs/heads/master Commit: 2f67dae711ec2cd084229d8fd5366a72a832c060 Parents: 5a0f4b6 Author: Radhika PC <[email protected]> Authored: Mon Apr 22 13:36:51 2013 +0530 Committer: Radhika PC <[email protected]> Committed: Mon Apr 22 13:36:51 2013 +0530 ---------------------------------------------------------------------- docs/en-US/changed-API-commands-4.2 | 107 ++++++++ docs/en-US/limit-accounts-domains.xml | 387 ++++++++++++++++++++++++++++ docs/en-US/work-with-usage.xml | 24 +- 3 files changed, 507 insertions(+), 11 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cloudstack/blob/2f67dae7/docs/en-US/changed-API-commands-4.2 ---------------------------------------------------------------------- diff --git a/docs/en-US/changed-API-commands-4.2 b/docs/en-US/changed-API-commands-4.2 new file mode 100644 index 0000000..cbaa2e3 --- /dev/null +++ b/docs/en-US/changed-API-commands-4.2 @@ -0,0 +1,107 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent"> +%BOOK_ENTITIES; +]> +<!-- 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. +--> +<section id="changed-API-commands-4.2"> + <title>Changed API Commands in 4.2</title> + <informaltable> + <tgroup cols="2" align="left" colsep="1" rowsep="1"> + <thead> + <row> + <entry><para>Parameter Name</para></entry> + <entry><para>Description</para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para>updateResourceLimit</para></entry> + <entry> + <para>Added the following resource types to the <parameter>resourcetype</parameter> + request parameter to set the limits:</para> + <itemizedlist> + <listitem> + <para>CPU</para> + </listitem> + <listitem> + <para>RAM</para> + </listitem> + <listitem> + <para>primary storage</para> + </listitem> + <listitem> + <para>secondary storage</para> + </listitem> + <listitem> + <para>network rate</para> + </listitem> + </itemizedlist> + </entry> + </row> + <row> + <entry><para>updateResourceCount</para></entry> + <entry> + <para>Added the following resource types to the <parameter>resourcetype</parameter> + request parameter to set the limits:</para> + <itemizedlist> + <listitem> + <para>CPU</para> + </listitem> + <listitem> + <para>RAM</para> + </listitem> + <listitem> + <para>primary storage</para> + </listitem> + <listitem> + <para>secondary storage</para> + </listitem> + <listitem> + <para>network rate</para> + </listitem> + </itemizedlist> + </entry> + </row> + <row> + <entry><para>listResourceLimits </para></entry> + <entry> + <para>Added the following resource types to the <parameter>resourcetype</parameter> + request parameter:</para> + <itemizedlist> + <listitem> + <para>CPU</para> + </listitem> + <listitem> + <para>RAM</para> + </listitem> + <listitem> + <para>primary storage</para> + </listitem> + <listitem> + <para>secondary storage</para> + </listitem> + <listitem> + <para>network rate</para> + </listitem> + </itemizedlist> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> +</section> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/2f67dae7/docs/en-US/limit-accounts-domains.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/limit-accounts-domains.xml b/docs/en-US/limit-accounts-domains.xml new file mode 100644 index 0000000..64a886e --- /dev/null +++ b/docs/en-US/limit-accounts-domains.xml @@ -0,0 +1,387 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent"> +%BOOK_ENTITIES; +]> + +<!-- 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. +--> +<section id="limit-accounts-domains"> + <title>Limiting Resource Usage</title> + <para>In addition to VMs, volumes, and snapshots, &PRODUCT; allows you limit resource types, such + as CPU, RAM, Primary storage, Secondary storage, and Network Rate.</para> + <para>Previously in &PRODUCT;, resource usage limit was imposed based on the resource count, that + is, restrict a user or domain on the basis of the number of VMs, volumes, or snapshots used. A + new set of resource types has been added to the existing pool of resources (VMs, Volumes, and + Snapshots) to support the customization model—need-basis usage, such as large VM or small + VM. The new resource types are now broadly classified as CPU, RAM, Primary storage, Secondary + storage, and Network Rate. &PRODUCT; now allows the root administrator to impose resource usage + limit by the following resource types for Domain, Project and Accounts. </para> + <itemizedlist> + <listitem> + <para>CPUs</para> + </listitem> + <listitem> + <para>Memory (RAM)</para> + </listitem> + <listitem> + <para>Primary Storage (Volumes)</para> + </listitem> + <listitem> + <para>Secondary Storage (Snapshots, Templates, ISOs)</para> + </listitem> + <listitem> + <para>Network Rate (Mbps)</para> + </listitem> + </itemizedlist> + <para>To control the behaviour of this feature, the following configuration parameters have been + added:</para> + <informaltable> + <tgroup cols="2" align="left" colsep="1" rowsep="1"> + <thead> + <row> + <entry><para>Parameter Name</para></entry> + <entry><para>Description</para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para>max.account.cpus</para></entry> + <entry><para>Maximum number of CPU cores that can be used for an account. </para> + <para>Default is 40.</para></entry> + </row> + <row> + <entry><para>max.account.ram (MB)</para></entry> + <entry><para>Maximum RAM that can be used for an account. </para> + <para>Default is 40960.</para></entry> + </row> + <row> + <entry><para>max.account.primary.storage (GB)</para></entry> + <entry><para>Maximum primary storage space that can be used for an account. </para> + <para>Default is 20*10.</para> + </entry> + </row> + <row> + <entry><para>max.account.secondary.storage (GB)</para></entry> + <entry><para>Maximum secondary storage space that can be used for an account. </para> + <para>Default is 20*20.</para></entry> + </row> + <row> + <entry><para>max.account.network.rate (Mbps)</para></entry> + <entry><para>Maximum network rate that can be used for an account. </para> + <para>Default is 200.</para></entry> + </row> + <row> + <entry><para>max.project.cpus</para></entry> + <entry> + <para>Maximum number of CPU cores that can be used for an account. </para> + <para>Default is 40.</para> + </entry> + </row> + <row> + <entry><para>max.project.ram (MB)</para></entry> + <entry> + <para>Maximum RAM that can be used for an account. </para> + <para>Default is 40960.</para> + </entry> + </row> + <row> + <entry><para>max.project.primary.storage (GB)</para></entry> + <entry> + <para>Maximum primary storage space that can be used for an account. </para> + <para>Default is 20*10.</para> + </entry> + </row> + <row> + <entry><para>max.project.secondary.storage (GB)</para></entry> + <entry> + <para>Maximum secondary storage space that can be used for an account. </para> + <para>Default is 20*20.</para> + </entry> + </row> + <row> + <entry><para>max.project.network.rate (Mbps)</para></entry> + <entry> + <para>Maximum network rate that can be used for an account. </para> + <para>Default is 200.</para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <section id="user-permission-rn"> + <title>User Permission</title> + <para>The root administrator, domain administrators and users are able to list resources. Ensure + that proper logs are maintained in the <filename>vmops.log</filename> and + <filename>api.log</filename> files.</para> + <itemizedlist> + <listitem> + <para>The root admin will have the privilege to list and update resource limits.</para> + </listitem> + <listitem> + <para>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. </para> + </listitem> + <listitem> + <para>Normal users would have privilege to list resource limits. Use the listResourceLimits + API.</para> + </listitem> + </itemizedlist> + </section> + <section id="consideration-rn"> + <title>Use Cases and Considerations</title> + <itemizedlist> + <listitem> + <para>When you refer to Primary or Seconday storage space, it implies that the stated size + of the volume and not the physical size— the actual consumed size on disk in case of + thin provisioning.</para> + </listitem> + <listitem> + <para>If admin reduces the resource limit for an account and set it to less than the + resources currently consumed by that account, the existing VMs/templates/volumes are + destroyed. Using those resources, limits are imposed if the user under that account tries + to execute a new operation. For example, the existing behavior in the case of a VM are: </para> + <itemizedlist> + <listitem> + <para>migrateVirtualMachine: The users under that account will be able to migrate the + running VM into any other host without facing any limit issue.</para> + </listitem> + <listitem> + <para>recoverVirtualMachine: Destroyed VMs cannot be recovered.</para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para>For any resource type, if a domain has limit X, sub-domain or accounts under that + domain can have there own limits, but at any point of time the sum of resource allocated + to sub-domain or accounts under the domain should never exceed the value X.</para> + <para>For example, if a domain has the CPU limit of 40 and sub-domain D1 and account A1 can + have limits of 30 each, but at any point of time the resource allocated to D1 and A1 + should not exceed the limit 40.</para> + </listitem> + <listitem> + <para>If any operation needs to pass through two of more resource limit check, then the + lower of 2 limits will be enforced, For e.g. if an account has VM limit of 10 and CPU + limit of 20 and user under that account requests 5 VMs of 4 CPUs each, after this user can + deploy 5 more VMs(because VM limit is 10) but user has exausted his CPU limit and cannot + deploy any more instance.</para> + </listitem> + </itemizedlist> + </section> + <section id="per-domain-limits"> + <title>Per-Domain Limits</title> + <para>&PRODUCT; allows the configuration of limits on a domain basis. With a domain limit in + place, all users still have their account limits. They are additionally limited, as a group, + to not exceed the resource limits set on their domain. Domain limits aggregate the usage of + all accounts in the domain as well as all accounts in all sub-domains of that domain. Limits + set at the root domain level apply to the sum of resource usage by the accounts in all domains + and sub-domains below that root domain.</para> + <para>To set a domain limit:</para> + <orderedlist> + <listitem> + <para>Log in to the &PRODUCT; UI.</para> + </listitem> + <listitem> + <para>In the left navigation tree, click Domains.</para> + </listitem> + <listitem> + <para>Select the domain you want to modify. The current domain limits are displayed. </para> + <para>A value of -1 shows that there is no limit in place.</para> + </listitem> + <listitem> + <para>Click the Edit button<inlinemediaobject> + <imageobject> + <imagedata fileref="./images/edit-icon.png"/> + </imageobject> + <textobject> + <phrase>editbutton.png: edits the settings.</phrase> + </textobject> + </inlinemediaobject></para> + </listitem> + <listitem> + <para>Edit the following as per your requirement:</para> + <informaltable> + <tgroup cols="2" align="left" colsep="1" rowsep="1"> + <thead> + <row> + <entry><para>Parameter Name</para></entry> + <entry><para>Description</para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para>Instance Limits</para></entry> + <entry><para>The number of instances that can be used in a domain.</para></entry> + </row> + <row> + <entry><para>Public IP Limits</para></entry> + <entry> + <para>The number of public IP addresses that can be used in a + domain.</para></entry> + </row> + <row> + <entry><para>Volume Limits</para></entry> + <entry><para>The number of disk volumes that can be created in a domain. </para> + </entry> + </row> + <row> + <entry><para>Snapshot Limits</para></entry> + <entry>The number of snapshots that can be created in a domain.</entry> + </row> + <row> + <entry><para>Template Limits</para></entry> + <entry><para>The number of templates that can be registered in a + domain.</para></entry> + </row> + <row> + <entry><para>VPC limits</para></entry> + <entry><para>The number of VPCs that can be created in a domain.</para></entry> + </row> + <row> + <entry><para>CPU limits</para></entry> + <entry> + <para>The number of CPU cores that can be used for a domain.</para> + </entry> + </row> + <row> + <entry><para>Memory limits (MB)</para></entry> + <entry> + <para>The number of RAM that can be used for a domain.</para> + </entry> + </row> + <row> + <entry><para>Primary Storage limits (GB)</para></entry> + <entry> + <para>The primary storage space that can be used for a domain.</para> + </entry> + </row> + <row> + <entry><para>Secondary Storage limits (GB)</para></entry> + <entry> + <para>The secondary storage space that can be used for a domain.</para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </listitem> + <listitem><para>Click Apply.</para></listitem> + </orderedlist> + </section> + <section id="default-account-resource-limit"> + <title>Default Account Resource Limits</title> + <para>You can limit resource use by accounts. The default limits are set by using global + configuration parameters, and they affect all accounts within a cloud. The relevant parameters + are those beginning with max.account, for example: max.account.snapshots.</para> + <para>To override a default limit for a particular account, set a per-account resource + limit.</para> + <orderedlist> + <listitem> + <para>Log in to the &PRODUCT; UI.</para> + </listitem> + <listitem> + <para>In the left navigation tree, click Accounts.</para> + </listitem> + <listitem> + <para>Select the account you want to modify. The current limits are displayed. </para> + <para>A value of -1 shows that there is no limit in place.</para> + </listitem> + <listitem> + <para>Click the Edit button.<inlinemediaobject> + <imageobject> + <imagedata fileref="./images/edit-icon.png"/> + </imageobject> + <textobject> + <phrase>editbutton.png: edits the settings</phrase> + </textobject> + </inlinemediaobject></para> + </listitem> + <listitem> + <para>Edit the following as per your requirement:</para> + <informaltable> + <tgroup cols="2" align="left" colsep="1" rowsep="1"> + <thead> + <row> + <entry><para>Parameter Name</para></entry> + <entry><para>Description</para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para>Instance Limits</para></entry> + <entry><para>The number of instances that can be used in an account.</para> + <para>The default is 20.</para></entry> + </row> + <row> + <entry><para>Public IP Limits</para></entry> + <entry> + <para>The number of public IP addresses that can be used in an + account.</para> + <para>The default is 20.</para></entry> + </row> + <row> + <entry><para>Volume Limits</para></entry> + <entry><para>The number of disk volumes that can be created in an account.</para> + <para>The default is 20.</para></entry> + </row> + <row> + <entry><para>Snapshot Limits</para></entry> + <entry><para>The number of snapshots that can be created in an account.</para> + <para>The default is 20.</para></entry> + </row> + <row> + <entry><para>Template Limits</para></entry> + <entry><para>The number of templates that can be registered in an + account.</para> + <para>The default is 20.</para></entry> + </row> + <row> + <entry><para>VPC limits</para></entry> + <entry><para>The number of VPCs that can be created in an account.</para> + <para>The default is 20.</para></entry> + </row> + <row> + <entry><para>CPU limits</para></entry> + <entry> + <para>The number of CPU cores that can be used for an account.</para> + <para>The default is 40.</para></entry> + </row> + <row> + <entry><para>Memory limits (MB)</para></entry> + <entry> + <para>The number of RAM that can be used for an account.</para> + <para>The default is 40960.</para></entry> + </row> + <row> + <entry><para>Primary Storage limits (GB)</para></entry> + <entry> + <para>The primary storage space that can be used for an account.</para> + <para>The default is 200.</para></entry> + </row> + <row> + <entry><para>Secondary Storage limits (GB)</para></entry> + <entry> + <para>The secondary storage space that can be used for an account.</para> + <para>The default is 400.</para></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </listitem> + <listitem><para>Click Apply.</para></listitem> + </orderedlist> + </section> +</section> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/2f67dae7/docs/en-US/work-with-usage.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/work-with-usage.xml b/docs/en-US/work-with-usage.xml index 00a7fb5..c40b1e2 100644 --- a/docs/en-US/work-with-usage.xml +++ b/docs/en-US/work-with-usage.xml @@ -21,16 +21,18 @@ specific language governing permissions and limitations under the License. --> - <chapter id="work-with-usage"> - <title>Working with Usage</title> - <para>The Usage Server is an optional, separately-installed part of &PRODUCT; that provides aggregated usage records which you can use to create billing integration for &PRODUCT;. The Usage Server works by taking data from the events log and creating summary usage records that you can access using the listUsageRecords API call. </para> - <para>The usage records show the amount of resources, such as VM run time or template storage - space, consumed by guest instances.</para> - <para>The Usage Server runs at least once per day. It can be configured to run multiple times per day.</para> - <xi:include href="configure-usage-server.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> - <xi:include href="set-usage-limit.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> - <xi:include href="globally-configured-limits.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> - <xi:include href="default-account-resource-limit.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> - <xi:include href="per-domain-limits.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + <title>Working with Usage</title> + <para>The Usage Server is an optional, separately-installed part of &PRODUCT; that provides + aggregated usage records which you can use to create billing integration for &PRODUCT;. The + Usage Server works by taking data from the events log and creating summary usage records that + you can access using the listUsageRecords API call. </para> + <para>The usage records show the amount of resources, such as VM run time or template storage + space, consumed by guest instances.</para> + <para>The Usage Server runs at least once per day. It can be configured to run multiple times per + day.</para> + <xi:include href="configure-usage-server.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> + <xi:include href="set-usage-limit.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> + <xi:include href="globally-configured-limits.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> + <xi:include href="limit-accounts-domains.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> </chapter>
