openstack/nova
Code Issues Proposed changes

Add sample API content

Browse Source 
This adds sample API content for versions and servers resources,
including the parameters.yaml that is needed in both of these cases.

It also makes a new tox.ini target 'api-ref' for building these docs,
which will be used as part of the publishing pipeline.

Change-Id: I310ed352dc5dd81d01f2fd5f1a2fab662c29f0dc
This commit is contained in:
Sean Dague
2016-03-29 11:56:21 -04:00
parent 68ec070645
commit 329898ffbc
5 changed files with 1309 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
api-ref/source/index.rst Normal file
View File

@@ -0,0 +1,8 @@
:tocdepth: 2
=============
Compute API
=============
.. include:: versions.rst
.. include:: servers.rst

609
api-ref/source/parameters.yaml Normal file
View File

@@ -0,0 +1,609 @@
tenant_id:
type: UUID
in: URI
description: |
The UUID of the tenant in a multi-tenancy cloud.
changes-since:
type: dateTime
in: query
optional: True
description: |
Only return servers that have changed in status since the specified time
image:
type: UUID
in: query
optional: True
description: |
Filters the response by an image, as a UUID.
flavor:
type: UUID
in: query
optional: True
description: |
Filters the response by a flavor, as a UUID. A flavor is a
combination of memory, disk size, and CPUs.
name:
type: regexp
in: query
optional: True
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.
status:
type: ServerStatus
in: query
optional: True
description: |
Filters the response by a server status, as a string. For example, ACTIVE.
host:
type: string
in: query
optional: True
description: |
Filters the response by a host name, as a string. This query
parameter is typically available to only administrative
users. If you are a non-administrative user, the API ignores
this parameter.
limit:
type: int
in: query
optional: True
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.
marker:
type: string
in: query
optional: True
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.
request_id:
type: UUID
in: header
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.
servers:
type: list
in: body
description: |
A list of servers objects that match the critera above. If no
additional filters are added will be all non ``DELETED`` servers
for the project of the user making the request.
server_id:
type: UUID
in: body
description: |
The UUID of a server. Useful for follow on calls.
server_id_url:
type: UUID
in: URL
description: |
The UUID of a server.
generic_links:
type: list
in: body
description: |
A list of uris that reference the resource in question.
server_name:
type: string
in: body
description: |
The display name of the server
server:
type: object
in: body
description: |
A structured description of the server.
security_groups:
in: body
optional: True
type: string
description: |
One or more security groups. Specify the name of the security
group in the name attribute. If you omit this attribute, the API
creates the server in the default security group.
user_data:
in: body
optional: True
type: string
description: |
Configuration information or scripts to use upon launch. Must be Base64 encoded.
availability_zone:
in: body
optional: True
type: string
description: |
The availability zone from which to launch the server. When you
provision resources, you specify from which availability zone you
want your instance to be built.
Typically, you use availability zones to arrange OpenStack compute
hosts into logical groups. An availability zone provides a form of
physical isolation and redundancy from other availability
zones. For instance, if some racks in your data center are on a
separate power source, you can put servers in those racks in their
own availability zone. Availability zones can also help separate
different classes of hardware.
By segregating resources into availability zones, you can ensure
that your application resources are spread across disparate
machines to achieve high availability in the event of hardware or
other failure.
image_ref:
in: body
type: string
description: |
The image reference, as a ``UUID`` or full URL, for the image to
use for your server instance.
flavor_ref:
in: body
type: string
description: |
The flavor reference, as a ``UUID`` or full URL, for the flavor
for your server instance.
network_obj:
in: body
type: object
optional: True
description: |
A networks object. Required parameter when there are mulitple
networks defined for the tenant. When you do not specify the
networks parameter, the server attaches to the only network
created for the current tenant.
Optionally, you can create one or more NICs on the server.
To provision the server instance with a NIC for a network, specify
the UUID of the network in the uuid attribute in a networks
object.
To provision the server instance with a NIC for an already
existing port, specify the port-id in the port attribute in a
networks object.
fixed_ip:
in: body
type: string
optional: True
description: |
A fixed IPv4 address for the NIC. Valid with a neutron or
nova-networks network.
metadata:
in: body
type: object
optional: True
description: |
Metadata key and value pairs. The maximum size of the metadata
key and value is 255 bytes each.
personality:
in: body
type: string
optional: True
description: |
The file path and contents, text only, to inject into the server
at launch. The maximum size of the file path data is 255
bytes. The maximum limit is The number of allowed bytes in the
decoded, rather than encoded, data.
block_device_mapping_v2:
in: body
type: object
optional: True
description: |
Enables you to boot a server from a volume when you specify
additional parameters. If you specify the volume status, you must
set it to available. In the OpenStack Block Storage database, the
volume ``attach_status`` must be ``detached``.
bdm_device_name:
in: block_device_mapping_v2
type: string
description: |
A path to the device for the volume that you want to use to boot the server.
bdm_source_type:
in: block_device_mapping_v2
type: string
description: |
The source type of the volume. A valid value is blank, snapshot, volume, or image.
bdm_destination_type:
in: block_device_mapping_v2
type: string
optional: True
description: |
Defines where the volume comes from. A valid value is local or volume.
bdm_delete_on_termination:
in: block_device_mapping_v2
type: boolean
description: |
To delete the boot volume when the server is destroyed, specify
``true``. Otherwise, specify ``false``.
bdm_guest_format:
in: block_device_mapping_v2
type: string
description: |
Specifies the guest server disk file system format, such as ephemeral or swap.
bdm_boot_index:
in: block_device_mapping_v2
type: int
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.
config_drive:
in: body
type: boolean
optional: True
description: |
Indicates whether a configuration 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.
keypair_name:
in: body
type: string
optional: True
description: |
Key pair name.
scheduler_hints:
in: body
type: object
optional: True
description: |
The dictionary of data to send to the
scheduler. Alternatively, you can specify
OS-SCH-HNT:scheduler_hints as the string.
server_disk_config:
in: body
type: string
optional: True
description: |
Controls how the API partitions the disk when you create,
rebuild, or resize servers. A server inherits the
OS-DCF:diskConfig value from the image from which it was
created, and an image inherits the OS-DCF:diskConfig value
from the server from which it was created. To override the
inherited setting, you can include this attribute in the
request body of a server create, rebuild, or resize request.
If the OS-DCF:diskConfig value for an image is ``MANUAL``, you
cannot create a server from that image and set its
OS-DCF:diskConfig value to ``AUTO``.
A valid value is:
``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 whatever
partition scheme and file system is in the source image. If the
target flavor disk is larger, the API does not partition the
remaining disk space.
admin_pass:
in: body
type: string
description: |
The administrative password of the server.
server_addresses:
type: object
in: body
description: |
The addresses for the server.
Addresses information is hidden for any server in a state set
in the ``osapi_hide_server_address_states`` configuration
option. By default, servers in building state hide their
addresses information.
See nova.conf - configuration options.
created:
type: string
in: body
description: |
The date and time when the resource was created.
The date and time stamp format is 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.
flavor_obj:
type: object
in: body
description: |
The ID and links for the flavor for your server instance. A
flavor is a combination of memory, disk size, and CPUs.
image_obj:
type: object
in: body
description: |
The UUID and links for the image for your server instance. The
image object might be an empty string when you boot the server
from a volume.
hostId:
type: string
in: body
description: |
The ID of the host. This is a hashed value which will be the
same if 2 instances are on the same physical host.
server_compute_hostname:
type: string
in: body
admin_only: True
description: |
The host name. Appears in the response for administrative users only.
server_hypervisor_hostname:
type: string
in: body
admin_only: True
description: |
The hypervisor host name. Appears in the response for administrative users only.
server_instance_name:
type: string
in: body
admin_only: True
description: |
The instance name. The Compute API generates the instance name
from the instance name template. Appears in the response for
administrative users only.
server_power_state:
type: string
in: body
description: |
The power state of the instance.
server_task_state:
type: string
in: body
description: |
The task state of the instance.
server_vm_state:
type: string
in: body
description: |
The VM state.
server_volumes_attached:
type: object
in: body
description: |
The attached volumes, if any.
server_launched_at:
type: string
in: body
description: |
The date and time when the server was launched.
The date and time stamp format is 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.
If the ``deleted_at`` date and time stamp is not set, its value is null.
server_terminated_at:
type: string
in: body
description: |
The date and time when the server was deleted.
The date and time stamp format is 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.
If the deleted_at date and time stamp is not set, its value is null.
build_progress:
type: int
in: body
description: |
A percentage value of the build progress.
security_groups_obj:
type: object
in: body
description: |
Security groups object.
sg_description:
type: string
in: security_groups
description: |
The security group description.
sg_id:
type: string
in: security_groups
description: |
The security group ID.
sg_name:
type: string
in: security_groups
description: |
The security group name.
sg_rules:
type: object
in: security_groups
description: |
A rules object.
server_status:
type: string
in: body
description: |
The server status.
tenant_id_body:
type: UUID
in: body
description: |
The ``UUID`` of the tenant in a multi-tenancy cloud.
updated:
type: string
in: body
description: |
The date and time when the resource was updated.
The date and time stamp format is ISO 8601:
CCYY-MM-DDThh:mm:ss±hh:mm
The ±hh:mm value, if included, is the time zone as an offset from UTC.
For example, 2015-08-27T09:49:58-05:00.
The UTC time zone is assumed.
user_id:
type: UUID
in: body
description: |
The user ID of the user who owns the server.
# parameters in microversions only
server_locked:
type: boolean
in: body
min_version: 2.9
description: |
Whether or not a server has been ``locked``. Locked servers
prevent most actions from being performed on them.
host_status:
type: string
in: body
min_version: 2.16
description: |
The host status. Values where next value in list can override
the previous:
``UP`` if nova-compute up.
``UNKNOWN`` if nova-compute not reported by servicegroup driver.
``DOWN`` if nova-compute forced down.
``MAINTENANCE`` if nova-compute is disabled.
Empty string indicates there is no host for server.
This attribute appears in the response only if the policy permits.
server_description:
type: string
in: body
min_version: 2.19
description: |
A free form description field for the server. It is limitted to
``255`` characters in length.

