openstack/ironic
Code Issues Proposed changes
ironic/api-ref/source/parameters.yaml
Vladyslav Drok 7d736d1697 Followup to 0335e81a8787 
This change fixes issues pointed out in the last patch set of the
referenced change request.

Apart from that, 406 error code is removed from expected error codes,
as currently .*/portgroups.* resources do not return it.

Change-Id: Ib5fccb3a4d1d2c1c7dd1095b86199536db87da4c
2016-11-17 09:47:05 +00:00

795 lines
21 KiB
YAML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# variables in header
header_version:
description: |
Specific API microversion used to generate this response.
in: header
required: true
type: string
openstack-request-id:
description: >
A unique ID for tracking the request. The request ID associated with the request
appears in the log lines for that request. By default, the middleware configuration
ensures that the request ID appears in the log files.
in: header
required: false
type: string
x-openstack-ironic-api-max-version:
description: |
Maximum API microversion supported by this endpoint, eg. "1.22"
in: header
required: true
type: string
x-openstack-ironic-api-min-version:
description: |
Minimum API microversion supported by this endpoint, eg. "1.1"
in: header
required: true
type: string
x-openstack-ironic-api-version:
description: >
A request SHOULD include this header to indicate to the Ironic API service what
version the client supports. The server will transform the response object into
compliance with the requested version, if it is supported, or return a
406 Not Supported error.
If this header is not supplied, the server will default to ``min_version``
in all responses.
in: header
required: true
type: string
# variables in path
chassis_ident:
description: |
The UUID of the chassis.
in: path
required: true
type: string
driver_ident:
description: |
The name of the driver.
in: path
required: true
type: string
node_id:
description: |
The UUID of the node.
in: path
required: false
type: string
node_ident:
description: |
The UUID or Name of the node.
in: path
required: true
type: string
port_ident:
description: |
The UUID of the port.
in: path
required: true
type: string
portgroup_ident:
description: |
The UUID or Name of the portgroup. Added in API microversion 1.23.
in: path
required: true
type: string
callback_url:
description: |
The URL of an active ironic-python-agent ramdisk, sent back to the Bare
Metal service and stored temporarily during a provisioning action.
in: query
required: true
type: string
# variables common to all query strings
fields:
description: |
One or more fields to be returned in the response.
For example, the following request returns only the ``uuid``
and ``name`` fields for each node:
::
GET /v1/nodes?fields=uuid,name
in: query
required: false
type: array
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. This value cannot be
larger than the ``max_limit`` option in the ``[api]`` section of the
configuration. If it is higher than ``max_limit``, only ``max-limit``
resources will be returned.
in: query
required: false
type: integer
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
# variables in the vendor_passthru query string
method_name:
description: |
Driver specific method name.
in: query
required: true
type: string
# variable in the lookup query string
r_addresses:
description: |
Optional list of one or more Port addresses.
in: query
required: false
type: array
# variables in the node query string
r_associated:
description: |
Filter the list of returned nodes and only return those which are, or are
not, associated with an ``instance_uuid``.
in: query
required: false
type: boolean
r_driver:
description: |
Filter the list of returned nodes, and only return those with the specified
``driver``.
in: query
required: false
type: string
r_instance_uuid:
description: |
Filter the list of returned nodes, and only return the node with this
specific instance UUID, or an empty set if not found.
in: query
required: false
type: string
r_maintenance:
description: |
Filter the list of returned nodes and only return those with
``maintenance`` set to ``True`` or ``False``.
in: query
required: false
type: boolean
# variable in the lookup query string
r_node_uuid:
description: |
Optional Node UUID.
in: query
required: false
type: string
r_port_address:
description: |
Filter the list of returned Ports, and only return the ones with the
specified physical hardware address, typically MAC, or an empty set if not
found.
in: query
required: false
type: string
r_port_node_ident:
description: |
Filter the list of returned Ports, and only return the ones associated
with this specific node (name or UUID), or an empty set if not found.
in: query
required: false
type: string
r_port_node_uuid:
description: |
Filter the list of returned Ports, and only return the ones associated
with this specific node UUID, or an empty set if not found.
in: query
required: false
type: string
r_port_portgroup_ident:
description: |
Filter the list of returned Ports, and only return the ones associated
with this specific Portgroup (name or UUID), or an empty set if not found.
Added in API microversion 1.24.
in: query
required: false
type: string
r_portgroup_address:
description: |
Filter the list of returned Portgroups, and only return the ones with the
specified physical hardware address, typically MAC, or an empty set if not
found. Added in API microversion 1.23.
in: query
required: false
type: string
r_portgroup_node_ident:
description: |
Filter the list of returned Portgroups, and only return the ones associated
with this specific node (name or UUID), or an empty set if not found.
Added in API microversion 1.23.
in: query
required: false
type: string
r_provision_state:
description: |
Filter the list of returned nodes, and only return those with the specified
``provision_state``.
in: query
required: false
type: string
r_resource_class:
description: |
Filter the list of returned nodes, and only return the ones with the
specified resource class. Introduced in API version 1.21.
in: query
required: false
type: string
sort_dir:
description: |
Sorts the response by the requested 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 server attribute that is provided as the
``sort_key``.
in: query
required: false
type: string
sort_key:
description: |
Sorts the response by the this attribute value.
Default is ``id``. 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
attribute that is provided as the ``sort_key``.
in: query
required: false
type: string
# variable returned from /lookup
agent_config:
description: |
JSON document of configuration data for the ironic-python-agent process.
in: body
required: true
type: JSON
agent_node:
description: |
JSON document containing a subset of Node fields, used by the
ironic-python-agent process as it operates on the Node.
in: body
required: true
type: JSON
# variables in the API response body
boot_device:
description: |
The boot device for a Node, eg. "pxe" or "disk".
in: body
required: true
type: string
chassis:
description: |
A ``chassis`` object.
in: body
required: true
type: array
chassis_uuid:
description: |
UUID of the chassis associated with this Node. May be empty or None.
in: body
required: true
type: string
clean_step:
description: |
The current clean step. Introduced with the cleaning feature.
in: body
required: false
type: string
clean_steps:
description: |
An ordered list of cleaning steps that will be performed on the node. A
cleaning step is a dictionary with required keys ‘interface’ and ‘step’, and
optional key ‘args’. If specified, the value for ‘args’ is a keyword variable
argument dictionary that is passed to the cleaning step method.
in: body
required: false
type: array
configdrive:
description: |
A gzip'ed and base-64 encoded config drive, to be written to a partition
on the Node's boot disk. This parameter is only accepted when setting the
state to "active".
in: body
required: false
type: string or gzip+b64 blob
console_enabled:
description: |
Indicates whether console access is enabled or disabled on this node.
in: body
required: true
type: boolean
created_at:
description: |
The UTC date and time when the resource was created,
`ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ format.
in: body
required: true
type: string
description:
description: |
Descriptive text about the Ironic service.
in: body
required: true
type: string
driver_info:
description: |
All the metadata required by the driver to manage this Node. List of fields
varies between drivers, and can be retrieved from the ``/v1/drivers/<DRIVER_NAME>/properties`` resource.
in: body
required: true
type: JSON
driver_internal_info:
description: |
Internal metadata set and stored by the Node's driver. This field is read-only.
in: body
required: false
type: JSON
driver_name:
description: |
The name of the driver.
in: body
required: true
type: string
driver_property_links:
description: |
A list of links to driver properties. Added in API microversion 1.14.
in: body
required: true
type: array
drivers:
description: |
A list of driver objects.
in: body
required: true
type: array
extra:
description: |
A set of one or more arbitrary metadata key and
value pairs.
in: body
required: true
type: object
hosts:
description: |
A list of active hosts that support this driver.
in: body
required: true
type: array
id:
description: |
Major API version, eg, "v1"
in: body
required: true
type: string
inspection_finished_at:
description: |
The UTC date and time when the last hardware inspection finished
successfully, `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ format.
May be "null".
in: body
required: true
type: string
inspection_started_at:
description: |
The UTC date and time when the hardware inspection was started,
`ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ format.
May be "null".
in: body
required: true
type: string
instance_info:
description: |
Information used to customize the deployed image. May include root partition
size, a base 64 encoded config drive, and other metadata. Note that this field
is erased automatically when the instance is deleted (this is done by requesting
the Node provision state be changed to DELETED).
in: body
required: true
type: JSON
instance_uuid:
description: |
UUID of the Nova instance associated with this Node.
in: body
required: true
type: string
internal_info:
description: |
Internal metadata set and stored by the Port. This field is read-only.
Added in API microversion 1.18.
in: body
required: true
type: JSON
last_error:
description: |
Any error from the most recent (last) transaction that started but failed to finish.
in: body
required: true
type: string
links:
description: |
A list of relative links. Includes the self and
bookmark links.
in: body
required: true
type: array
local_link_connection:
description: |
The Port binding profile. If specified, must contain ``switch_id`` (only
a MAC address or an OpenFlow based datapath_id of the switch are accepted
in this field) and ``port_id`` (identifier of the physical port on the
switch to which node's port is connected to) fields. ``switch_info`` is an
optional string field to be used to store any vendor-specific information.
Added in API microversion 1.19.
in: body
required: true
type: JSON
maintenance:
description: |
Whether or not this Node is currently in "maintenance mode". Setting a Node
into maintenance mode removes it from the available resource pool and halts
some internal automation. This can happen manually (eg, via an API request)
or automatically when Ironic detects a hardware fault that prevents communication
with the machine.
in: body
required: true
type: boolean
maintenance_reason:
description: |
User-settable description of the reason why this Node was placed into
maintenance mode
in: body
required: false
type: string
n_portgroups:
description: |
Links to the collection of portgroups on this node.
Added in API microversion 1.24.
in: body
required: true
type: array
n_ports:
description: |
Links to the collection of ports on this node
in: body
required: true
type: array
n_properties:
description: |
Physical characteristics of this Node. Populated by ironic-inspector during
inspection. May be edited via the REST API at any time.
in: body
required: true
type: JSON
n_states:
description: |
Links to the collection of states. Note that this resource is also used to
request state transitions.
in: body
required: true
type: array
name:
description: |
The name of the driver.
in: body
required: true
type: string
network_interface:
description: |
Which Network Interface provider to use when plumbing the network
connections for this Node. Added in API microversion v1.20
in: body
required: true
type: string
node_name:
description: |
Human-readable identifier for the Node resource. May be undefined. Certain
words are reserved. Added in API microversion 1.5
in: body
required: false
type: string
node_uuid:
description: |
UUID of the Node this resource belongs to.
in: body
required: true
type: string
nodes:
description: |
Links to the collection of nodes contained in
this chassis.
in: body
required: true
type: array
passthru_async:
description: |
If True the passthru function is invoked asynchronously; if False,
synchronously.
in: body
required: true
type: boolean
passthru_attach:
description: |
True if the return value will be attached to the response object, and False
if the return value will be returned in the response body.
in: body
required: true
type: boolean
passthru_description:
description: |
A description of what the method does, including any method parameters.
in: body
required: true
type: string
passthru_http_methods:
description: |
A list of HTTP methods supported by the vendor function.
in: body
required: true
type: array
persistent:
description: |
Whether the boot device should be set only for the next reboot, or
persistently.
in: body
required: true
type: boolean
pg_ports:
description: |
Links to the collection of ports belonging to this portgroup. Added in
API microversion 1.24.
in: body
required: true
type: array
port_address:
description: |
Physical hardware address of this network Port, typically the hardware
MAC address.
in: body
required: true
type: string
portgroup_address:
description: |
Physical hardware address of this Portgroup, typically the hardware
MAC address. Added in API microversion 1.23.
in: body
required: true
type: string
portgroup_internal_info:
description: |
Internal metadata set and stored by the Portgroup. This field is read-only.
Added in API microversion 1.23.
in: body
required: true
type: JSON
portgroup_name:
description: |
Human-readable identifier for the Portgroup resource. May be undefined.
Added in API microversion 1.23.
in: body
required: false
type: string
portgroup_uuid:
description: |
UUID of the Portgroup this resource belongs to. Added in API microversion 1.23.
in: body
required: true
type: string
portgroups:
description: |
A collection of Portgroup resources. Added in API microversion 1.23.
in: body
required: true
type: array
ports:
description: |
A collection of Port resources.
in: body
required: true
type: array
power_state:
description: |
The current power state of this Node. Usually, "power on" or "power off", but may be "None"
if Ironic is unable to determine the power state (eg, due to hardware failure).
in: body
required: true
type: string
properties:
description: |
A list of links to driver properties.
in: body
required: true
type: array
provision_state:
description: |
The current provisioning state of this Node.
in: body
required: true
type: string
provision_updated_at:
description: |
The UTC date and time when the resource was created,
`ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ format.
``null`` if the node is not being provisioned.
in: body
required: true
type: string
pxe_enabled:
description: |
Indicates whether PXE is enabled or disabled on the Port. Added in API
microversion 1.19.
in: body
required: true
type: boolean
r_driver_name:
description: |
The name of the driver used to manage this Node.
in: body
required: true
type: string
raid_config:
description: |
Represents the current RAID configuration of the node. Introduced with
the cleaning feature.
in: body
required: false
type: JSON
reason:
description: |
Specify the reason for setting the Node into maintenance mode.
in: body
required: false
type: string
requested_provision_state:
description: |
One of the provisioning verbs: manage, provide, inspect, clean, active,
rebuild, delete (deleted), abort.
in: body
required: true
type: string
reservation:
description: |
The ``name`` of an Ironic Conductor host which is holding a lock on this node,
if a lock is held. Usually "null", but this field can be useful for debugging.
in: body
required: true
type: string
resource_class:
description: |
A string which can be used by external schedulers to identify this Node as
a unit of a specific type of resource. This will be used by the openstack
Placement Engine in a future release. Added in API microversion 1.21.
in: body
required: true
type: string
standalone_ports_supported:
description: |
Indicates whether ports that are members of this portgroup can be
used as stand-alone ports. Added in API microversion 1.23.
in: body
required: true
type: boolean
supported_boot_devices:
description: |
List of boot devices which this Node's driver supports.
in: body
required: true
type: array
target_power_state:
description: |
If a power state transition has been requested, this field represents the
requested (ie, "target") state.
in: body
required: true
type: string
target_provision_state:
description: |
If a provisioning action has been requested, this field represents the
requested (ie, "target") state. Note that a Node may go through several
states during its transition to this target state. For instance, when requesting
an instance be deployed to an AVAILABLE Node, the Node may go through the following
state change progression: AVAILABLE -> DEPLOYING -> DEPLOYWAIT -> DEPLOYING -> ACTIVE
in: body
required: true
type: string
target_raid_config:
description: |
Represents the requested RAID configuration of the node, which will be
applied when the Node next transitions through the CLEANING state. Introduced
with the cleaning feature.
in: body
required: true
type: JSON
updated_at:
description: |
The UTC date and time when the resource was updated,
`ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ format.
May be "null".
in: body
required: true
type: string
uuid:
description: |
The UUID for the resource.
in: body
required: true
type: string
# variables returned from node-validate
v_boot:
description: |
Status of the "boot" interface
in: body
required: true
type: object
v_console:
description: |
Status of the "console" interface
in: body
required: true
type: object
v_deploy:
description: |
Status of the "deploy" interface
in: body
required: true
type: object
v_inspect:
description: |
Status of the "inspect" interface
in: body
required: true
type: object
v_management:
description: |
Status of the "management" interface
in: body
required: true
type: object
v_power:
description: |
Status of the "power" interface
in: body
required: true
type: object
v_raid:
description: |
Status of the "raid" interface
in: body
required: true
type: object
version:
description: |
Versioning of this API response, eg. "1.22".
in: body
required: true
type: string
versions:
description: |
Array of information about currently supported versions.
in: body
required: true
type: array
View Git Blame Copy Permalink