Command Line Reference¶
allocation candidate list¶
List allocation candidates.
Returns a representation of a collection of allocation requests and
resource provider summaries. Each allocation request has information
to issue an openstack resource provider allocation set
request to claim
resources against a related set of resource providers.
As several allocation requests are available its necessary to select one. To make a decision, resource provider summaries are provided with the inventory/capacity information.
For example:
$ export OS_PLACEMENT_API_VERSION=1.10
$ openstack allocation candidate list --resource VCPU=1
+---+------------+-------------------------+-------------------------+
| # | allocation | resource provider | inventory used/capacity |
+---+------------+-------------------------+-------------------------+
| 1 | VCPU=1 | 66bcaca9-9263-45b1-a569 | VCPU=0/128 |
| | | -ea708ff7a968 | |
+---+------------+-------------------------+-------------------------+
In this case, the user is looking for resource providers that can have
capacity to allocate 1 VCPU
resource class. There is one resource
provider that can serve that allocation request and that resource providers
current VCPU
inventory used is 0 and available capacity is 128.
This command requires at least --os-placement-api-version 1.10
.
openstack allocation candidate list
[--sort-column SORT_COLUMN]
[--sort-ascending | --sort-descending]
[--resource <resource_class>=<value>]
[--limit <limit>]
[--required <required>]
[--forbidden <forbidden>]
[--member-of <member_of>]
[--group <group>]
[--group-policy <group_policy>]
- --sort-column SORT_COLUMN¶
specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated
- --sort-ascending¶
sort the column(s) in ascending order
- --sort-descending¶
sort the column(s) in descending order
- --resource <resource_class>=<value>¶
String indicating an amount of resource of a specified class that providers in each allocation request must collectively have the capacity and availability to serve. Can be specified multiple times per resource class. For example:
--resource VCPU=4 --resource DISK_GB=64 --resource MEMORY_MB=2048
- --limit <limit>¶
A positive integer to limit the maximum number of allocation candidates. This option requires at least
--os-placement-api-version 1.16
.
- --required <required>¶
A required trait. May be repeated. Allocation candidates must collectively contain all of the required traits. This option requires at least
--os-placement-api-version 1.17
.
- --forbidden <forbidden>¶
A forbidden trait. May be repeated. Returned allocation candidates must not contain any of the specified traits. This option requires at least
--os-placement-api-version 1.22
.
- --member-of <member_of>¶
A list of comma-separated UUIDs of the resource provider aggregates. The returned allocation candidates must be associated with at least one of the aggregates identified by uuid. This param requires at least
--os-placement-api-version 1.21
and can be repeated to add(restrict) the condition with--os-placement-api-version 1.24
or greater. For example, to get candidates in either of agg1 or agg2 and definitely in agg3, specify:--member_of <agg1>,<agg2> --member_of <agg3>
- --group <group>¶
An integer to group granular requests. If specified, following given options of resources, required/forbidden traits, and aggregate are associated to that group and will be satisfied by the same resource provider in the response. Can be repeated to get candidates from multiple resource providers in the same resource provider tree. For example,
--group 1 --resource VCPU=3 --required HW_CPU_X86_AVX --group 2 --resource VCPU=2 --required HW_CPU_X86_SSE
will provide candidates where three VCPUs comes from a provider withHW_CPU_X86_AVX
trait and two VCPUs from a provider withHW_CPU_X86_SSE
trait. This option requires at least--os-placement-api-version 1.25
or greater, but to have placement server be aware of resource provider tree, use--os-placement-api-version 1.29
or greater.
- --group-policy <group_policy>¶
This indicates how the groups should interact when multiple groups are supplied. With group_policy=none (default), separate groups may or may not be satisfied by the same provider. With group_policy=isolate, numbered groups are guaranteed to be satisfied by different providers.
This command is provided by the osc-placement plugin.
resource class create¶
Create a new resource class.
This command requires at least --os-placement-api-version 1.2
.
openstack resource class create <name>
- name¶
Name of the resource class
This command is provided by the osc-placement plugin.
resource class delete¶
Delete the resource class identified by <name>
.
Only custom resource classes can be deleted.
This command requires at least --os-placement-api-version 1.2
.
openstack resource class delete <name>
- name¶
Name of the resource class
This command is provided by the osc-placement plugin.
resource class list¶
Return a list of all resource classes.
This command requires at least --os-placement-api-version 1.2
.
openstack resource class list
[--sort-column SORT_COLUMN]
[--sort-ascending | --sort-descending]
- --sort-column SORT_COLUMN¶
specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated
- --sort-ascending¶
sort the column(s) in ascending order
- --sort-descending¶
sort the column(s) in descending order
This command is provided by the osc-placement plugin.
resource class set¶
Create or validate the existence of single resource class.
Unlike openstack resource class create
, this command also succeeds if
the resource class already exists, which makes this an idempotent check or
create command.
This command requires at least --os-placement-api-version 1.7
.
openstack resource class set <name>
- name¶
Name of the resource class
This command is provided by the osc-placement plugin.
resource class show¶
Return a representation of the resource class identified by <name>
.
This command requires at least --os-placement-api-version 1.2
.
openstack resource class show <name>
- name¶
Name of the resource class
This command is provided by the osc-placement plugin.
resource provider aggregate list¶
List resource provider aggregates.
This command requires at least --os-placement-api-version 1.1
.
openstack resource provider aggregate list
[--sort-column SORT_COLUMN]
[--sort-ascending | --sort-descending]
<uuid>
- --sort-column SORT_COLUMN¶
specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated
- --sort-ascending¶
sort the column(s) in ascending order
- --sort-descending¶
sort the column(s) in descending order
- uuid¶
UUID of the resource provider
This command is provided by the osc-placement plugin.
resource provider aggregate set¶
Associate a list of aggregates with the resource provider.
Each request cleans up previously associated resource provider aggregates entirely and sets the new ones. Passing empty aggregate UUID list will remove all associations with aggregates for the particular resource provider.
This command requires at least --os-placement-api-version 1.1
.
openstack resource provider aggregate set
[--sort-column SORT_COLUMN]
[--sort-ascending | --sort-descending]
[--aggregate <aggregate_uuid>]
[--generation <resource_provider_generation>]
<uuid>
- --sort-column SORT_COLUMN¶
specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated
- --sort-ascending¶
sort the column(s) in ascending order
- --sort-descending¶
sort the column(s) in descending order
- --aggregate <aggregate_uuid>¶
UUID of the aggregate. Specify multiple times to associate a resource provider with multiple aggregates.
- --generation <resource_provider_generation>¶
The generation of resource provider. Must match the server-side generation of the resource provider or the operation will fail.
This param requires at least
--os-placement-api-version 1.19
.
- uuid¶
UUID of the resource provider
This command is provided by the osc-placement plugin.
resource provider allocation delete¶
Delete all resource allocations for a given consumer.
openstack resource provider allocation delete <uuid>
- uuid¶
UUID of the consumer
This command is provided by the osc-placement plugin.
resource provider allocation set¶
Replaces the set of resource allocation(s) for a given consumer.
Note that this is a full replacement of the existing allocations. If you want to retain the existing allocations and add a new resource class allocation, you must specify all resource class allocations, old and new.
From --os-placement-api-version 1.8
it is required to specify
--project-id
and --user-id
to set allocations. It is highly
recommended to provide a --project-id
and --user-id
when setting
allocations for accounting and data consistency reasons.
Starting with --os-placement-api-version 1.12
the API response
contains the project_id
and user_id
of allocations which also
appears in the CLI output.
Starting with --os-placement-api-version 1.28
a consumer generation is
used which facilitates safe concurrent modification of an allocation.
Starting with --os-placement-api-version 1.38
it is required to specify
--consumer-type
to set allocations. It is helpful to provide a
--consumer-type
when setting allocations so that resource usages can be
filtered on consumer types.
openstack resource provider allocation set
[--sort-column SORT_COLUMN]
[--sort-ascending | --sort-descending]
[--allocation <rp=resource-provider-id,resource-class-name=amount-of-resource-used>]
[--project-id project_id]
[--user-id user_id]
[--consumer-type consumer_type]
<uuid>
- --sort-column SORT_COLUMN¶
specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated
- --sort-ascending¶
sort the column(s) in ascending order
- --sort-descending¶
sort the column(s) in descending order
- --allocation <rp=resource-provider-id,resource-class-name=amount-of-resource-used>¶
Create (or update) an allocation of a resource class. Specify option multiple times to set multiple allocations.
- --project-id project_id¶
ID of the consuming project. This option is required starting from
--os-placement-api-version 1.8
.
- --user-id user_id¶
ID of the consuming user. This option is required starting from
--os-placement-api-version 1.8
.
- --consumer-type consumer_type¶
The type of the consumer. This option is required starting from
--os-placement-api-version 1.38
.
- uuid¶
UUID of the consumer
This command is provided by the osc-placement plugin.
resource provider allocation show¶
Show resource allocations for a given consumer.
Starting with --os-placement-api-version 1.12
the API response contains
the project_id
and user_id
of allocations which also appears in the
CLI output.
Starting with --os-placement-api-version 1.38
the API response contains
the consumer_type
of consumer which also appears in the CLI output.
openstack resource provider allocation show
[--sort-column SORT_COLUMN]
[--sort-ascending | --sort-descending]
<uuid>
- --sort-column SORT_COLUMN¶
specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated
- --sort-ascending¶
sort the column(s) in ascending order
- --sort-descending¶
sort the column(s) in descending order
- uuid¶
UUID of the consumer
This command is provided by the osc-placement plugin.
resource provider allocation unset¶
Removes one or more sets of provider allocations for a consumer.
Note that omitting both the --provider
and the --resource-class
option is equivalent to removing all allocations for the given consumer.
This command requires --os-placement-api-version 1.12
or greater. Use
openstack resource provider allocation set
for older versions.
openstack resource provider allocation unset
[--sort-column SORT_COLUMN]
[--sort-ascending | --sort-descending]
[--provider provider_uuid]
[--resource-class resource_class]
<consumer_uuid>
- --sort-column SORT_COLUMN¶
specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated
- --sort-ascending¶
sort the column(s) in ascending order
- --sort-descending¶
sort the column(s) in descending order
- --provider provider_uuid¶
UUID of a specific resource provider from which to remove allocations for the given consumer. This is useful when the consumer has allocations on more than one provider, for example after evacuating a server to another compute node and you want to cleanup allocations on the source compute node resource provider in order to delete it. Specify multiple times to remove allocations against multiple resource providers. Omit this option to remove all allocations for the consumer, or to remove all allocationsof a specific resource class from all the resource provider with the
--resource_class
option.
- --resource-class resource_class¶
Name of a resource class from which to remove allocations for the given consumer. This is useful when the consumer has allocations on more than one resource class. By default, this will remove allocations for the given resource class from all the providers. If
--provider
option is also specified, allocations to remove will be limited to that resource class of the given resource provider.
- consumer_uuid¶
UUID of the consumer. It is strongly recommended to use
--os-placement-api-version 1.28
or greater when using this option to ensure the other allocation information is retained.
This command is provided by the osc-placement plugin.
resource provider create¶
Create a new resource provider
openstack resource provider create
[--parent-provider <parent_provider>]
[--uuid <uuid>]
<name>
- --parent-provider <parent_provider>¶
UUID of the parent provider. Omit for no parent. This option requires at least
--os-placement-api-version 1.14
.
- --uuid <uuid>¶
UUID of the resource provider
- name¶
Name of the resource provider
This command is provided by the osc-placement plugin.
resource provider delete¶
Delete a resource provider
openstack resource provider delete <uuid>
- uuid¶
UUID of the resource provider
This command is provided by the osc-placement plugin.
resource provider inventory class set¶
Replace the inventory record of the class for the resource provider.
Example:
openstack resource provider inventory class set <uuid> VCPU --total 16 --max_unit 4 --reserved 1
openstack resource provider inventory class set
[--allocation_ratio <allocation_ratio>]
[--min_unit <min_unit>]
[--max_unit <max_unit>]
[--reserved <reserved>]
[--step_size <step_size>]
--total <total>
<uuid>
<class>
- --allocation_ratio <allocation_ratio>¶
It is used in determining whether consumption of the resource of the provider can exceed physical constraints. For example, for a vCPU resource with: allocation_ratio = 16.0, total = 8. Overall capacity is equal to 128 vCPUs.
- --min_unit <min_unit>¶
A minimum amount any single allocation against an inventory can have.
- --max_unit <max_unit>¶
A maximum amount any single allocation against an inventory can have.
- --reserved <reserved>¶
The amount of the resource a provider has reserved for its own use.
- --step_size <step_size>¶
A representation of the divisible amount of the resource that may be requested. For example, step_size = 5 means that only values divisible by 5 (5, 10, 15, etc.) can be requested.
- --total <total>¶
The actual amount of the resource that the provider can accommodate.
- uuid¶
UUID of the resource provider
- class¶
<resource_class> is an entity that indicates standard or deployer-specific resources that can be provided by a resource provider. For example, VCPU, MEMORY_MB, DISK_GB.
This command is provided by the osc-placement plugin.
resource provider inventory delete¶
Delete the inventory.
Depending on the resource class argument presence, delete all inventory for a given resource provider or for a resource provider/class pair.
Delete all inventories for given resource provider requires at least
--os-placement-api-version 1.5
.
openstack resource provider inventory delete
--resource-class <resource_class>
<uuid>
- --resource-class <resource_class>¶
<resource_class> is an entity that indicates standard or deployer-specific resources that can be provided by a resource provider. For example, VCPU, MEMORY_MB, DISK_GB. This argument can be omitted starting with
--os-placement-api-version 1.5
. If it is omitted all inventories of the specified resource provider will be deleted.
- uuid¶
UUID of the resource provider
This command is provided by the osc-placement plugin.
resource provider inventory list¶
List inventories for a given resource provider.
openstack resource provider inventory list
[--sort-column SORT_COLUMN]
[--sort-ascending | --sort-descending]
<uuid>
- --sort-column SORT_COLUMN¶
specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated
- --sort-ascending¶
sort the column(s) in ascending order
- --sort-descending¶
sort the column(s) in descending order
- uuid¶
UUID of the resource provider
This command is provided by the osc-placement plugin.
resource provider inventory set¶
Replaces the set of inventory records for the resource provider.
Note that by default this is a full replacement of the existing inventory.
If you want to retain the existing inventory and add a new resource class
inventory, you must specify all resource class inventory, old and new, or
specify the --amend
option.
If a specific inventory field is not specified for a given resource class,
it is assumed to be the total, i.e. --resource VCPU=16
is equivalent to
--resource VCPU:total=16
.
Example:
openstack resource provider inventory set <uuid> --resource VCPU=16 --resource MEMORY_MB=2048 --resource MEMORY_MB:step_size=128
openstack resource provider inventory set
[--sort-column SORT_COLUMN]
[--sort-ascending | --sort-descending]
[--resource <resource_class>:<inventory_field>=<value>]
[--aggregate]
[--amend]
[--dry-run]
<uuid>
- --sort-column SORT_COLUMN¶
specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated
- --sort-ascending¶
sort the column(s) in ascending order
- --sort-descending¶
sort the column(s) in descending order
- --resource <resource_class>:<inventory_field>=<value>¶
String describing resource. <resource_class> is an entity that indicates standard or deployer-specific resources that can be provided by a resource provider. For example, VCPU, MEMORY_MB, DISK_GB. <inventory_field> (optional) can be: allocation_ratio - it is used in determining whether consumption of the resource of the provider can exceed physical constraints. for example, for a vcpu resource with: allocation_ratio = 16.0, total = 8. overall capacity is equal to 128 vcpus. min_unit - a minimum amount any single allocation against an inventory can have. max_unit - a maximum amount any single allocation against an inventory can have. reserved - the amount of the resource a provider has reserved for its own use. step_size - a representation of the divisible amount of the resource that may be requested. for example, step_size = 5 means that only values divisible by 5 (5, 10, 15, etc.) can be requested. total - the actual amount of the resource that the provider can accommodate.
- --aggregate¶
If this option is specified, the inventories for all resource providers that are members of the aggregate will be set. This option requires at least
--os-placement-api-version 1.3
- --amend¶
If this option is specified, the inventories will be amended instead of being fully replaced
- --dry-run¶
If this option is specified, the inventories that would be set will be returned without actually setting any inventories
- uuid¶
UUID of the resource provider or UUID of the aggregate, if –aggregate is specified
This command is provided by the osc-placement plugin.
resource provider inventory show¶
Show the inventory for a given resource provider/class pair.
openstack resource provider inventory show <uuid> <resource_class>
- uuid¶
UUID of the resource provider
- resource_class¶
<resource_class> is an entity that indicates standard or deployer-specific resources that can be provided by a resource provider. For example, VCPU, MEMORY_MB, DISK_GB.
This command is provided by the osc-placement plugin.
resource provider list¶
List resource providers
openstack resource provider list
[--sort-column SORT_COLUMN]
[--sort-ascending | --sort-descending]
[--uuid <uuid>]
[--name <name>]
[--resource <resource_class>=<value>]
[--in-tree <in_tree>]
[--required <required>]
[--forbidden <forbidden>]
[--member-of <member_of>]
- --sort-column SORT_COLUMN¶
specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated
- --sort-ascending¶
sort the column(s) in ascending order
- --sort-descending¶
sort the column(s) in descending order
- --uuid <uuid>¶
UUID of the resource provider
- --name <name>¶
Name of the resource provider
- --resource <resource_class>=<value>¶
A resource class value pair indicating an amount of resource of a specified class that a provider must have the capacity to serve. May be repeated.
This param requires at least
--os-placement-api-version 1.4
.
- --in-tree <in_tree>¶
Restrict listing to the same “provider tree” as the specified provider UUID. This option requires at least
--os-placement-api-version 1.14
.
- --required <required>¶
A required trait. May be repeated. Resource providers must collectively contain all of the required traits. This option requires at least
--os-placement-api-version 1.18
.
- --forbidden <forbidden>¶
A forbidden trait. May be repeated. Returned resource providers must not contain any of the specified traits. This option requires at least
--os-placement-api-version 1.22
.
- --member-of <member_of>¶
A list of comma-separated UUIDs of the resource provider aggregates. The returned resource providers must be associated with at least one of the aggregates identified by uuid. This param requires at least
--os-placement-api-version 1.3
and can be repeated to add(restrict) the condition with--os-placement-api-version 1.24
or greater. For example, to get candidates either in agg1 or in agg2 and definitely in agg3, specify:--member_of <agg1>,<agg2> --member_of <agg3>
This command is provided by the osc-placement plugin.
resource provider set¶
Update an existing resource provider
openstack resource provider set
--name <name>
[--parent-provider <parent_provider>]
<uuid>
- --name <name>¶
A new name of the resource provider
- --parent-provider <parent_provider>¶
UUID of the parent provider. Can only be set if the resource provider has no parent yet. This option requires at least
--os-placement-api-version 1.14
.
- uuid¶
UUID of the resource provider
This command is provided by the osc-placement plugin.
resource provider show¶
Show resource provider details
openstack resource provider show [--allocations] <uuid>
- --allocations¶
include the info on allocations of the provider resources
- uuid¶
UUID of the resource provider
This command is provided by the osc-placement plugin.
resource provider trait delete¶
Dissociate all the traits from the resource provider.
Note that this command is not atomic if multiple processes are managing traits for the same provider.
This command requires at least --os-placement-api-version 1.6
.
openstack resource provider trait delete <uuid>
- uuid¶
UUID of the resource provider.
This command is provided by the osc-placement plugin.
resource provider trait list¶
List traits associated with the resource provider identified by {uuid}.
This command requires at least --os-placement-api-version 1.6
.
openstack resource provider trait list
[--sort-column SORT_COLUMN]
[--sort-ascending | --sort-descending]
<uuid>
- --sort-column SORT_COLUMN¶
specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated
- --sort-ascending¶
sort the column(s) in ascending order
- --sort-descending¶
sort the column(s) in descending order
- uuid¶
UUID of the resource provider.
This command is provided by the osc-placement plugin.
resource provider trait set¶
Associate traits with the resource provider identified by {uuid}.
All the associated traits will be replaced by the traits specified.
This command requires at least --os-placement-api-version 1.6
.
openstack resource provider trait set
[--sort-column SORT_COLUMN]
[--sort-ascending | --sort-descending]
[--trait <trait>]
<uuid>
- --sort-column SORT_COLUMN¶
specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated
- --sort-ascending¶
sort the column(s) in ascending order
- --sort-descending¶
sort the column(s) in descending order
- --trait <trait>¶
Name of the trait. May be repeated.
- uuid¶
UUID of the resource provider.
This command is provided by the osc-placement plugin.
resource provider usage show¶
Show resource usages per class for a given resource provider.
openstack resource provider usage show
[--sort-column SORT_COLUMN]
[--sort-ascending | --sort-descending]
<uuid>
- --sort-column SORT_COLUMN¶
specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated
- --sort-ascending¶
sort the column(s) in ascending order
- --sort-descending¶
sort the column(s) in descending order
- uuid¶
UUID of the resource provider
This command is provided by the osc-placement plugin.
resource usage show¶
Show resource usages for a project (and optionally user) per class.
Gives a report of usage information for resources associated with the
project identified by the project_id
argument and user identified by
the --user-id
option.
This command requires at least --os-placement-api-version 1.9
.
openstack resource usage show
[--sort-column SORT_COLUMN]
[--sort-ascending | --sort-descending]
[--user-id <user-uuid>]
<project-uuid>
- --sort-column SORT_COLUMN¶
specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated
- --sort-ascending¶
sort the column(s) in ascending order
- --sort-descending¶
sort the column(s) in descending order
- --user-id <user-uuid>¶
ID of the user.
- project-uuid¶
ID of the project.
This command is provided by the osc-placement plugin.
trait create¶
Create a new custom trait.
Custom traits must begin with the prefix CUSTOM_
and contain only the
letters A through Z, the numbers 0 through 9 and the underscore “_”
character.
This command requires at least --os-placement-api-version 1.6
.
openstack trait create <name>
- name¶
Name of the trait.
This command is provided by the osc-placement plugin.
trait delete¶
Delete the trait specified by {name}.
This command requires at least --os-placement-api-version 1.6
.
openstack trait delete <name>
- name¶
Name of the trait.
This command is provided by the osc-placement plugin.
trait list¶
Return a list of valid trait strings.
This command requires at least --os-placement-api-version 1.6
.
openstack trait list
[--sort-column SORT_COLUMN]
[--sort-ascending | --sort-descending]
[--name <name>]
[--associated]
- --sort-column SORT_COLUMN¶
specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated
- --sort-ascending¶
sort the column(s) in ascending order
- --sort-descending¶
sort the column(s) in descending order
- --name <name>¶
A string to filter traits. The following options are available: startswith operator filters the traits whose name begins with a specific prefix, e.g. name=startswith:CUSTOM, in operator filters the traits whose name is in the specified list, e.g. name=in:HW_CPU_X86_AVX,HW_CPU_X86_SSE, HW_CPU_X86_INVALID_FEATURE.
- --associated¶
If this parameter is presented, the returned traits will be those that are associated with at least one resource provider.
This command is provided by the osc-placement plugin.
trait show¶
Check if a trait name exists in this cloud.
This command requires at least --os-placement-api-version 1.6
.
openstack trait show <name>
- name¶
Name of the trait.
This command is provided by the osc-placement plugin.