From 329898ffbcf26274cf1e33ac9b1ccae9744c338a Mon Sep 17 00:00:00 2001 From: Sean Dague Date: Tue, 29 Mar 2016 11:56:21 -0400 Subject: [PATCH] Add sample API content 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 --- api-ref/source/index.rst | 8 + api-ref/source/parameters.yaml | 609 ++++++++++++++++++++++++++++++++ api-ref/source/servers.rst | 624 +++++++++++++++++++++++++++++++++ api-ref/source/versions.rst | 53 +++ tox.ini | 15 + 5 files changed, 1309 insertions(+) create mode 100644 api-ref/source/index.rst create mode 100644 api-ref/source/parameters.yaml create mode 100644 api-ref/source/servers.rst create mode 100644 api-ref/source/versions.rst diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst new file mode 100644 index 000000000000..4b28d1e09f66 --- /dev/null +++ b/api-ref/source/index.rst @@ -0,0 +1,8 @@ +:tocdepth: 2 + +============= + Compute API +============= + +.. include:: versions.rst +.. include:: servers.rst diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml new file mode 100644 index 000000000000..02e84ed93883 --- /dev/null +++ b/api-ref/source/parameters.yaml @@ -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. diff --git a/api-ref/source/servers.rst b/api-ref/source/servers.rst new file mode 100644 index 000000000000..06716188df17 --- /dev/null +++ b/api-ref/source/servers.rst @@ -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 diff --git a/api-ref/source/versions.rst b/api-ref/source/versions.rst new file mode 100644 index 000000000000..8cda2ce81001 --- /dev/null +++ b/api-ref/source/versions.rst @@ -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 diff --git a/tox.ini b/tox.ini index b2d535849ed5..c4a02abe31f8 100644 --- a/tox.ini +++ b/tox.ini @@ -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