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>]
    [--aggregate-uuid <aggregate_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>=<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.

--aggregate-uuid <aggregate_uuid>¶

UUID of the resource provider aggregate of which the returned allocation candidates are a member. The returned allocation candidates must be associated with at least one of the aggregates identified by uuid. May be repeated.

This param requires at least --os-placement-api-version 1.21.

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.

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

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.

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 the --provider 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]
    <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. 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. Specify multiple times to remove allocations against multiple resource providers. Omit this option to remove all allocations for the consumer.

consumer_uuid¶: UUID of the consumer

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>]
    [--aggregate-uuid <aggregate_uuid>]
    [--resource <resource_class>=<value>]
    [--in-tree <in_tree>]
    [--required <required>]
    [--forbidden <forbidden>]

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

--aggregate-uuid <aggregate_uuid>¶

UUID of the resource provider aggregate of which the listed resource providers are a member. The returned resource providers must be associated with at least one of the aggregates identified by uuid. May be repeated.

This param requires at least --os-placement-api-version 1.3.

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

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.

Command Line Reference

Command Line Reference¶

allocation candidate list¶

resource class create¶

resource class delete¶

resource class list¶

resource class set¶

resource class show¶

resource provider aggregate list¶

resource provider aggregate set¶

resource provider allocation delete¶

resource provider allocation set¶

resource provider allocation show¶

resource provider allocation unset¶

resource provider create¶

resource provider delete¶

resource provider inventory class set¶

resource provider inventory delete¶

resource provider inventory list¶

resource provider inventory set¶

resource provider inventory show¶

resource provider list¶

resource provider set¶

resource provider show¶

resource provider trait delete¶

resource provider trait list¶

resource provider trait set¶

resource provider usage show¶

resource usage show¶

trait create¶

trait delete¶

trait list¶

trait show¶

osc-placement 2.2.1.dev2

Page Contents