624
api-ref/source/servers.rst Normal file
View File

@@ -0,0 +1,624 @@
===================
Servers (servers)
===================
Lists, creates, shows details for, updates, and deletes servers.
Concepts
========
Passwords
---------
When you create a server, you can specify a password through the
optional adminPass attribute. The password must meet the complexity
requirements set by your OpenStack Compute provider. The server might
enter an ERROR state if the complexity requirements are not met. In
this case, a client might issue a change password action to reset the
server password.
If you do not specify a password, the API generates and assigns a
random password that it returns in the response object. This password
meets the security requirements set by the compute provider. For
security reasons, subsequent GET calls do not require this password.
Server metadata
---------------
You can specify custom server metadata at server launch time. The
maximum size for each metadata key-value pair is 255 bytes. The
compute provider determines the maximum number of key-value pairs for
each server. You can query this value through the maxServerMeta
absolute limit.
Server networks
---------------
You can specify one or more networks to which the server connects at
launch time. Users can also specify a specific port on the network or
the fixed IP address to assign to the server interface.
You can use both IPv4 and IPv6 addresses as access addresses and you
can assign both addresses simultaneously. You can update access
addresses after you create a server.
Server personality
------------------
To customize the personality of a server instance, you can inject data
into its file system. For example, you might insert ssh keys, set
configuration files, or store data that you want to retrieve from
inside the instance. This customization method provides minimal
launch-time personalization. If you require significant customization,
create a custom image.
Follow these guidelines when you inject files:
The maximum size of the file path data is 255 bytes.
Encode the file contents as a Base64 string. The compute provider
determines the maximum size of the file contents. The image that you
use to create the server determines this value.
The maximum limit refers to the number of bytes in the decoded data
and not to the number of characters in the encoded data.
The maxPersonality absolute limit defines the maximum number of file
path and content pairs that you can supply. The compute provider
determines this value.
The maxPersonalitySize absolute limit is a byte limit that applies to
all images in the deployment. Providers can set additional per-image
personality limits.
The file injection might not occur until after the server builds and
boots.
After file injection, only system administrators can access
personality files. For example, on Linux, all files have root as the
owner and the root group as the group owner, and allow only user and
group read access (chmod 440).
Server access addresses
-----------------------
In a hybrid environment, the underlying implementation might not
control the IP address of a server. Instead, the access IP address
might be part of the dedicated hardware; for example, a router/NAT
device. In this case, you cannot use the addresses that the
implementation provides to access the server from outside the local
LAN. Instead, the API might assign a separate access address at
creation time to provide access to the server. This address might not
be directly bound to a network interface on the server and might not
necessarily appear when you query the server addresses. However,
clients should use an access address to access the server directly.
List servers - Lists IDs, names, and links for all servers.
===========================================================
.. rest_method:: GET /v2.1/{tenant_id}/servers
Servers contain a status attribute that indicates the current server
state. You can filter on the server status when you complete a list
servers request. The server status is returned in the response
body. The possible server status values are:
- ``ACTIVE``. The server is active.
- ``BUILDING``. The server has not finished the original build process.
- ``DELETED``. The server is permanently deleted.
- ``ERROR``. The server is in error.
- ``HARD_REBOOT``. The server is hard rebooting. This is equivalent to
pulling the power plug on a physical server, plugging it back in,
and rebooting it.
- ``MIGRATING``. The server is being migrated to a new host.
- ``PASSWORD``. The password is being reset on the server.
- ``PAUSED``. In a paused state, the state of the server is stored in
RAM. A paused server continues to run in frozen state.
- ``REBOOT``. The server is in a soft reboot state. A reboot command
was passed to the operating system.
- ``REBUILD``. The server is currently being rebuilt from an image.
- ``RESCUED``. The server is in rescue mode. A rescue image is running
with the original server image attached.
- ``RESIZED``. Server is performing the differential copy of data that
changed during its initial copy. Server is down for this stage.
- ``REVERT_RESIZE``. The resize or migration of a server failed for
some reason. The destination server is being cleaned up and the
original source server is restarting.
- ``SOFT_DELETED``. The server is marked as deleted but the disk
images are still available to restore.
- ``STOPPED``. The server is powered off and the disk image still
persists.
- ``SUSPENDED``. The server is suspended, either by request or
necessity. This status appears for only the XenServer/XCP, KVM, and
ESXi hypervisors. Administrative users can suspend an instance if it
is infrequently used or to perform system maintenance. When you
suspend an instance, its VM state is stored on disk, all memory is
written to disk, and the virtual machine is stopped. Suspending an
instance is similar to placing a device in hibernation; memory and
vCPUs become available to create other instances.
- ``UNKNOWN``. The state of the server is unknown. Contact your cloud
provider.
- ``VERIFY_RESIZE``. System is awaiting confirmation that the server
is operational after a move or resize.
Normal response codes: 200
Error response codes: computeFault (400, 500, …), serviceUnavailable
(503), badRequest (400), unauthorized (401), forbidden (403),
badMethod (405)
Request parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- changes-since: changes-since
- image: image
- flavor: flavor
- name: name
- status: status
- host: host
- limit: limit
- marker: marker
Response Example
----------------
.. literalinclude:: /../../doc/api_samples/servers/servers-list-resp.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- x-openstack-request-id: request_id
- servers: servers
- id: server_id
- links: generic_links
- name: server_name
Create server
=============
.. rest_method:: POST /v2.1/{tenant_id}/servers
The progress of this operation depends on the location of the
requested image, network I/O, host load, selected flavor, and other
factors.
To check the progress of the request, make a GET /servers/{id}
request. This call returns a progress attribute, which is a percentage
value from 0 to 100.
The Location header returns the full URL to the newly created server
and is available as a self and bookmark link in the server
representation.
When you create a server, the response shows only the server ID, its
links, and the admin password. You can get additional attributes
through subsequent GET requests on the server.
Include the block-device-mapping-v2 parameter in the create request
body to boot a server from a volume.
Include the key_name parameter in the create request body to add a
keypair to the server when you create it. To create a keypair, make a
create keypair request.
Preconditions
-------------
The user must have sufficient server quota to create the number of
servers requested.
The connection to the Image service is valid.
Asynchronous postconditions
---------------------------
With correct permissions, you can see the server status as ACTIVE
through API calls.
With correct access, you can see the created server in the compute
node that OpenStack Compute manages.
Troubleshooting
---------------
If the server status remains BUILDING or shows another error status,
the request failed. Ensure you meet the preconditions then investigate
the compute node.
The server is not created in the compute node that OpenStack Compute
manages.
The compute node needs enough free resource to match the resource of
the server creation request.
Ensure that the scheduler selection filter can fulfill the request
with the available compute nodes that match the selection criteria of
the filter.
Normal response codes: 202
Error response codes: computeFault (400, 500, …), serviceUnavailable
(503), badRequest (400), unauthorized (401), forbidden (403),
badMethod (405), itemNotFound (404)
Request Example
---------------
.. literalinclude:: /../../doc/api_samples/servers/server-create-req.json
:language: javascript
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- server: server
- security_groups: security_groups
- user_data: user_data
- os-availability-zone:availability_zone: availability_zone
- imageRef: image_ref
- flavorRef: flavor_ref
- networks: network_obj
- name: server_name
- fixed_ip: fixed_ip
- metadata: metadata
- personality: personality
- block_device_mapping_v2: block_device_mapping_v2
- device_name: bdm_device_name
- source_type: bdm_source_type
- destination_type: bdm_destination_type
- delete_on_termination: bdm_delete_on_termination
- guest_format: bdm_guest_format
- boot_index: bdm_boot_index
- config_drive: config_drive
- key_name: keypair_name
- os:scheduler_hints: scheduler_hints
- OS-DCF:diskConfig: server_disk_config
Response Example
----------------
.. literalinclude:: /../../doc/api_samples/servers/server-create-resp.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- x-openstack-request-id: request_id
- server: server
- adminPass: admin_pass
- name: server_name
- security_groups: security_groups
- id: server_id
- links: generic_links
List Servers Detailed
=====================
.. rest_method:: GET /v2.1/​{tenant_id}​/servers/detail
The compute provisioning algorithm has an anti-affinity property that
attempts to spread customer VMs across hosts. Under certain
situations, VMs from the same customer might be placed on the same
host. The hostId property shows the host that your server runs on and
can be used to determine this scenario if it is relevant to your
application.
For each server, shows server details including configuration drive,
extended status, and server usage information.
The extended status information appears in the OS-EXT-STS:vm_state,
OS-EXT-STS:power_state, and OS-EXT-STS:task_state attributes.
The server usage information appears in the OS-SRV-USG:launched_at and
OS-SRV-USG:terminated_at attributes.
To hide addresses information for instances in a certain state, set
the osapi_hide_server_address_states configuration option. Set this
option to a valid VM state in the nova.conf configuration file.
HostId is unique per account and is not globally unique.
Normal response codes: 200
Error response codes: computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405)
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- changes-since: changes-since
- image: image
- flavor: flavor
- name: name
- status: status
- host: host
- limit: limit
- marker: marker
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- servers: servers
- addresses: server_addresses
- created: created
- flavor: flavor_obj
- hostId: hostId
- id: server_id
- image: image_obj
- key_name: keypair_name
- links: generic_links
- metadata: metadata
- name: server_name
- OS-DCF:diskConfig: server_disk_config
- OS-EXT-AZ:availability_zone: availability_zone
- OS-EXT-SRV-ATTR:host: server_compute_hostname
- OS-EXT-SRV-ATTR:hypervisor_hostname: server_hypervisor_hostname
- OS-EXT-SRV-ATTR:instance_name: server_instance_name
- OS-EXT-STS:power_state: server_power_state
- OS-EXT-STS:task_state: server_task_state
- OS-EXT-STS:vm_state: server_vm_state
- os-extended-volumes:volumes_attached: server_volumes_attached
- OS-SRV-USG:launched_at: server_launched_at
- OS-SRV-USG:terminated_at: server_terminated_at
- progress: build_progress
- security_groups: security_groups_obj
- description: sg_description
- id: sg_id
- name: sg_name
- rules: sg_rules
- status: server_status
- tenant_id: tenant_id_body
- updated: updated
- user_id: user_id
- locked: server_locked
- host_status: host_status
- description: server_description
Example Response
----------------
.. literalinclude:: /../../doc/api_samples/servers/servers-details-resp.json
:language: javascript
Show Server Details
===================
.. rest_method:: GET /v2.1/​{tenant_id}​/servers/{server_id}
Includes server details including configuration drive, extended
status, and server usage information.
The extended status information appears in the ``OS-EXT-STS:vm_state``,
``OS-EXT-STS:power_state``, and ``OS-EXT-STS:task_state`` attributes.
The server usage information appears in the ``OS-SRV-USG:launched_at``
and ``OS-SRV-USG:terminated_at`` attributes.
To hide addresses information for instances in a certain state, set
the osapi_hide_server_address_states configuration option. Set this
option to a valid VM state in the nova.conf configuration file.
HostId is unique per account and is not globally unique.
Preconditions
-------------
The server must exist.
Normal response codes: 200
Error response codes: computeFault (400, 500, …), serviceUnavailable
(503), badRequest (400), unauthorized (401), forbidden (403),
badMethod (405), itemNotFound (404)
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- server_id: server_id_url
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- servers: servers
- addresses: server_addresses
- created: created
- flavor: flavor_obj
- hostId: hostId
- id: server_id
- image: image_obj
- key_name: keypair_name
- links: generic_links
- metadata: metadata
- name: server_name
- OS-DCF:diskConfig: server_disk_config
- OS-EXT-AZ:availability_zone: availability_zone
- OS-EXT-SRV-ATTR:host: server_compute_hostname
- OS-EXT-SRV-ATTR:hypervisor_hostname: server_hypervisor_hostname
- OS-EXT-SRV-ATTR:instance_name: server_instance_name
- OS-EXT-STS:power_state: server_power_state
- OS-EXT-STS:task_state: server_task_state
- OS-EXT-STS:vm_state: server_vm_state
- os-extended-volumes:volumes_attached: server_volumes_attached
- OS-SRV-USG:launched_at: server_launched_at
- OS-SRV-USG:terminated_at: server_terminated_at
- progress: build_progress
- security_groups: security_groups_obj
- description: sg_description
- id: sg_id
- name: sg_name
- rules: sg_rules
- status: server_status
- tenant_id: tenant_id_body
- updated: updated
- user_id: user_id
- locked: server_locked
- host_status: host_status
- description: server_description
Example Response
----------------
.. literalinclude:: /../../doc/api_samples/servers/server-get-resp.json
:language: javascript
Update Server
=============
.. rest_method:: PUT /v2.1/​{tenant_id}​/servers/​{server_id}
Preconditions
-------------
The server must exist.
You can edit the accessIPv4, accessIPv6, diskConfig and name attributes.
Normal response codes: 200
Error response codes: computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404), buildInProgress (409)
Request Parameters
------------------
(NOTE: sdague) - the upstream docs here are completely scatted and
seem to include the create parameters in this list when most of them
don't work.
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- server_id: server_id_url
- description: server_description
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- servers: servers
- addresses: server_addresses
- created: created
- flavor: flavor_obj
- hostId: hostId
- id: server_id
- image: image_obj
- key_name: keypair_name
- links: generic_links
- metadata: metadata
- name: server_name
- OS-DCF:diskConfig: server_disk_config
- OS-EXT-AZ:availability_zone: availability_zone
- OS-EXT-SRV-ATTR:host: server_compute_hostname
- OS-EXT-SRV-ATTR:hypervisor_hostname: server_hypervisor_hostname
- OS-EXT-SRV-ATTR:instance_name: server_instance_name
- OS-EXT-STS:power_state: server_power_state
- OS-EXT-STS:task_state: server_task_state
- OS-EXT-STS:vm_state: server_vm_state
- os-extended-volumes:volumes_attached: server_volumes_attached
- OS-SRV-USG:launched_at: server_launched_at
- OS-SRV-USG:terminated_at: server_terminated_at
- progress: build_progress
- security_groups: security_groups_obj
- description: sg_description
- id: sg_id
- name: sg_name
- rules: sg_rules
- status: server_status
- tenant_id: tenant_id_body
- updated: updated
- user_id: user_id
- locked: server_locked
- host_status: host_status
- description: server_description
Example Requests
----------------
Updating the allowed fields for a server
.. literalinclude:: /../../doc/api_samples/servers/server-update-req.json
:language: javascript
Example Response
----------------
.. literalinclude:: /../../doc/api_samples/servers/server-update-resp.json
:language: javascript
Delete Server
=============
.. rest_method:: DELETE /v2.1/​{tenant_id}​/servers/​{server_id}
Preconditions
-------------
- The server must exist.
- Anyone can delete a server when the status of the server is not
locked and when the policy allows.
- If the server is locked, you must have administrator privileges to
delete the server.
Asynchronous postconditions
---------------------------
- With correct permissions, you can see the server status as DELETED
through API calls.
- The port attached to the server is deleted.
- The server does not appear in the list servers response.
- The server managed by OpenStack Compute is deleted on the compute
node.
Troubleshooting
---------------
- If server status remains in deleting status or another error status,
the request failed. Ensure that you meet the preconditions. Then,
investigate the compute back end.
- The request returns the HTTP 409 response code when the server is
locked even if you have correct permissions. Ensure that you meet
the preconditions then investigate the server status.
- The server managed by OpenStack Compute is not deleted from the
compute node.
Normal response codes: 204
Error response codes: computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), itemNotFound (404)
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- server_id: server_id_url

