nova/api-ref/source/parameters.yaml
Sean Mooney 320c6fadde [codespell] fix typos in api-ref
this change uses codespell to fix typos in
the api-ref and updates setup.cfg to exclude more
binary types and build files.

Change-Id: Ife9bf9a87c70126969bf43f7aa4a3645617de901
2023-10-03 01:09:59 +01:00

7568 lines
205 KiB
YAML

# variables in header
image_location:
description: |
The image location URL of the image or backup created, HTTP header
"Location: <image location URL>" will be returned.
.. note:: The URL returned may not be accessible to users and should not
be relied upon. Use microversion 2.45 or simply parse the image ID out
of the URL in the Location response header.
in: header
required: true
type: string
max_version: 2.44
server_location:
description: |
The location URL of the server, HTTP header
"Location: <server location URL>" will be returned.
in: header
required: true
type: string
tag_location:
description: |
The location of the tag. It's individual tag URL which can be used for
checking the existence of the tag on the server or deleting the tag from the server.
in: header
required: true
type: string
x-compute-request-id_resp:
description: |
The local request ID, which is a unique ID generated automatically
for tracking each request to nova.
It is associated with the request and appears in the log lines
for that request.
By default, the middleware configuration
ensures that the local request ID appears in the log files.
.. note::
This header exists for backward compatibility.
in: header
required: true
type: string
x-openstack-request-id_req:
description: |
The global request ID, which is a unique common ID
for tracking each request in OpenStack components.
The format of the global request ID must be ``req-`` + UUID (UUID4).
If not in accordance with the format, it is ignored.
It is associated with the request and appears in the log lines
for that request.
By default, the middleware configuration ensures that
the global request ID appears in the log files.
in: header
required: false
type: string
min_version: 2.46
x-openstack-request-id_resp:
description: |
The local request ID, which is a unique ID generated automatically
for tracking each request to nova.
It is associated with the request and appears in the log lines
for that request.
By default, the middleware configuration
ensures that the local request ID appears in the log files.
in: header
required: true
type: string
min_version: 2.46
# variables in path
agent_build_id:
description: |
The id of the agent build.
in: path
required: true
type: string
aggregate_id:
description: |
The aggregate ID.
in: path
required: true
type: integer
api_version:
in: path
required: true
type: string
description: >
The API version as returned in the links from the ``GET /`` call.
before_timestamp:
description: |
Filters the response by the date and time before which to list usage
audits.
The date and time stamp format is as follows:
::
CCYY-MM-DD hh:mm:ss.NNNNNN
For example, ``2015-08-27 09:49:58`` or ``2015-08-27 09:49:58.123456``.
in: path
required: true
type: string
cell_id:
description: |
The UUID of the cell.
in: path
required: true
type: string
console_id:
description: |
The UUID of the console.
in: path
required: true
type: string
console_token:
description: |
Console authentication token.
in: path
required: true
type: string
# Used in the request path for PUT /os-services/disable-log-reason before
# microversion 2.53.
disabled_reason:
description: |
The reason for disabling a service.
in: path
required: false
type: string
domain:
description: |
The registered DNS domain that the DNS drivers publish.
in: path
required: true
type: string
fixed_ip_path:
description: |
The fixed IP of interest to you.
in: path
required: true
type: string
flavor_extra_spec_key:
description: |
The extra spec key for the flavor.
in: path
required: true
type: string
flavor_id:
description: |
The ID of the flavor.
in: path
required: true
type: string
floating_ip_id:
description: |
The ID of the floating IP address.
in: path
required: true
type: string
host_name:
description: |
The name of the host.
in: path
required: true
type: string
hypervisor_hostname_pattern:
description: |
The hypervisor host name or a portion of it.
The hypervisor hosts are selected with the host name matching this pattern.
in: path
required: true
type: string
hypervisor_id:
description: |
The ID of the hypervisor.
in: path
required: true
type: integer
max_version: 2.52
hypervisor_id_uuid:
description: |
The ID of the hypervisor as a UUID.
in: path
required: true
type: string
min_version: 2.53
image_id:
description: |
The UUID of the image.
in: path
required: true
type: string
instance_id:
description: |
The UUID of the instance.
in: path
required: true
type: string
ip:
description: |
The IP address.
in: path
required: true
type: string
key:
description: |
The metadata item key, as a string. Maximum length is 255 characters.
in: path
required: true
type: string
keypair_name_path:
description: |
The keypair name.
in: path
required: true
type: string
migration_id_path:
description: |
The ID of the server migration.
in: path
required: true
type: integer
network_id:
description: |
The UUID of the network.
in: path
required: true
type: string
network_label:
description: |
The network label, such as ``public`` or ``private``.
in: path
required: true
type: string
node_id:
description: |
The node ID.
in: path
required: true
type: string
port_id_path:
description: |
The UUID of the port.
in: path
required: true
type: string
quota_class_id: &quota_class_id
description: |
The ID of the quota class.
Nova supports the ``default`` Quota Class only.
in: path
required: true
type: string
request_id:
description: |
The ID of the request.
in: path
required: true
type: string
security_group_default_rule_id:
description: |
The UUID of the security group rule.
in: path
required: true
type: string
security_group_id:
description: |
The ID of the security group.
in: path
required: true
type: string
security_group_rule_id:
description: |
The ID of the security group rule.
in: path
required: true
type: string
server_group_id:
description: |
The UUID of the server group.
in: path
required: true
type: string
server_id_path:
description: |
The UUID of the server.
in: path
required: true
type: string
service_id_path_2_52:
description: |
The id of the service.
.. note:: This may not uniquely identify a service in a multi-cell
deployment.
in: path
required: true
type: integer
max_version: 2.52
service_id_path_2_53:
description: |
The id of the service as a uuid. This uniquely identifies the service in a
multi-cell deployment.
in: path
required: true
type: string
min_version: 2.53
service_id_path_2_53_no_version:
description: |
The id of the service as a uuid. This uniquely identifies the service in a
multi-cell deployment.
in: path
required: true
type: string
snapshot_id_path:
description: |
The UUID of the snapshot.
in: path
required: true
type: string
tag:
description: |
The tag as a string.
in: path
required: true
type: string
tenant_id:
description: |
The UUID of the tenant in a multi-tenancy cloud.
in: path
required: true
type: string
volume_id_attached_path:
description: |
The UUID of the attached volume.
in: path
required: true
type: string
volume_id_path:
description: |
The unique ID for a volume.
in: path
required: true
type: string
volume_id_swap_src:
description: |
The UUID of the volume being replaced.
in: path
required: true
type: string
volume_id_to_detach_path:
description: |
The UUID of the volume to detach.
in: path
required: true
type: string
# variables in query
access_ip_v4_query_server:
in: query
required: false
type: string
description: |
Filter server list result by IPv4 address that should be used
to access the server.
access_ip_v6_query_server:
in: query
required: false
type: string
description: |
Filter server list result by IPv6 address that should be used
to access the server.
all_projects:
description: |
Administrator only. Lists server groups for all projects. For example:
``GET /os-server-groups?all_projects=True``
If you specify a tenant ID for a non-administrative user with this query parameter,
the call lists all server groups for the tenant, or project, rather than for
all projects.
Value of this query parameter is not checked, only presence is considered
as request for all projects.
in: query
required: false
type: string
all_tenants:
description: |
Specify the ``all_tenants`` query parameter to ping instances
for all tenants. By default this is only allowed by admin users.
Value of this query parameter is not checked, only presence
is considered as request for all tenants.
in: query
required: false
type: string
all_tenants_query:
description: |
Specify the ``all_tenants`` query parameter to list all instances
for all projects. By default this is only allowed by administrators.
If this parameter is specified without a value, the value defaults to
``True``. If the value is specified, ``1``, ``t``, ``true``,
``on``, ``y`` and ``yes`` are treated as ``True``. ``0``, ``f``,
``false``, ``off``, ``n`` and ``no`` are treated as ``False``.
(They are case-insensitive.)
in: query
required: false
type: boolean
all_tenants_sec_grp_query:
description: |
Specify the ``all_tenants`` query parameter to list all security
groups for all projects. This is only allowed for admin users.
Value of this query parameter is not checked, only presence
is considered as request for all tenants.
in: query
required: false
type: string
availability_zone_query_server:
description: |
Filter the server list result by server availability zone.
This parameter is restricted to administrators until microversion 2.83.
If non-admin users specify this parameter on a microversion less than 2.83,
it will be ignored.
in: query
required: false
type: string
binary_query:
description: |
Filter the service list result by binary name of the service.
in: query
required: false
type: string
changes-since:
description: |
Filters the response by a date and time when the image last changed status.
Use this query parameter to check for changes since a previous request rather
than re-downloading and re-parsing the full status at each polling interval.
If data has changed, the call returns only the items changed since the ``changes-since``
time. If data has not changed since the ``changes-since`` time, the call returns an
empty list.
To enable you to keep track of changes, this filter also displays images
that were deleted if the ``changes-since`` value specifies a date in the last 30 days.
Items deleted more than 30 days ago might be returned, but it is not guaranteed.
The date and time stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
The ``±hh:mm`` value, if included, returns the time zone as an offset from UTC.
For example, ``2015-08-27T09:49:58-05:00``.
If you omit the time zone, the UTC time zone is assumed.
in: query
required: false
type: string
changes_before_instance_action:
description: |
Filters the response by a date and time stamp when the instance actions last changed.
Those instances that changed before or equal to the specified date and time stamp
are returned.
The date and time stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
The ``±hh:mm`` value, if included, returns the time zone as an offset from UTC.
For example, ``2015-08-27T09:49:58-05:00``.
If you omit the time zone, the UTC time zone is assumed.
When both ``changes-since`` and ``changes-before`` are specified,
the value of the ``changes-before`` must be later than or equal to
the value of the ``changes-since`` otherwise API will return 400.
in: query
required: false
type: string
min_version: 2.66
changes_before_migration:
description: |
Filters the response by a date and time stamp when the migration last
changed. Those migrations that changed before or equal to the specified date and time
stamp are returned.
The date and time stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
The ``±hh:mm`` value, if included, returns the time zone as an offset from UTC.
For example, ``2015-08-27T09:49:58-05:00``.
If you omit the time zone, the UTC time zone is assumed.
When both ``changes-since`` and ``changes-before`` are specified,
the value of the ``changes-before`` must be later than or equal to
the value of the ``changes-since`` otherwise API will return 400.
in: query
required: false
type: string
min_version: 2.66
changes_before_server:
description: |
Filters the response by a date and time stamp when the server last changed.
Those servers that changed before or equal to the specified date and time stamp
are returned. To help keep track of changes this may also return recently deleted
servers.
The date and time stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
The ``±hh:mm`` value, if included, returns the time zone as an offset from UTC.
For example, ``2015-08-27T09:49:58-05:00``.
If you omit the time zone, the UTC time zone is assumed.
When both ``changes-since`` and ``changes-before`` are specified,
the value of the ``changes-before`` must be later than or equal to
the value of the ``changes-since`` otherwise API will return 400.
in: query
required: false
type: string
min_version: 2.66
changes_since_instance_action:
description: |
Filters the response by a date and time stamp when the instance action last
changed.
The date and time stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
The ``±hh:mm`` value, if included, returns the time zone as an offset from UTC.
For example, ``2015-08-27T09:49:58-05:00``.
If you omit the time zone, the UTC time zone is assumed.
When both ``changes-since`` and ``changes-before`` are specified,
the value of the ``changes-since`` must be earlier than or equal to
the value of the ``changes-before`` otherwise API will return 400.
in: query
required: false
type: string
min_version: 2.58
changes_since_migration:
description: |
Filters the response by a date and time stamp when the migration last
changed. Those changed after the specified date and time stamp are returned.
The date and time stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
The ``±hh:mm`` value, if included, returns the time zone as an offset from UTC.
For example, ``2015-08-27T09:49:58-05:00``.
If you omit the time zone, the UTC time zone is assumed.
When both ``changes-since`` and ``changes-before`` are specified,
the value of the ``changes-since`` must be earlier than or equal to
the value of the ``changes-before`` otherwise API will return 400.
in: query
required: false
type: string
min_version: 2.59
changes_since_server:
description: |
Filters the response by a date and time stamp when the server last
changed status. To help keep track of changes this may also return
recently deleted servers.
The date and time stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
The ``±hh:mm`` value, if included, returns the time zone as an offset from UTC.
For example, ``2015-08-27T09:49:58-05:00``.
If you omit the time zone, the UTC time zone is assumed.
When both ``changes-since`` and ``changes-before`` are specified,
the value of the ``changes-since`` must be earlier than or equal to
the value of the ``changes-before`` otherwise API will return 400.
in: query
required: false
type: string
config_drive_query_server:
description: |
Filter the server list result by the config drive setting of the server.
This parameter is restricted to administrators until microversion 2.83.
If non-admin users specify this parameter on a microversion less than 2.83,
it will be ignored.
in: query
required: false
type: string
created_at_query_server:
description: |
Filter the server list result by a date and time stamp when server was created.
The date and time stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
The ``±hh:mm`` value, if included, returns the time zone as an offset from UTC.
For example, ``2015-08-27T09:49:58-05:00``.
If you omit the time zone, the UTC time zone is assumed.
This parameter is restricted to administrators until microversion 2.83.
If non-admin users specify this parameter on a microversion less than 2.83,
it will be ignored.
in: query
required: false
type: string
delete_info:
description: |
Information for snapshot deletion. Include the ID of the associated volume. For
example:
.. code-block:: javascript
DELETE /os-assisted-volume-snapshots/421752a6-acf6-4b2d-bc7a-119f9148cd8c?delete_info='{"volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c"}'
in: query
required: true
type: string
deleted_query:
in: query
required: false
type: boolean
description: |
Show deleted items only. In some circumstances deleted items will still
be accessible via the backend database, however there is no
contract on how long, so this parameter should be used with
caution. ``1``, ``t``, ``true``, ``on``, ``y`` and ``yes`` are treated as
``True`` (case-insensitive). Other than them are treated as ``False``.
This parameter is only valid when specified by administrators.
If non-admin users specify this parameter, it is ignored.
description_query_server:
description: |
Filter the server list result by description.
This parameter is only valid when specified by administrators.
If non-admin users specify this parameter, it is ignored.
.. note::
``display_description`` can also be requested which is alias of
``description`` but that is not recommended to use as that will
be removed in future.
in: query
required: false
type: string
detailed_simple_tenant_usage:
description: |
Specify the ``detailed=1`` query parameter to get detail information
('server_usages' information).
in: query
required: false
type: integer
disk_config_query_server:
description: |
Filter the server list result by the ``disk_config`` setting of the server,
Valid values are:
- ``AUTO``
- ``MANUAL``
This parameter is only valid when specified by administrators.
If non-admin users specify this parameter, it is ignored.
in: query
required: false
type: string
end_simple_tenant_usage:
description: |
The ending time to calculate usage statistics on compute and
storage resources. The date and time stamp format is any of
the following ones:
::
CCYY-MM-DDThh:mm:ss
For example, ``2015-08-27T09:49:58``.
::
CCYY-MM-DDThh:mm:ss.NNNNNN
For example, ``2015-08-27T09:49:58.123456``.
::
CCYY-MM-DD hh:mm:ss.NNNNNN
For example, ``2015-08-27 09:49:58.123456``.
If you omit this parameter, the current time is used.
in: query
required: false
type: string
exclude:
description: |
Specify ``exclude=uuid[,uuid...]`` to exclude the instances from the results.
in: query
required: false
type: string
flavor_is_public_query:
in: query
required: false
type: string
description: |
This parameter is only applicable to users with the administrative role.
For all other non-admin users, the parameter is ignored and only public
flavors will be returned. Filters the flavor list based on whether the
flavor is public or private. If the value of this parameter is not
specified, it is treated as ``True``. If the value is specified, ``1``,
``t``, ``true``, ``on``, ``y`` and ``yes`` are treated as ``True``. ``0``,
``f``, ``false``, ``off``, ``n`` and ``no`` are treated as ``False``
(they are case-insensitive). If the value is ``None`` (case-insensitive)
both public and private flavors will be listed in a single request.
flavor_query:
description: |
Filters the response by a flavor, as a UUID. A flavor is a combination of memory,
disk size, and CPUs.
in: query
required: false
type: string
host_query_server:
description: |
Filter the server list result by the host name of compute node.
This parameter is only valid when specified by administrators.
If non-admin users specify this parameter, it is ignored.
in: query
required: false
type: string
host_query_service:
description: |
Filter the service list result by the host name.
in: query
required: false
type: string
hostname_query_server:
description: |
Filter the server list result by the host name of server.
This parameter is only valid when specified by administrators until
microversion 2.90, after which it can be specified by all users.
If non-admin users specify this parameter before microversion 2.90, it is
ignored.
in: query
required: false
type: string
hypervisor_hostname_pattern_query:
description: |
The hypervisor host name or a portion of it. The hypervisor hosts are
selected with the host name matching this pattern.
.. note:: ``limit`` and ``marker`` query parameters for paging are
not supported when listing hypervisors using a hostname pattern.
Also, ``links`` will not be returned in the response when using this
query parameter.
in: query
required: false
type: string
min_version: 2.53
hypervisor_limit:
description: |
Requests a page size of items. Returns a number of items up to a limit value.
Use the ``limit`` parameter to make an initial limited request and use the ID
of the last-seen item from the response as the ``marker`` parameter value in a
subsequent limited request.
in: query
required: false
type: integer
min_version: 2.33
hypervisor_marker:
description: |
The ID of the last-seen item. Use the ``limit`` parameter to make an initial limited
request and use the ID of the last-seen item from the response as the ``marker``
parameter value in a subsequent limited request.
in: query
required: false
type: integer
min_version: 2.33
max_version: 2.52
hypervisor_marker_uuid:
description: |
The ID of the last-seen item as a UUID. Use the ``limit`` parameter to make
an initial limited request and use the ID of the last-seen item from the
response as the ``marker`` parameter value in a subsequent limited request.
in: query
required: false
type: string
min_version: 2.53
hypervisor_query:
description: |
Filters the response by a hypervisor type.
in: query
required: false
type: string
hypervisor_with_servers_query:
description: |
Include all servers which belong to each hypervisor in the response output.
in: query
required: false
type: boolean
min_version: 2.53
image_name_query:
description: |
Filters the response by an image name, as a string.
in: query
required: false
type: string
image_query:
description: |
Filters the response by an image, as a UUID.
.. note::
'image_ref' can also be requested which is alias of 'image'
but that is not recommended to use as that will be removed in future.
in: query
required: false
type: string
image_server_query:
description: |
Filters the response by a server, as a URL.
format: uri
in: query
required: false
type: string
image_status_query:
description: |
Filters the response by an image status, as a string. For example, ``ACTIVE``.
in: query
required: false
type: string
image_type_query:
description: |
Filters the response by an image type. For example, ``snapshot`` or ``backup``.
in: query
required: false
type: string
include:
description: |
Specify ``include=uuid[,uuid...]`` to include the instances in the results.
in: query
required: false
type: string
instance_action_limit:
description: |
Requests a page size of items. Returns a number of items up to a limit value.
Use the ``limit`` parameter to make an initial limited request and use the
last-seen item from the response as the ``marker`` parameter value in a
subsequent limited request.
in: query
required: false
type: integer
min_version: 2.58
instance_action_marker:
description: |
The ``request_id`` of the last-seen instance action. Use the ``limit``
parameter to make an initial limited request and use the last-seen
item from the response as the ``marker`` parameter value in a subsequent
limited request.
in: query
required: false
type: string
min_version: 2.58
ip6_query:
description: |
An IPv6 address to filter results by.
Up to microversion 2.4, this parameter is only valid when specified
by administrators. If non-admin users specify this parameter,
it is ignored.
Starting from microversion 2.5, this parameter is valid for no-admin users
as well as administrators.
in: query
required: false
type: string
ip_query:
description: |
An IPv4 address to filter results by.
in: query
required: false
type: string
kernel_id_query_server:
in: query
required: false
type: string
description: |
Filter the server list result by the UUID of the kernel image
when using an AMI.
This parameter is only valid when specified by administrators.
If non-admin users specify this parameter, it is ignored.
key_name_query_server:
description: |
Filter the server list result by keypair name.
This parameter is restricted to administrators until microversion 2.83.
If non-admin users specify this parameter on a microversion less than 2.83,
it will be ignored.
in: query
required: false
type: string
keypair_limit:
description: |
Requests a page size of items. Returns a number of items up to a limit value.
Use the ``limit`` parameter to make an initial limited request and use the
last-seen item from the response as the ``marker`` parameter value in a
subsequent limited request.
in: query
required: false
type: integer
min_version: 2.35
keypair_marker:
description: |
The last-seen item. Use the ``limit`` parameter to make an initial limited
request and use the last-seen item from the response as the ``marker``
parameter value in a subsequent limited request.
in: query
required: false
type: string
min_version: 2.35
keypair_user:
in: query
required: false
type: string
description: |
This allows administrative users to operate key-pairs of specified
user ID.
min_version: 2.10
launch_index_query_server:
description: |
Filter the server list result by the sequence in which the
servers were launched.
This parameter is only valid when specified by administrators.
If non-admin users specify this parameter, it is ignored.
in: query
required: false
type: integer
launched_at_query_server:
description: |
Filter the server list result by a date and time stamp when the instance was launched.
The date and time stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
The ``±hh:mm`` value, if included, returns the time zone as an offset from UTC.
For example, ``2015-08-27T09:49:58-05:00``.
If you omit the time zone, the UTC time zone is assumed.
This parameter is restricted to administrators until microversion 2.83.
If non-admin users specify this parameter on a microversion less than 2.83,
it will be ignored.
in: query
required: false
type: string
limit:
description: |
Requests a page size of items. Returns a number of items up to a limit value.
Use the ``limit`` parameter to make an initial limited request and use the ID
of the last-seen item from the response as the ``marker`` parameter value in a
subsequent limited request.
in: query
required: false
type: integer
limit_simple:
description: |
Used in conjunction with ``offset`` to return a slice of items. ``limit``
is the maximum number of items to return. If ``limit`` is not specified,
or exceeds the configurable ``max_limit``, then ``max_limit`` will be
used instead.
in: query
required: false
type: integer
locked_by_query_server:
description: |
Filter the server list result by who locked the server, possible value
could be ``admin`` or ``owner``.
This parameter is only valid when specified by administrators.
If non-admin users specify this parameter, it is ignored.
in: query
required: false
type: string
locked_query_server:
description: |
Specify the ``locked`` query parameter to list all locked or unlocked
instances. If the value is specified, ``1``, ``t``, ``true``,
``on``, ``y`` and ``yes`` are treated as ``True``. ``0``, ``f``,
``false``, ``off``, ``n`` and ``no`` are treated as ``False``.
(They are case-insensitive.) Any other value provided will be considered
invalid.
in: query
required: false
type: boolean
min_version: 2.73
marker:
description: |
The ID of the last-seen item. Use the ``limit`` parameter to make an initial limited
request and use the ID of the last-seen item from the response as the ``marker``
parameter value in a subsequent limited request.
in: query
required: false
type: string
migration_hidden:
description: |
The 'hidden' setting of migration to filter.
The 'hidden' flag is set if the value is 1.
The 'hidden' flag is not set if the value is 0.
But the 'hidden' setting of migration is always 0,
so this parameter is useless to filter migrations.
in: query
required: false
type: integer
migration_host:
description: |
The source/destination compute node of migration to filter.
in: query
required: false
type: string
migration_instance_uuid:
description: |
The uuid of the instance that migration is operated on to filter.
in: query
required: false
type: string
migration_limit:
description: |
Requests a page size of items. Returns a number of items up to a limit value.
Use the ``limit`` parameter to make an initial limited request and use the
last-seen item from the response as the ``marker`` parameter value in a
subsequent limited request.
in: query
required: false
type: integer
min_version: 2.59
migration_marker:
description: |
The UUID of the last-seen migration. Use the ``limit`` parameter to make an
initial limited request and use the last-seen item from the response as
the ``marker`` parameter value in a subsequent limited request.
in: query
required: false
type: string
min_version: 2.59
migration_source_compute:
description: |
The source compute node of migration to filter.
in: query
required: false
type: string
migration_status:
description: |
The status of migration to filter.
in: query
required: false
type: string
migration_type:
description: |
The type of migration to filter. Valid values are:
* ``evacuation``
* ``live-migration``
* ``migration``
* ``resize``
in: query
required: false
type: string
minDisk:
description: |
Filters the response by a minimum disk space, in GiB. For example, ``100``.
in: query
required: false
type: integer
minRam:
description: |
Filters the response by a minimum RAM, in MiB. For example, ``512``.
in: query
required: false
type: integer
node_query_server:
description: |
Filter the server list result by the node.
This parameter is only valid when specified by administrators.
If non-admin users specify this parameter, it is ignored.
in: query
required: false
type: string
not_tags_any_query:
in: query
required: false
type: string
description: |
A list of tags to filter the server list by. Servers that don't
match any tags in this list will be returned. Boolean expression in this
case is 'NOT (t1 OR t2)'. Tags in query must be separated by comma.
min_version: 2.26
not_tags_query:
in: query
required: false
type: string
description: |
A list of tags to filter the server list by. Servers that don't
match all tags in this list will be returned. Boolean expression in this
case is 'NOT (t1 AND t2)'. Tags in query must be separated by comma.
min_version: 2.26
offset_simple:
description: |
Used in conjunction with ``limit`` to return a slice of items. ``offset``
is where to start in the list.
in: query
required: false
type: integer
power_state_query_server:
in: query
required: false
type: integer
description: |
Filter the server list result by server power state.
Possible values are integer values that is mapped as::
0: NOSTATE
1: RUNNING
3: PAUSED
4: SHUTDOWN
6: CRASHED
7: SUSPENDED
This parameter is restricted to administrators until microversion 2.83.
If non-admin users specify this parameter on a microversion less than 2.83,
it will be ignored.
progress_query_server:
description: |
Filter the server list result by the progress of the server.
The value could be from 0 to 100 as integer.
This parameter is restricted to administrators until microversion 2.83.
If non-admin users specify this parameter on a microversion less than 2.83,
it will be ignored.
in: query
required: false
type: integer
project_id_query_migrations:
description: |
Filter the migrations by the given project ID.
in: query
required: false
type: string
min_version: 2.80
project_id_query_server:
description: |
Filter the list of servers by the given project ID.
This filter only works when the ``all_tenants`` filter is also specified.
.. note::
'tenant_id' can also be requested which is alias of 'project_id'
but that is not recommended to use as that will be removed in future.
in: query
required: false
type: string
ramdisk_id_query_server:
in: query
required: false
type: string
description: |
Filter the server list result by the UUID of the ramdisk image when
using an AMI.
This parameter is only valid when specified by administrators.
If non-admin users specify this parameter, it is ignored.
reservation_id_query:
in: query
required: false
type: string
description: |
A reservation id as returned by a servers multiple create call.
reserved_query:
description: |
Specify whether the result of resource total includes reserved resources
or not.
- ``0``: Not include reserved resources.
- Other than 0: Include reserved resources.
If non integer value is specified, it is the same as ``0``.
in: query
required: false
type: integer
server_name_query:
description: |
Filters the response by a server name, as a string. You can use regular expressions
in the query. For example, the ``?name=bob`` regular expression returns both bob
and bobb. If you must match on only bob, you can use a regular expression that
matches the syntax of the underlying database server that is implemented for Compute,
such as MySQL or PostgreSQL.
.. note::
'display_name' can also be requested which is alias of 'name'
but that is not recommended to use as that will be removed in future.
format: regexp
in: query
required: false
type: string
server_root_device_name_query:
in: query
required: false
type: string
description: |
Filter the server list result by the root device name of the server.
This parameter is only valid when specified by administrators.
If non-admin users specify this parameter, it is ignored.
server_status_query:
description: |
Filters the response by a server status, as a string. For example, ``ACTIVE``.
Up to microversion 2.37, an empty list is returned if an invalid status is
specified. Starting from microversion 2.38, a 400 error is returned
in that case.
in: query
required: false
type: string
server_uuid_query:
description: |
Filter the server list result by the UUID of the server.
This parameter is only valid when specified by administrators.
If non-admin users specify this parameter, it is ignored.
in: query
required: false
type: string
soft_deleted_server:
description: |
Filter the server list by ``SOFT_DELETED`` status. This parameter is only valid
when the ``deleted=True`` filter parameter is specified.
in: query
required: false
type: boolean
sort_dir_flavor:
description: |
Sort direction. A valid value is ``asc`` (ascending) or ``desc`` (descending).
Default is ``asc``. You can specify multiple pairs of sort key and sort direction
query parameters. If you omit the sort direction in a pair, the API uses the natural
sorting direction of the flavor ``sort_key`` attribute.
in: query
required: false
type: string
sort_dir_server:
description: |
Sort direction. A valid value is ``asc`` (ascending) or ``desc`` (descending).
Default is ``desc``. You can specify multiple pairs of sort key and sort direction
query parameters. If you omit the sort direction in a pair, the API uses the natural
sorting direction of the server ``sort_key`` attribute.
in: query
required: false
type: string
sort_key_flavor:
description: |
Sorts by a flavor attribute. Default attribute is ``flavorid``. You can specify
multiple pairs of sort key and sort direction query parameters. If you omit the
sort direction in a pair, the API uses the natural sorting direction of the flavor
``sort_key`` attribute. The sort keys are limited to:
- ``created_at``
- ``description``
- ``disabled``
- ``ephemeral_gb``
- ``flavorid``
- ``id``
- ``is_public``
- ``memory_mb``
- ``name``
- ``root_gb``
- ``rxtx_factor``
- ``swap``
- ``updated_at``
- ``vcpu_weight``
- ``vcpus``
in: query
required: false
type: string
sort_key_server:
description: |
Sorts by a server attribute. Default attribute is ``created_at``. You can
specify multiple pairs of sort key and sort direction query parameters. If
you omit the sort direction in a pair, the API uses the natural sorting
direction of the server ``sort_key`` attribute. The sort keys are limited
to:
- ``access_ip_v4``
- ``access_ip_v6``
- ``auto_disk_config``
- ``availability_zone``
- ``config_drive``
- ``created_at``
- ``display_description``
- ``display_name``
- ``host``
- ``hostname``
- ``image_ref``
- ``instance_type_id``
- ``kernel_id``
- ``key_name``
- ``launch_index``
- ``launched_at``
- ``locked`` (New in version 2.73)
- ``locked_by``
- ``node``
- ``power_state``
- ``progress``
- ``project_id``
- ``ramdisk_id``
- ``root_device_name``
- ``task_state``
- ``terminated_at``
- ``updated_at``
- ``user_id``
- ``uuid``
- ``vm_state``
``host`` and ``node`` are only allowed for admin.
If non-admin users specify them, a 403 error is returned.
in: query
required: false
type: string
start_simple_tenant_usage:
description: |
The beginning time to calculate usage statistics on compute and
storage resources. The date and time stamp format is any of the
following ones:
::
CCYY-MM-DDThh:mm:ss
For example, ``2015-08-27T09:49:58``.
::
CCYY-MM-DDThh:mm:ss.NNNNNN
For example, ``2015-08-27T09:49:58.123456``.
::
CCYY-MM-DD hh:mm:ss.NNNNNN
For example, ``2015-08-27 09:49:58.123456``.
If you omit this parameter, the current time is used.
in: query
required: false
type: string
tags_any_query:
in: query
required: false
type: string
description: |
A list of tags to filter the server list by. Servers that match
any tag in this list will be returned. Boolean expression in this
case is 't1 OR t2'. Tags in query must be separated by comma.
min_version: 2.26
tags_query:
in: query
required: false
type: string
description: |
A list of tags to filter the server list by. Servers that match
all tags in this list will be returned. Boolean expression in this
case is 't1 AND t2'. Tags in query must be separated by comma.
min_version: 2.26
task_state_query_server:
in: query
required: false
type: string
description: |
Filter the server list result by task state.
This parameter is restricted to administrators until microversion 2.83.
If non-admin users specify this parameter on a microversion less than 2.83,
it will be ignored.
tenant_id_query:
description: |
Specify the project ID (tenant ID) to show the rate and absolute limits.
This parameter can be specified by admin only.
in: query
required: false
type: string
terminated_at_query_server:
description: |
Filter the server list result by a date and time stamp when instance was terminated.
The date and time stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
The ``±hh:mm`` value, if included, returns the time zone as an offset from UTC.
For example, ``2015-08-27T09:49:58-05:00``.
If you omit the time zone, the UTC time zone is assumed.
This parameter is restricted to administrators until microversion 2.83.
If non-admin users specify this parameter on a microversion less than 2.83,
it will be ignored.
in: query
required: false
type: string
usage_limit:
description: |
Requests a page size of items. Calculate usage for the limited number of
instances. Use the ``limit`` parameter to make an initial limited request
and use the last-seen instance UUID from the response as the ``marker``
parameter value in a subsequent limited request.
in: query
required: false
type: integer
min_version: 2.40
usage_marker:
description: |
The last-seen item. Use the ``limit`` parameter to make an initial limited
request and use the last-seen instance UUID from the response as the
``marker`` parameter value in a subsequent limited request.
in: query
required: false
type: string
min_version: 2.40
user_id_query_migrations:
description: |
Filter the migrations by the given user ID.
in: query
required: false
type: string
min_version: 2.80
user_id_query_quota:
description: |
ID of user to list the quotas for.
in: query
required: false
type: string
user_id_query_quota_delete:
description: |
ID of user to delete quotas for.
in: query
required: false
type: string
user_id_query_server:
description: |
Filter the list of servers by the given user ID.
This parameter is restricted to administrators until microversion 2.83.
If non-admin users specify this parameter on a microversion less than 2.83,
it will be ignored.
in: query
required: false
type: string
user_id_query_set_quota:
description: |
ID of user to set the quotas for.
in: query
required: false
type: string
vm_state_query_server:
description: |
Filter the server list result by vm state.
The value could be:
- ``ACTIVE``
- ``BUILDING``
- ``DELETED``
- ``ERROR``
- ``PAUSED``
- ``RESCUED``
- ``RESIZED``
- ``SHELVED``
- ``SHELVED_OFFLOADED``
- ``SOFT_DELETED``
- ``STOPPED``
- ``SUSPENDED``
This parameter is restricted to administrators until microversion 2.83.
If non-admin users specify this parameter on a microversion less than 2.83,
it will be ignored.
in: query
required: false
type: string
# variables in body
accessIPv4:
in: body
required: true
type: string
description: |
IPv4 address that should be used to access this server. May be
automatically set by the provider.
accessIPv4_in:
in: body
required: false
type: string
description: |
IPv4 address that should be used to access this server.
accessIPv6:
in: body
required: true
type: string
description: |
IPv6 address that should be used to access this server. May be
automatically set by the provider.
accessIPv6_in:
in: body
required: false
type: string
description: |
IPv6 address that should be used to access this server.
action:
description: |
The name of the action.
in: body
required: true
type: string
action_reserve:
description: |
The attribute to reserve an IP with a value of ``null``.
in: body
required: false
type: string
action_unreserve:
description: |
The attribute to release an IP with a value of ``null``.
in: body
required: false
type: string
addFixedIp:
description: |
The action to add a fixed ip address to a server.
in: body
required: true
type: object
addFloatingIp:
description: |
The action. Contains required floating IP ``address`` and optional
``fixed_address``.
in: body
required: true
type: object
address:
description: |
The floating IP address.
in: body
required: true
type: string
addresses:
description: |
The addresses for the server. Servers with status ``BUILD`` hide their
addresses information.
in: body
required: true
type: object
addresses_obj:
description: |
The addresses information for the server.
in: body
required: true
type: object
addSecurityGroup:
description: |
The action to add a security group to a server.
in: body
required: true
type: object
addTenantAccess:
description: |
The action.
in: body
required: true
type: string
adminPass_change_password:
description: |
The administrative password for the server.
in: body
required: true
type: string
adminPass_evacuate:
description: |
An administrative password to access the evacuated instance.
If you set ``enable_instance_password`` configuration option to ``False``,
the API wouldn't return the ``adminPass`` field in response.
in: body
required: false
type: string
max_version: 2.13
adminPass_evacuate_request:
description: |
An administrative password to access the evacuated server.
If you omit this parameter, the operation generates a new password.
Up to API version 2.13, if ``onSharedStorage`` is set to ``True`` and
this parameter is specified, an error is raised.
in: body
required: false
type: string
adminPass_request:
description: |
The administrative password of the server. If you omit this parameter, the operation
generates a new password.
in: body
required: false
type: string
adminPass_rescue_request:
description: |
The password for the rescued instance. If you omit this parameter, the operation
generates a new password.
in: body
required: false
type: string
adminPass_response:
description: |
The administrative password for the server. If you set ``enable_instance_password`` configuration
option to ``False``, the API wouldn't return the ``adminPass`` field in response.
in: body
required: false
type: string
agent:
description: |
The guest agent object.
in: body
required: true
type: object
agent_id:
description: |
The agent ID.
in: body
required: true
type: integer
agent_id_str:
description: |
The agent ID. (This is a bug of API, this should be integer type which is consistent with
the responses of agent create and list. This will be fixed in later microversion.)
in: body
required: true
type: string
agents:
description: |
A list of guest agent objects.
in: body
required: true
type: array
aggregate:
description: |
The host aggregate object.
in: body
required: true
type: object
aggregate_add_host:
description: |
The add_host object used to add host to aggregate.
in: body
required: true
type: object
aggregate_az:
description: |
The availability zone of the host aggregate.
in: body
required: true
type: string
aggregate_az_optional_create:
description: |
The availability zone of the host aggregate. You should use a custom
availability zone rather than the default returned by the
os-availability-zone API. The availability zone must not include ':'
in its name.
in: body
required: false
type: string
aggregate_az_optional_update:
description: |
The availability zone of the host aggregate. You should use a custom
availability zone rather than the default returned by the
os-availability-zone API. The availability zone must not include ':'
in its name.
.. warning:: You should not change or unset the availability zone of an
aggregate when that aggregate has hosts which contain servers in it
since that may impact the ability for those servers to move to another
host.
in: body
required: false
type: string
aggregate_host_list:
description: |
A list of host ids in this aggregate.
in: body
required: true
type: array
aggregate_id_body:
description: |
The ID of the host aggregate.
in: body
required: true
type: integer
aggregate_metadata_request:
description: |
Metadata key and value pairs associated with the aggregate.
The maximum size for each metadata key and value pair is 255 bytes.
New keys will be added to existing aggregate metadata. For existing
keys, if the value is ``null`` the entry is removed, otherwise the
value is updated. Note that the special ``availability_zone`` metadata
entry cannot be unset to ``null``.
.. warning:: You should not change the availability zone of an
aggregate when that aggregate has hosts which contain servers in it
since that may impact the ability for those servers to move to another
host.
in: body
required: true
type: object
aggregate_metadata_response:
description: |
Metadata key and value pairs associated with the aggregate.
in: body
required: true
type: object
aggregate_name:
description: |
The name of the host aggregate.
in: body
required: true
type: string
aggregate_name_optional:
description: |
The name of the host aggregate.
in: body
required: false
type: string
aggregate_remove_host:
description: |
The add_host object used to remove host from aggregate.
in: body
required: true
type: object
aggregate_uuid:
description: |
The UUID of the host aggregate.
in: body
required: true
type: string
min_version: 2.41
aggregates:
description: |
The list of existing aggregates.
in: body
required: true
type: array
alias:
description: |
A short name by which this extension is also known.
in: body
required: true
type: string
alive:
description: |
Returns true if the instance is alive.
in: body
required: true
type: boolean
architecture:
description: |
The name of the cpu architecture.
in: body
required: true
type: string
associate_host:
description: |
The name of the host to associate.
in: body
required: true
type: string
attachment_bdm_id_resp:
description: |
The UUID of the block device mapping record in Nova for the attachment.
in: body
required: true
type: string
min_version: 2.89
attachment_device_put_req:
description: |
Name of the device in the attachment object, such as, ``/dev/vdb``.
in: body
required: false
type: string
min_version: 2.85
attachment_device_resp:
description: |
Name of the device in the attachment object, such as, ``/dev/vdb``.
in: body
required: false
type: string
attachment_id_put_req:
description: |
The UUID of the attachment.
in: body
required: false
type: string
min_version: 2.85
attachment_id_resp:
description: |
The UUID of the attachment.
in: body
required: false
type: string
attachment_server_id_put_req:
description: |
The UUID of the server.
in: body
required: false
type: string
min_version: 2.85
attachment_server_id_resp:
description: |
The UUID of the server.
in: body
required: false
type: string
attachment_volume_id_resp:
description: |
The UUID of the associated volume attachment in Cinder.
in: body
required: true
type: string
min_version: 2.89
attachment_volumeId_resp:
description: |
The UUID of the attached volume.
in: body
required: false
type: string
availability_zone:
description: |
The availability zone.
in: body
required: false
type: string
availability_zone_info:
description: |
The list of availability zone information.
in: body
required: true
type: array
availability_zone_state:
description: |
The current state of the availability zone.
in: body
required: true
type: object
availability_zone_unshelve:
description: |
The availability zone name. Specifying an availability zone is only
allowed when the server status is ``SHELVED_OFFLOADED`` otherwise
HTTP 409 conflict response is returned.
Since microversion 2.91 ``"availability_zone":null`` allows unpinning the
instance from any availability_zone it is pinned to.
in: body
required: false
type: string
min_version: 2.77
available:
description: |
Returns true if the availability zone is available.
in: body
required: true
type: boolean
backup_name:
description: |
The name of the image to be backed up.
in: body
required: true
type: string
backup_rotation:
description: |
The rotation of the back up image, the oldest image will be removed when image count
exceed the rotation count.
in: body
required: true
type: integer
backup_type:
description: |
The type of the backup, for example, ``daily``.
in: body
required: true
type: string
baremetal_cpus:
description: |
Number of CPUs the node has.
.. note:: This is a JSON string, even though it will look like an int value.
in: body
required: true
type: string
baremetal_disk:
description: |
Amount of disk in GiB the node has.
.. note:: This is a JSON string, even though it will look like an int value.
in: body
required: true
type: string
baremetal_host:
description: |
This will always have the value ``IRONIC MANAGED``.
in: body
required: true
type: string
baremetal_id:
description: |
UUID of the baremetal node.
in: body
required: true
type: string
baremetal_instance_uuid:
description: |
UUID of the server instance on this node.
in: body
required: true
type: string
baremetal_interfaces:
description: |
A list of interface objects for active interfaces on the baremetal
node. Each will have an ``address`` field with the address.
in: body
required: true
type: array
baremetal_mem:
description: |
Amount of memory in MiB the node has.
.. note:: This is a JSON string, even though it will look like an int value.
in: body
required: true
type: string
baremetal_node:
description: |
A baremetal node object.
in: body
required: true
type: object
baremetal_nodes:
description: |
An array of baremetal node objects.
in: body
required: true
type: array
baremetal_taskstate:
description: |
The Ironic task state for the node. See Ironic project for more
details.
in: body
required: true
type: string
binary:
description: |
The binary name of the service.
in: body
required: true
type: string
block_device_mapping_v2:
description: |
Enables fine grained control of the block device mapping for an instance. This
is typically used for booting servers from volumes. An example format would look
as follows:
.. code-block:: javascript
"block_device_mapping_v2": [{
"boot_index": "0",
"uuid": "ac408821-c95a-448f-9292-73986c790911",
"source_type": "image",
"volume_size": "25",
"destination_type": "volume",
"delete_on_termination": true,
"tag": "disk1",
"disk_bus": "scsi"}]
In microversion 2.32, ``tag`` is an optional string attribute that can
be used to assign a tag to the block device. This tag is then exposed to
the guest in the metadata API and the config drive and is associated to
hardware metadata for that block device, such as bus (ex: SCSI), bus
address (ex: 1:0:2:0), and serial.
A bug has caused the ``tag`` attribute to no longer be accepted starting
with version 2.33. It has been restored in version 2.42.
in: body
required: false
type: array
block_device_uuid:
description: |
This is the uuid of source resource. The uuid points to different resources
based on the ``source_type``. For example, if ``source_type`` is ``image``,
the block device is created based on the specified image which is retrieved
from the image service. Similarly, if ``source_type`` is ``snapshot`` then
the uuid refers to a volume snapshot in the block storage service. If
``source_type`` is ``volume`` then the uuid refers to a volume in the block
storage service.
in: body
required: false
type: string
block_migration:
description: |
Set to ``True`` to migrate local disks by using block migration. If the source
or destination host uses shared storage and you set this value to ``True``, the
live migration fails.
in: body
required: true
type: boolean
max_version: 2.24
block_migration_2_25:
description: |
Migrates local disks by using block migration. Set to ``auto`` which means
nova will detect whether source and destination hosts on shared storage. if they are
on shared storage, the live-migration won't be block migration. Otherwise the block
migration will be executed. Set to ``True``, means the request will fail when the
source or destination host uses shared storage. Set to ``False`` means the request
will fail when the source and destination hosts are not on the shared storage.
in: body
required: true
type: string
min_version: 2.25
boot_index:
description: |
Defines the order in which a hypervisor tries devices when it attempts to boot
the guest from storage. Give each device a unique boot index starting from ``0``.
To disable a device from booting, set the boot index to a negative value or use
the default boot index value, which is ``None``. The simplest usage is, set the
boot index of the boot device to ``0`` and use the default boot index value, ``None``,
for any other devices. Some hypervisors might not support booting from multiple
devices; these hypervisors consider only the device with a boot index of ``0``. Some
hypervisors support booting from multiple devices but only if the devices are
of different types. For example, a disk and CD-ROM.
in: body
required: true
type: integer
cache:
description: A list of image objects to cache.
in: body
required: true
type: array
certificate:
description: |
The certificate object.
in: body
required: true
type: object
changePassword:
description: |
The action to change an administrative password of the server.
in: body
required: true
type: object
cidr:
description: |
The CIDR for address range.
in: body
required: true
type: string
cloudpipe:
description: |
The cloudpipe object.
in: body
required: true
type: object
cloudpipes:
description: |
The list of cloudpipe objects.
in: body
required: true
type: array
code:
description: |
The HTTP response code for the event. The following codes are currently used:
* 200 - successfully submitted event
* 400 - the request is missing required parameter
* 404 - the instance specified by ``server_uuid`` was not found
* 422 - no host was found for the server specified by ``server_uuid``,
so there is no route to this server.
in: body
required: true
type: string
config_drive:
description: |
Indicates whether a config drive enables metadata injection. The config_drive
setting provides information about a drive that the instance can mount at boot
time. The instance reads files from the drive to get information that is normally
available through the metadata service. This metadata is different from the user
data. Not all cloud providers enable the ``config_drive``. Read more in the
`OpenStack End User Guide <https://docs.openstack.org/nova/latest/user/config-drive.html>`_.
in: body
required: false
type: boolean
config_drive_diagnostics:
description: |
Indicates whether or not a config drive was used for this server.
in: body
required: true
type: boolean
min_version: 2.48
config_drive_resp:
description: |
Indicates whether or not a config drive was used for this server.
The value is ``True`` or an empty string. An empty string stands for
``False``.
in: body
required: true
type: string
config_drive_resp_update_rebuild:
description: |
Indicates whether or not a config drive was used for this server.
The value is ``True`` or an empty string. An empty string stands for
``False``.
in: body
required: true
type: string
min_version: 2.75
configure_project_cloudpipe:
description: |
VPN IP and Port information to configure the cloudpipe instance..
in: body
required: true
type: object
confirmResize:
description: |
The action to confirm a resize operation.
in: body
required: true
type: none
console:
description: |
The console object.
in: body
required: true
type: object
console_host:
description: |
The name or ID of the host.
in: body
required: false
type: string
console_id_in_body:
description: |
The UUID of the console.
in: body
required: true
type: string
console_output:
description: |
The console output as a string. Control characters will be escaped
to create a valid JSON string.
in: body
required: true
type: string
console_password:
description: |
The password for the console.
in: body
required: true
type: string
console_type:
description: |
The type of the console.
in: body
required: true
type: string
consoles:
description: |
The list of console objects.
in: body
required: true
type: array
contents:
description: |
The file contents field in the personality object.
in: body
required: true
type: string
max_version: 2.56
cores: &cores
description: |
The number of allowed server cores for each tenant.
in: body
required: true
type: integer
cores_quota_class: &cores_quota_class
<<: *cores
description: |
The number of allowed server cores for the quota class.
cores_quota_class_optional:
<<: *cores_quota_class
required: false
cores_quota_details:
description: |
The object of detailed cores quota, including in_use, limit and
reserved number of cores.
in: body
required: true
type: object
cores_quota_optional:
description: |
The number of allowed server cores for each tenant.
in: body
required: false
type: integer
cpu_details_diagnostics:
description: |
The list of dictionaries with detailed information about VM CPUs.
Following fields are presented in each dictionary:
- ``id`` - the ID of CPU (Integer)
- ``time`` - CPU Time in nano seconds (Integer)
- ``utilisation`` - CPU utilisation in percents (Integer)
in: body
required: true
type: array
min_version: 2.48
cpu_info:
description: |
A dictionary that contains cpu information like ``arch``, ``model``,
``vendor``, ``features`` and ``topology``. The content of this field is
hypervisor specific.
.. note::
Since version 2.28 ``cpu_info`` field is returned as a dictionary
instead of string.
in: body
required: true
type: object
max_version: 2.87
create_info:
description: |
Information for snapshot creation.
in: body
required: true
type: object
create_info_id:
description: |
Its an arbitrary string that gets passed back to the user.
in: body
required: false
type: string
create_info_id_resp:
description: |
Its the same arbitrary string which was sent in request body.
.. note::
This string is passed back to user as it is and not being
used in Nova internally. So use ``snapshot_id`` instead for further
operation on this snapshot.
in: body
required: true
type: string
createBackup:
description: |
The action.
in: body
required: true
type: object
created:
description: |
The date and time when the resource was created. The date and time
stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2015-08-27T09:49:58-05:00``. The ``±hh:mm``
value, if included, is the time zone as an offset from UTC. In
the previous example, the offset value is ``-05:00``.
in: body
required: true
type: string
createImage:
description: |
The action to create a snapshot of the image or
the volume(s) of the server.
in: body
required: true
type: object
current_workload:
description: |
The current_workload is the number of tasks the hypervisor is responsible
for. This will be equal or greater than the number of active VMs on the
system (it can be greater when VMs are being deleted and the hypervisor is
still cleaning up).
in: body
required: true
type: integer
max_version: 2.87
current_workload_total:
description: |
The current_workload is the number of tasks the hypervisors are responsible
for. This will be equal or greater than the number of active VMs on the
systems (it can be greater when VMs are being deleted and a hypervisor is
still cleaning up).
in: body
required: true
type: integer
data:
description: |
The certificate.
in: body
required: true
type: string
delete_on_termination:
description: |
To delete the boot volume when the server is destroyed, specify ``true``.
Otherwise, specify ``false``. Default: ``false``
in: body
required: false
type: boolean
delete_on_termination_attachments_req:
description: |
To delete the attached volume when the server is destroyed, specify ``true``.
Otherwise, specify ``false``. Default: ``false``
in: body
required: false
type: boolean
min_version: 2.79
delete_on_termination_attachments_resp:
description: |
A flag indicating if the attached volume will be deleted when the server is
deleted.
in: body
required: true
type: boolean
min_version: 2.79
delete_on_termination_put_req:
description: |
A flag indicating if the attached volume will be deleted when the server is
deleted.
in: body
required: false
type: boolean
min_version: 2.85
deleted:
description: |
A boolean indicates whether this aggregate is deleted or not, if it has
not been deleted, ``false`` will appear.
in: body
required: true
type: boolean
deleted_at:
description: |
The date and time when the resource was deleted. If the resource has
not been deleted yet, this field will be ``null``, The date and time
stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2015-08-27T09:49:58-05:00``. The ``±hh:mm``
value, if included, is the time zone as an offset from UTC. In
the previous example, the offset value is ``-05:00``.
in: body
required: true
type: string
description:
description: |
Security group description.
in: body
required: true
type: string
destination_type:
description: |
Defines where the block device mapping will reside. Valid values are:
* ``local``: The ephemeral disk resides local to the compute host on
which the server runs
* ``volume``: The persistent volume is stored in the block storage service
in: body
required: false
type: string
device:
description: |
Name of the device such as, ``/dev/vdb``. Omit or set this parameter to null for
auto-assignment, if supported. If you specify this parameter, the device must
not exist in the guest operating system. Note that as of the 12.0.0 Liberty release,
the Nova libvirt driver no longer honors a user-supplied device name. This is
the same behavior as if the device name parameter is not supplied on the request.
in: body
required: false
type: string
device_name:
description: |
A path to the device for the volume that you want to use to boot the server.
Note that as of the 12.0.0 Liberty release, the Nova libvirt driver no
longer honors a user-supplied device name. This is the same behavior as if
the device name parameter is not supplied on the request.
in: body
required: false
type: string
device_resp:
description: |
Name of the device such as, ``/dev/vdb``.
in: body
required: true
type: string
device_tag_bdm:
description: |
A device role tag that can be applied to a block device. The guest OS of a
server that has devices tagged in this manner can access hardware metadata
about the tagged devices from the metadata API and on the config drive, if
enabled.
.. note:: Due to a bug, block device tags are accepted in version 2.32 and
subsequently starting with version 2.42.
in: body
required: false
type: string
min_version: 2.32
device_tag_bdm_attachment:
description: |
A device role tag that can be applied to a volume when attaching it to the
VM. The guest OS of a server that has devices tagged in this manner can
access hardware metadata about the tagged devices from the metadata API and
on the config drive, if enabled.
.. note:: Tagged volume attachment is not supported for shelved-offloaded
instances.
in: body
required: false
type: string
min_version: 2.49
device_tag_bdm_attachment_put_req:
description: |
The device tag applied to the volume block device or ``null``.
in: body
required: true
type: string
min_version: 2.85
device_tag_bdm_attachment_resp:
description: |
The device tag applied to the volume block device or ``null``.
in: body
required: true
type: string
min_version: 2.70
device_tag_nic:
description: |
A device role tag that can be applied to a network interface. The guest OS
of a server that has devices tagged in this manner can access hardware
metadata about the tagged devices from the metadata API and on the config
drive, if enabled.
.. note:: Due to a bug, network interface tags are accepted between 2.32
and 2.36 inclusively, and subsequently starting with version 2.42.
in: body
required: false
type: string
min_version: 2.32
device_tag_nic_attachment:
description: |
A device role tag that can be applied to a network interface when attaching
it to the VM. The guest OS of a server that has devices tagged in this
manner can access hardware metadata about the tagged devices from the
metadata API and on the config
drive, if enabled.
in: body
required: false
type: string
min_version: 2.49
device_tag_nic_attachment_resp:
description: |
The device tag applied to the virtual network interface or ``null``.
in: body
required: true
type: string
min_version: 2.70
device_type:
description: |
The device type. For example, ``disk``, ``cdrom``.
in: body
required: false
type: string
device_volume_type:
description: |
The device ``volume_type``. This can be used to specify the type of volume
which the compute service will create and attach to the server.
If not specified, the block storage service will provide a default volume
type. See the `block storage volume types API <https://docs.openstack.org/api-ref/block-storage/v3/#volume-types-types>`_
for more details.
There are some restrictions on ``volume_type``:
- It can be a volume type ID or name.
- It is only supported with ``source_type`` of ``blank``, ``image`` or
``snapshot``.
- It is only supported with ``destination_type`` of ``volume``.
in: body
required: false
type: string
min_version: 2.67
# Optional input parameter in the body for PUT /os-services/{service_id} added
# in microversion 2.53.
disabled_reason_2_53_in:
description: |
The reason for disabling a service. The minimum length is 1 and the
maximum length is 255. This may only be requested with ``status=disabled``.
in: body
required: false
type: string
disabled_reason_body:
description: |
The reason for disabling a service.
in: body
required: true
type: string
disk_available_least:
description: |
The actual free disk on this hypervisor(in GiB). If allocation ratios used
for overcommit are configured, this may be negative. This is intentional as
it provides insight into the amount by which the disk is overcommitted.
in: body
required: true
type: integer
max_version: 2.87
disk_available_least_total:
description: |
The actual free disk on all hypervisors(in GiB). If allocation ratios used
for overcommit are configured, this may be negative. This is intentional as
it provides insight into the amount by which the disk is overcommitted.
in: body
required: true
type: integer
disk_bus:
description: |
Disk bus type, some hypervisors (currently only libvirt) support
specify this parameter. Some example disk_bus values can be: ``fdc``,
``ide``, ``sata``, ``scsi``, ``usb``, ``virtio``, ``xen``, ``lxc``
and ``uml``. Support for each bus type depends on the virtualization driver
and underlying hypervisor.
in: body
required: false
type: string
disk_config:
description: |
Disk configuration. The value is either:
- ``AUTO``. The API builds the server with a single partition the size of
the target flavor disk. The API automatically adjusts the file system to
fit the entire partition.
- ``MANUAL``. The API builds the server by using the partition scheme and
file system that is in the source image. If the target flavor disk is
larger, The API does not partition the remaining disk space.
in: body
required: true
type: string
disk_details_diagnostics:
description: |
The list of dictionaries with detailed information about VM disks.
Following fields are presented in each dictionary:
- ``read_bytes`` - Disk reads in bytes (Integer)
- ``read_requests`` - Read requests (Integer)
- ``write_bytes`` - Disk writes in bytes (Integer)
- ``write_requests`` - Write requests (Integer)
- ``errors_count`` - Disk errors (Integer)
in: body
required: true
type: array
min_version: 2.48
disk_over_commit:
description: |
Set to ``True`` to enable over commit when the destination host is checked for
available disk space. Set to ``False`` to disable over commit. This setting affects
only the libvirt virt driver.
in: body
required: true
type: boolean
max_version: 2.25
display_description:
description: |
The volume description.
in: body
required: true
type: string
display_description_optional:
description: |
The volume description.
in: body
required: false
type: string
display_name:
description: |
The volume name.
in: body
required: true
type: string
display_name_optional:
description: |
The volume name.
in: body
required: false
type: string
driver_diagnostics:
description: |
The driver on which the VM is running. Possible values are:
- ``libvirt``
- ``xenapi``
- ``hyperv``
- ``vmwareapi``
- ``ironic``
in: body
required: true
type: string
min_version: 2.48
ended_at:
description: |
The date and time when the server was deleted.
The date and time stamp format is as follows:
::
CCYY-MM-DDThh:mm:ss.NNNNNN
For example, ``2015-08-27T09:49:58.123456``.
If the server hasn't been deleted yet, its value is ``null``.
in: body
required: true
type: string
ended_at_optional:
description: |
The date and time when the server was deleted.
The date and time stamp format is as follows:
::
CCYY-MM-DDThh:mm:ss.NNNNNN
For example, ``2015-08-27T09:49:58.123456``.
If the server hasn't been deleted yet, its value is ``null``.
in: body
required: false
type: string
errors:
description: |
The number of errors.
in: body
required: true
type: integer
evacuate:
description: |
The action to evacuate a server to another host.
in: body
required: true
type: object
event:
description: |
The name of the event.
in: body
required: true
type: string
event_details:
min_version: 2.84
description: |
Details of the event. May be ``null``.
in: body
required: true
type: string
event_finish_time:
description: |
The date and time when the event was finished. The date and time
stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2015-08-27T09:49:58-05:00``. The ``±hh:mm``
value, if included, is the time zone as an offset from UTC. In
the previous example, the offset value is ``-05:00``.
in: body
required: true
type: string
event_host:
min_version: 2.62
description: |
The name of the host on which the event occurred.
Policy defaults enable only users with the administrative role to see
an instance action event host. Cloud providers can change these
permissions through the ``policy.json`` file.
in: body
required: false
type: string
event_hostId:
min_version: 2.62
description: |
An obfuscated hashed host ID string, or the empty string if there is no
host for the event. This is a hashed value so will not actually look like
a hostname, and is hashed with data from the project_id, so the same
physical host as seen by two different project_ids will be different.
This is useful when within the same project you need to determine if two
events occurred on the same or different physical hosts.
in: body
required: true
type: string
event_name:
description: |
The event name. A valid value is:
- ``network-changed``
- ``network-vif-plugged``
- ``network-vif-unplugged``
- ``network-vif-deleted``
- ``volume-extended`` (since microversion ``2.51``)
- ``power-update`` (since microversion ``2.76``)
- ``accelerator-request-bound`` (since microversion ``2.82``)
in: body
required: true
type: string
event_result:
description: |
The result of the event.
in: body
required: true
type: string
event_start_time:
description: |
The date and time when the event was started. The date and time
stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2015-08-27T09:49:58-05:00``. The ``±hh:mm``
value, if included, is the time zone as an offset from UTC. In
the previous example, the offset value is ``-05:00``.
in: body
required: true
type: string
event_status:
description: |
The event status. A valid value is ``failed``, ``completed``, or ``in-progress``.
Default is ``completed``.
in: body
required: false
type: string
event_tag:
description: |
A string value that identifies the event. Certain types of events require
specific tags:
- For the ``accelerator-request-bound`` event, the tag must be
the accelerator request UUID.
- For the ``power-update`` event the tag must be either be ``POWER_ON``
or ``POWER_OFF``.
- For the ``volume-extended`` event the tag must be the volume id.
in: body
required: false
type: string
event_traceback:
description: |
The traceback stack if an error occurred in this event.
Policy defaults enable only users with the administrative role to see
an instance action event traceback. Cloud providers can change these
permissions through the ``policy.json`` file.
in: body
required: true
type: string
events:
description: |
List of external events to process.
in: body
required: true
type: array
extension:
description: |
An ``extension`` object.
in: body
required: true
type: object
extension_description:
description: |
Text describing this extension's purpose.
in: body
required: true
type: string
extension_links:
description: |
Links pertaining to this extension. This is a list of dictionaries, each including
keys ``href`` and ``rel``.
in: body
required: true
type: array
extension_name:
description: |
Name of the extension.
in: body
required: true
type: string
extensions:
description: |
List of ``extension`` objects.
in: body
required: true
type: array
extra_specs:
description: |
A dictionary of the flavor's extra-specs key-and-value pairs. It appears
in the os-extra-specs' "create" REQUEST body, as well as the
os-extra-specs' "create" and "list" RESPONSE body.
in: body
required: true
type: object
extra_specs_2_47:
min_version: 2.47
description: |
A dictionary of the flavor's extra-specs key-and-value pairs. This will
only be included if the user is allowed by policy to index flavor
extra_specs.
in: body
required: false
type: object
extra_specs_2_61:
min_version: 2.61
description: |
A dictionary of the flavor's extra-specs key-and-value pairs. This will
only be included if the user is allowed by policy to index flavor
extra_specs.
in: body
required: false
type: object
fault:
description: |
A fault object. Only displayed when the server status is ``ERROR`` or
``DELETED`` and a fault occurred.
in: body
required: false
type: object
fault_code:
description: |
The error response code.
in: body
required: true
type: integer
fault_created:
description: |
The date and time when the exception was raised. The date and time
stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2015-08-27T09:49:58-05:00``. The ``±hh:mm``
value, if included, is the time zone as an offset from UTC. In
the previous example, the offset value is ``-05:00``.
in: body
required: true
type: string
fault_details:
description: |
The stack trace. It is available if the response code is not 500 or
you have the administrator privilege
in: body
required: false
type: string
fault_message:
description: |
The error message.
in: body
required: true
type: string
fixed_address:
description: |
The fixed IP address with which you want to associate the floating IP address.
in: body
required: false
type: string
fixed_ip:
description: |
A fixed IPv4 address for the NIC. Valid with a ``neutron`` or ``nova-networks``
network.
in: body
required: false
type: string
fixed_ip_address:
description: |
Fixed IP associated with floating IP network.
in: body
required: true
type: string
fixed_ip_host:
description: |
The hostname of the host that manages the server that is associated with
this fixed IP address.
in: body
required: true
type: string
fixed_ip_hostname:
description: |
The hostname of the server that is associated with this fixed IP address.
in: body
required: true
type: string
fixed_ip_obj:
description: |
A fixed IP address object.
in: body
required: true
type: object
fixed_ips:
description: |
Fixed IP addresses. If you request a specific fixed IP address without
a ``net_id``, the request returns a ``Bad Request (400)`` response code.
in: body
required: false
type: array
fixed_ips_quota:
description: |
The number of allowed fixed IP addresses for each tenant. Must be equal to or
greater than the number of allowed servers.
in: body
required: true
type: integer
max_version: 2.35
fixed_ips_quota_class: &fixed_ips_quota_class
description: |
The number of allowed fixed IP addresses for the quota class. Must be
equal to or greater than the number of allowed servers.
in: body
required: true
type: integer
max_version: 2.49
fixed_ips_quota_class_optional:
<<: *fixed_ips_quota_class
required: false
fixed_ips_quota_details:
description: |
The object of detailed fixed ips quota, including in_use, limit and
reserved number of fixed ips.
in: body
required: true
type: object
max_version: 2.35
fixed_ips_quota_optional:
description: |
The number of allowed fixed IP addresses for each tenant. Must be equal to or
greater than the number of allowed servers.
in: body
required: false
type: integer
max_version: 2.35
fixed_ips_resp:
description: |
Fixed IP addresses with subnet IDs.
in: body
required: true
type: array
flavor:
description: |
The ID and