openstack/senlin
Code Issues Proposed changes
b39f22f35d
senlin/api-ref/source/parameters.yaml
tengqm 89090b6d6b Fix micro-version documentation error in api-ref 
The 'min_version' stanza only works for new parameters added instead of
applicable to new APIs introduced. This patch fixes some places where
the micro_version wasn't explicitly spelt out and other places where
the 'min_version' failed silently.

Closes-Bug: #1673311
Change-Id: Icbdeb7406d0050c33485a79f59c818adefa8d30b
2017-03-16 13:14:52 +00:00

1331 lines
30 KiB
YAML
Raw Blame History

#### header parameters #######################################################
location:
type: string
in: header
required: True
description: |
For asynchronous object operations, the ``location`` header contains a
string that can be interpreted as a relative URI from where users can
track the progress of the action triggered.
microversion:
type: string
in: header
description: |
API microversion request. It takes the form of
``OpenStack-API-Version: clustering 1.0``, where ``1.0`` is the requested
API version.
request_id:
type: string
in: header
description: |
A unique ID for tracking service request. The request ID associated
with the request by default appears in the service logs.
#### path parameters #########################################################
action_id_url:
type: string
in: path
required: True
description: |
The name or short-ID or UUID that identifies an action object.
cluster_id_url:
type: string
in: path
required: True
description: |
The name, UUID or short-UUID of a cluster object.
event_id_url:
type: string
in: path
required: True
description: |
The name, UUID or short-UUID of an event object.
node_id_url:
type: string
in: path
required: True
description: |
The name, short-ID or UUID of a node object.
path_url:
type: string
in: path
required: True
description: |
A Json path format string for node attribute.
policy_id_url:
type: string
in: path
required: True
description: |
The name, UUID or short-UUID of a policy object.
policy_type_url:
type: string
in: path
required: True
description: |
The name of a policy type.
profile_id_url:
type: string
in: path
required: True
description: |
The name, UUID or short-UUID of a profile.
profile_type_url:
type: string
in: path
required: True
description: |
The name of a profile type.
receiver_id_url:
type: string
in: path
required: True
description: |
The name, UUID or short-UUID of a receiver object.
version_url:
type: string
in: path
required: True
description: |
A string indicating the major version of Clustering API.
webhook_id_url:
type: UUID
in: path
required: True
description: |
The UUID of a webhook object.
#### query parameters ########################################################
action_action_query:
type: string
in: query
description: |
Filters the resulted list using the ``action`` field of the object.
action_name_query:
type: string
in: query
description: |
Filters the response by the action name associated with an event.
Use this filter multiple times to filter by multiple actions.
action_status_query:
type: string
in: query
description: |
Filters the results by the ``status`` property of an action object.
cluster_identity_query:
type: string
in: query
description: |
The name, short-ID or UUID of the cluster object.
enabled_query:
type: string
in: query
description: |
Filters the response by a policy enabled status on the cluster.
global_project:
type: boolean
in: query
default: False
description: |
Indicates whether to include resources for all projects or resources for
the current project in the response.
If you are an administrative user and you set this value to ``true``, the
call returns all resources from all projects. Default is ``false``, which
returns only resources in the current project.
limit:
type: integer
in: query
description: |
Requests a page size of resources. Returns a number of resources up to the
limit value. Use the `limit` parameter to make an initial limited request
and use the ID of the last-seen resource from the response as the `marker`
parameter value in a subsequent limited request.
marker:
type: UUID
in: query
description: |
The ID of the last-seen resource. Use the `limit` parameter to make an
initial limited request and use the ID of the last-seen resource from the
response as the `marker` parameter value in a subsequent limited request.
name_query:
type: string
in: query
description: |
Filters the response by the ``name`` property of the object.
oid_query:
type: string
in: query
description: |
Filters the response by the ``ID`` of object associated with an event.
Use this filter multiple times to filter by multiple objects.
oname_query:
type: string
in: query
description: |
Filters the response by the ``name`` of object associated with an event.
Use this filter multiple times to filter by multiple objects.
otype_query:
type: string
in: query
description: |
Filters the response by the ``type`` of object associated with an event.
Use this filter multiple times to filter by multiple objects. A valid
value is ``CLUSTER`` or ``NODE``.
receiver_action_query:
type: string
in: query
description: |
Filters the response by the action targeted by the receiver.
receiver_type_query:
type: string
in: query
description: |
Filters the response by the ``type`` property of the receiver.
receiver_user_query:
type: string
in: query
description: |
Filters the response by the ``user`` property of the receiver.
min_version: 1.4
show_details:
type: boolean
in: query
default: False
required: False
description: |
A boolean indicating whether the detailed information about the physical
resource associated with the node object will be returned.
sort:
type: string
in: query
description: |
Sorts the response by one or more attribute and optional sort direction
combinations. A valid direction is ``asc`` (ascending) or ``desc``
(descending). Default direction is ``asc`` (ascending).
Specify the list as ``<key>[:<direction>]``.
For example, the following query parameters in the URI sort the resources
in the response by ``name`` in ascending order and then by ``status`` in
descending order::
GET /v1/clusters?sort=name:asc,status:desc
status_query:
type: string
in: query
description: |
Filters the resource collection by the ``status`` property.
target_query:
type: string
in: query
description: |
Filters the results by the UUID of the targeted object which is usually
a cluster.
type_query:
type: string
in: query
description: |
Filters the response by the ``type`` property of the object.
user_query:
type: UUID
in: query
description: |
Filters the response by the ``user`` property of the resource.
webhook_params:
type: object
in: query
description: |
The query string that forms the inputs to use for the targeted action.
webhook_version:
type: string
in: query
description: |
The webhook implementation version requested.
#### body parameters #########################################################
action:
type: object
in: body
required: True
description: |
A structured definition of an action object.
action_action:
type: string
in: body
required: True
description: |
A string representation of the action for execution.
action_context:
type: object
in: body
required: True
description: |
A collection of key-value pairs that are used as security context when
executing the action.
action_id:
type: UUID
in: body
required: True
description: |
A UUID that uniquely identifies an action object.
action_name:
type: string
in: body
required: True
description: |
The name of an action object.
action_owner:
type: string
in: body
required: True
description: |
The UUID of the owning engine that is currently locking the action for
execution.
action_request:
type: object
in: body
required: True
description: |
A structured definition of an action to be executed. The object is
usually expressed as::
<action_name>: {
<param_1>: <value_1>
<param_2>: <value_2>
...
}
The ``<action_name>`` indicates the requested action while the ``<param>``
keys provide the associated parameters to the action. Each individual
action has its own set of parameters.
action_status:
type: string
in: body
required: True
description: |
A string representation of the current status of the action.
action_target:
type: string
in: body
required: True
description: |
The UUID of the targeted object (which is usually a cluster).
action_timeout:
type: integer
in: body
required: True
description: |
The number of seconds after which an unfinished action execution will be
treated as timeout.
actions:
type: array
in: body
required: True
description: |
A list of action objects.
adjustment_max_size:
type: integer
in: body
description: |
The value to be set as the new ``max_size`` of the cluster.
adjustment_min_size:
type: integer
in: body
description: |
The value to be set as the new ``min_size`` of the cluster.
adjustment_min_step:
type: integer
in: body
description: |
When ``adjustment_type`` is set to ``CHANGE_IN_PERCENTAGE``, often times
the computed value is a float which could be less than 1.0. The
``min_step`` can be used to specify that at least this number of nodes will
be added or removed.
adjustment_number:
type: number
in: body
description: |
The number of adjustment. The interpretation of the value depends on the
value of the ``adjustment_type`` parameter. This parameter is mandatory
when ``adjustment_type`` is specified. Otherwise, it is optional.
When ``adjustment_type`` is specified as ``CHANGE_IN_PERCENTAGE``, the
value of this parameter can be a float number, otherwise it has to be an
integer.
adjustment_strict:
type: boolean
in: body
default: False
description: |
There are cases where the computed number of nodes to adjust will break
the size constraints of a cluster, i.e. its ``min_size`` or ``max_size``
property. If this is the case, the ``strict`` parameter can further
instructs the senlin engine whether the resize should be done on a best
effort basis. If the value is set to True, senlin engine will perform the
resize operation while respecting the cluster's size constraints.
Otherwise, if the computed adjustment will break the size constraints, the
resize request will be directly rejected.
adjustment_type:
type: string
in: body
description: |
The type of size adjustment. The valid values are:
- ``EXACT_CAPACITY``: The adjustment number specified is to be interpreted
as the targeted ``desired_capacity``. This value has to be a non-negative
integer.
- ``CHANGE_IN_CAPACITY``: The adjustment number specified is to be treated
as the number of nodes to add or remove. The value has to be a non-zero
integer. A positive number can be used to specify the number of nodes to
add while a negative number can be specified to indicate the number of
nodes to remove.
- ``CHANGE_IN_PERCENTAGE``: The adjustment number will be interpreted as
a percentile relative to a cluster's current ``desired_capacity``. The
adjustment number can be a positive or negative float value.
This parameter is optional when a resize request is only about changing the
``min_size`` and/or ``max_size`` of the cluster. Otherwise, it is required.
When this parameter is specified, the ``number`` parameter has to be
provided as well.
attr_value:
type: object
in: body
description: |
The attribute value on a specific node. The value could be of any data
type that is valid for the attribute.
build_info:
type: object
in: body
required: True
description: |
Build information for a Senlin deployment.
build_info_api:
type: object
in: body
required: True
description: |
Revision information of Senlin API service.
build_info_engine:
type: object
in: body
required: True
description: |
Revision information of Senlin engine service.
cause:
type: string
in: body
required: True
description: |
An explanation why an action was started.
check_params:
type: object
in: body
description: |
The optional parameters provided to a cluster check operation. The detailed
keys and values are not checked at the moment.
cluster:
type: object
in: body
required: True
description: |
The structured definition of a cluster object.
cluster_attributes:
type: array
in: body
required: True
description: |
A list of dictionaries each containing the node ID and the corresponding
attribute value.
cluster_data:
type: object
in: body
required: True
description: |
The structured data associated with the cluster.
cluster_id:
type: UUID
in: body
required: True
description: |
The UUID of the cluster object.
cluster_member_nodes:
type: array
in: body
required: True
description: |
The candidate nodes to be added to or removed from a cluster. The meaning
of the parameter is depended on the action requested.
Each item in the list can be the name, the short-ID or the UUID of a node.
cluster_name:
type: string
in: body
required: True
description: |
The name of the cluster object.
cluster_nodes:
type: array
in: body
required: True
description: |
A list of the UUIDs of node objects which are members of the current
cluster.
cluster_operation_request:
type: object
in: body
required: True
description: |
A structured definition of an operation to be performed. The object is
usually expressed as::
<operation_name>: {
filters: {
<cond_1>: <var_1>,
<cond_2>: <var_2>
}
params: {
<param_1>: <value_1>,
<param_2>: <value_2>
...
}
}
The ``<operation_name>`` specifies the operation to be performed, in which
the ``filters`` object contains a collection of filtering rules, and the
``params`` object provide the parameters (if any) to the operation.
Each individual operation has its own set of parameters, as supported by
the profile type of the target cluster.
cluster_policies:
type: array
in: body
required: True
description: |
A list of cluster_policy objects.
cluster_policies_property:
type: array
in: body
required: True
description: |
A list of UUIDs of the policies attached to current cluster.
cluster_policy:
type: object
in: body
required: True
description: |
The structured description of a cluster_policy object.
cluster_policy_enabled:
type: boolean
in: body
required: True
description: |
Whether the policy is enabled on the attached cluster.
cluster_policy_id:
type: UUID
in: body
required: True
description: |
The UUID of a cluster_policy object.
cluster_replace_nodes:
type: object
in: body
required: True
description: |
A collection of key-value pairs. Each key is the node to be replaced of a
cluster, each value is the node used to replace the original one.
Each item in of the key-value pairs can be the name, the short-ID or the
UUID of a node.
cluster_status:
type: string
in: body
required: True
description: |
The string representation of the current status of the cluster.
clusters:
type: array
in: body
required: True
description: |
A list of cluster objects.
created_at:
type: string
in: body
required: True
description: |
The date and time when the object was created. The date and time stamp
format is ISO8601: ``CCYY-MM-DDThh:mm:ssZ``. For example:
``2016-01-18T00:00:00Z``
depended_by:
type: array
in: body
required: True
description: |
A list of UUIDs of the actions that depend on the current action.
depends_on:
type: array
in: body
required: True
description: |
A list of UUIDs of the actions that the current action depends on.
desired_capacity:
type: integer
in: body
required: True
description: |
The desired capacity of a cluster. When creating a cluster, this value is
set to 0 by default.
destroy_after_deletion:
type: boolean
in: body
required: False
description: |
Whether deleted nodes to be destroyed right away.
min_version: 1.4
domain:
type: UUID
in: body
required: True
description: |
The ID of the domain a resource is created in.
end_time:
type: float
in: body
required: True
description: |
A floating point number that represents when an action's execution has
completed.
event:
type: object
in: body
required: True
description: |
The structured description of an event object.
event_id:
type: UUID
in: body
required: True
description: |
The UUID of an event object.
event_level:
type: string
in: body
required: True
description: |
The level of an event object.
event_status:
type: string
in: body
required: True
description: |
The current status of the object associated with the event.
event_timestamp:
type: string
in: body
required: True
description: |
The date and time when the event was generated. The date and time stamp
format is ISO8601: ``CCYY-MM-DDThh:mm:ssZ``.
events:
type: array
in: body
required: True
description: |
A list of event objects.
index:
type: integer
in: body
required: True
description: |
An integer that uniquely identifies a node within its owning cluster.
init_at:
type: string
in: body
required: True
description: |
The date and time when the object was initialized. The date and
time stamp format is ISO8601: ``CCYY-MM-DDThh:mm:ssZ``. For example:
``2016-01-18T00:00:00Z``
inputs:
type: object
in: body
required: True
description: |
A collection of key-value pairs that are fed to the action as input
parameters.
interval:
type: integer
in: body
required: True
description: |
An integer that indicates the interval in seconds between two consecutive
executions of a repeatable action.
max_size:
type: integer
in: body
required: True
description: |
The maximum size of a cluster, i.e. the maximum number of nodes that can
be members of the cluster. A value of -1 means that the cluster doesn't
have an upper bound regarding the number of member nodes.
max_size_req:
type: integer
default: -1
in: body
required: False
description: |
The maximum size of a cluster, i.e. the maximum number of nodes that can
be members of the cluster. A value of -1 means that the cluster doesn't
have an upper bound regarding the number of member nodes.
metadata:
type: object
in: body
required: True
description: |
A collection of key-value pairs associated with an object.
metadata_req:
type: object
in: body
description: |
A collection of key-value pairs associated with an object.
min_size:
type: integer
in: body
required: True
description: |
The minimum size of a cluster, i.e. the minimum number of nodes that can
be members of the cluster.
min_size_req:
type: integer
default: 0
in: body
required: False
description: |
The minimum size of a cluster, i.e. the minimum number of nodes that can
be members of the cluster.
name:
type: string
in: body
required: True
description:
The name of the object in question.
name_req:
type: string
in: body
required: False
description:
The new name of the object in question.
node:
type: object
in: body
required: True
description: |
A structured description of a node object.
node_cluster_identity:
type: string
in: body
required: False
description: |
The name, short-ID or UUID of the cluster object a node belongs to.
node_data:
type: object
in: body
required: True
description: |
A map containing key-value pairs associated with a node object.
node_id:
type: UUID
in: body
required: True
description: |
A UUID string that uniquely identifies a node object.
node_status:
type: string
in: body
required: True
description: |
The string representation of the current status of the node object.
nodes:
type: array
in: body
required: True
description: |
A list of node objects.
oid:
type: UUID
in: body
required: True
description: |
The UUID of an object associated with the event.
oname:
type: string
in: body
required: True
description: |
The name of an object associated with the event.
operation_request:
type: object
in: body
required: True
description: |
A structured definition of an operation to be performed. The object is
usually expressed as::
<operation_name>: {
<param_1>: <value_1>
<param_2>: <value_2>
...
}
The ``<operation_name>`` specifies the operation to be performed while the
``<param_n>`` keys provide the parameters (if any) to the operation. Each
individual operation has its own set of parameters, as supported by the
profile type of the target cluster or node.
operations:
type: object
in: body
required: True
description: |
A dictionary containing the description of operations (and parameters)
supported by a profile type.
otype:
type: string
in: body
required: True
description: |
The type of an object associated with the event.
outputs:
type: object
in: body
required: True
description: |
A collection of key-value pairs that were produced during the execution of
an action as its outputs.
physical_id:
type: UUID
in: body
required: True
description: |
The UUID of the physical resource represented by the node object.
policies:
type: array
in: body
required: True
description: |
A list of policy objects.
policy:
type: object
in: body
required: True
description: |
A structured description of a policy object.
policy_data:
type: object
in: body
required: True
description: |
A structured representation of data associated with a policy object.
policy_id:
type: UUID
in: body
required: True
description: |
The UUID of a policy object.
policy_identity:
type: string
in: body
required: True
description: |
The name, UUID or short-UUID of a policy object.
policy_name:
type: string
in: body
required: True
description: |
The name of a policy object.
policy_spec:
type: object
in: body
required: True
description: |
The detailed specification of a policy object.
policy_type:
type: object
in: body
required: True
description: |
A structured description of a policy type. Since API micro-version 1.5,
a "support_status" property is returned which contains a list
of support status changes.
policy_type_name:
type: string
in: body
required: True
description: |
The name of the policy type.
policy_type_schema:
type: object
in: body
required: True
description: |
The schema of a policy type. The schema of a policy type varies a lot
based on the specific type implementation.
policy_types:
type: array
in: body
required: True
description: |
A list of policy_type objects. Since API micro-version 1.5, each record
in the list will have a "support_status" property which contains a list
of support status changes.
profile:
type: object
in: body
required: True
description: |
A structured description of a profile object.
profile_id:
type: UUID
in: body
required: True
description: |
The UUID of the profile.
profile_identity:
type: string
in: body
required: False
description: |
The name, short-ID, or UUID of a profile.
profile_identity_req:
type: string
in: body
required: True
description: |
The name, short-ID, or UUID of a profile.
profile_name:
type: string
in: body
required: True
description: |
The name of the profile.
profile_only:
type: boolean
in: body
required: False
description: |
Whether the update of profile is limited to the target cluster. All nodes
in the cluster will be updated with the specified new profile if this
parameter is set to False. The default value is False.
min_version: 1.6
profile_spec:
type: object
in: body
required: True
description: |
The detailed specification of the profile.
profile_type:
type: object
in: body
required: True
description: |
A structured description of a profile type. Since API micro-version 1.5,
a "support_status" property is returned which contains a list
of support status changes.
profile_type_name:
type: string
in: body
required: True
description: |
The name of the profile type.
profile_type_schema:
type: object
in: body
required: True
description: |
The schema of a profile type. The schema of a profile type varies
a lot based on the specific type implementation. All profile types
share the ``context`` property which is a dictionary for customizing
the request context to authenticate with a backend service. A common
usage of this property is to set the ``region_name`` in the dictionary
so that a node can be created in the specified region. All other
properties are defined by a particular profile type implementation.
profile_types:
type: array
in: body
required: True
description: |
A list of profile_type objects. Since API micro-version 1.5, each record
in the list will have a "support_status" property which contains a list
of support status changes.
profiles:
type: array
in: body
required: True
description: |
A list for profile objects.
project:
type: UUID
in: body
required: True
description: |
The ID of the project a resource is created in.
receiver:
type: object
in: body
required: True
description: |
The structured definition of a receiver object.
receiver_action:
type: string
in: body
description: |
The action to initiate when the receiver is triggered. A valid value
should be the name of an action that can be applied on a cluster.
receiver_actor:
type: object
in: body
required: False
description: |
A map of key and value pairs to use for authentication.
receiver_channel:
type: object
in: body
required: True
description: |
The target to be used by user to trigger a receiver. For webhook type
of receiver, channel is a webhook URL.
receiver_cluster_identity:
type: string
in: body
description: |
The name, short-ID or UUID of the cluster object a node belongs to.
receiver_id:
type: UUID
in: body
required: True
description: |
The UUID of the receiver object.
receiver_params:
type: object
in: body
required: True
description: |
A map of key and value pairs to use for action creation.
receiver_params_req:
type: object
in: body
required: False
description: |
A map of key and value pairs to use for action creation. Some actions
might require certain input parameters.
receiver_type:
type: string
in: body
required: True
description: |
The type of the receiver.
receiver_type_req:
type: string
in: body
required: True
description: |
The type of the receiver. The valid values include ``webhook`` and
``message``.
receivers:
type: array
in: body
required: True
description: |
A list for receiver objects.
recover_params:
type: object
in: body
description: |
The optional parameters provided to a cluster recover operation. The
detailed keys and values are not checked at the moment.
role:
type: string
in: body
required: True
description: |
A string describing the role played by a node inside a cluster.
role_req:
type: string
in: body
description: |
A string describing the new role played by a node inside a cluster.
scale_count:
type: integer
in: body
default: 1
description: |
The number of new nodes to add to or remove from the specified cluster.
The interpretation is depending on the action requested. Default value is
1.
start_time:
type: float
in: body
required: True
description: |
A floating point number that represents the time when an action started
execution.
status_reason:
type: string
in: body
required: True
description: |
The string representation of the reason why the object has transited to
its current status.
timeout:
type: integer
in: body
required: True
description: |
The default timeout value (in seconds) of cluster operations.
timeout_req:
type: integer
in: body
required: False
description: |
The new timeout value (in seconds) of cluster operations.
updated_at:
type: string
in: body
required: True
description: |
The date and time when the object was last updated. The date and time
stamp format is ISO8601: ``CCYY-MM-DDThh:mm:ssZ``. For example:
``2016-01-18T00:00:00Z``
user:
type: UUID
in: body
required: True
description: |
The ID of the user an object is created by.
version:
type: object
in: body
required: True
description: |
The details about a major API version.
version_id:
type: string
in: body
required: True
description: |
The string representation of an API version number, e.g. ``1.0``.
version_links:
type: array
in: body
required: True
description: |
A list of relative URLs to different version objects.
version_max_version:
type: string
in: body
required: True
description: |
The string representation of the maximum microversion supported.
version_media_types:
type: array
in: body
required: True
description: |
A list of content-type based media type request supported.
version_min_version:
type: string
in: body
required: True
description: |
The string representation of the minimum microversion supported.
version_status:
type: string
in: body
required: True
description: |
A string indicating the supporting status of the version.
version_updated:
type: string
in: body
required: True
description: |
The date and time when the version was last updated. The date and time
stamp format is ISO8601: ``CCYY-MM-DDThh:mm:ssZ``. For example:
``2016-01-18T00:00:00Z``
versions:
type: array
in: body
required: True
description: |
A list of supported major API versions.
View Git Blame Copy Permalink