53
api-ref/source/versions.rst Normal file
View File

@@ -0,0 +1,53 @@
==============
API Versions
==============
Concepts
========
In order to bring new features to users over time, the Nova API
supports versioning. There are 2 kinds of versions in Nova ''major
versions'' as defined by dedicated urls. There are also
''microversions'' which can be requested through use of the
``OpenStack-API-Version`` header.
List All Major Versions
=======================
.. rest_method:: GET /
Normal Response Codes: 200 300
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- x-openstack-request-id: request_id
Response Example
~~~~~~~~~~~~~~~~
.. literalinclude:: /../../doc/api_samples/versions/versions-get-resp.json
:language: javascript
Show Details of 2.1 API
=======================
.. rest_method:: GET /v2.1
Normal Response Codes: 200 300
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- x-openstack-request-id: request_id
Response Example
~~~~~~~~~~~~~~~~
.. literalinclude:: /../../doc/api_samples/versions/v21-version-get-resp.json
:language: javascript

15
tox.ini
View File

@@ -91,6 +91,7 @@ commands =
bash -c '! find doc/ -type f -name *.json | xargs -t -n1 python -m json.tool 2>&1 > /dev/null | grep -B1 -v ^python'
oslo-config-generator --config-file=etc/nova/nova-config-generator.conf
sphinx-build -W -b html api-guide/source api-guide/build/html
sphinx-build -b html api-ref/source api-ref/build/html
[testenv:api-guide]
# This environment is called from CI scripts to test and publish
@@ -102,6 +103,20 @@ install_command = pip install -U --force-reinstall {opts} {packages}
commands =
sphinx-build -W -b html -d api-guide/build/doctrees api-guide/source api-guide/build/html
[testenv:api-ref]
# This environment is called from CI scripts to test and publish
# the API Ref to developer.openstack.org.
# NOTE(sdague): this target does not use constraints because
# upstream infra does not yet support it. Once that's fixed, we can
# drop the install_command.
#
# we do not used -W here because we are doing some slightly tricky
# things to build a single page document, and as such, we are ok
# ignoring the duplicate stanzas warning.
install_command = pip install -U --force-reinstall {opts} {packages}
commands =
sphinx-build -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
[testenv:bandit]
commands = bandit -c bandit.yaml -r nova -n 5 -ll