diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index db1ad89f75..6ac27a60d2 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -278,7 +278,15 @@ all_projects: type: boolean all_tenants: description: | - Specify the ``all_tenants=1`` query parameter to ping instances for all tenants. + Specify the ``all_tenants=1`` query parameter to ping instances + for all tenants. By default this is only allowed by admin users. + in: query + required: false + type: integer +all_tenants_query: + description: | + Specify the ``all_tenants=1`` query parameter to list all instances + for all projects. By default this is only allowed by admin users. in: query required: false type: integer @@ -320,9 +328,20 @@ changes-since: in: query required: false type: string -changes-since_1: +changes_since_server: description: | - Filters the response by a date and time stamp when the server last changed status. + Filters the response by a date and time stamp when the server last + changed status. To help keep track of changes this may also return + recently deleted servers. + + The date and time stamp format is `ISO 8601 `_: + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + The ``±hh:mm`` value, if included, returns the time zone as an offset from UTC. + For example, ``2015-08-27T09:49:58-05:00``. + If you omit the time zone, the UTC time zone is assumed. in: query required: false type: string @@ -337,6 +356,15 @@ delete_info: in: query required: true type: string +deleted_query: + in: query + required: false + type: boolean + description: | + Show deleted items. In some circumstances deleted items will still + be accessible via the backend database, however there is no + contract on how long, so this parameter should be used with + caution. It is typically only available to administrators. exclude: description: | Specify ``exclude=uuid[,uuid...]`` to exclude the instances from the results. @@ -370,6 +398,19 @@ include: in: query required: false type: string +ip_query: + description: | + An IPv4 address to filter results by. + in: query + required: false + type: string +ip6_query: + description: | + An IPv6 address to filter results by. + in: query + required: false + type: string + min_version: 2.5 limit: description: | Requests a page size of items. Returns a number of items up to a limit value. @@ -411,6 +452,12 @@ minRam_1: in: query required: false type: integer +reservation_id_query: + in: query + required: false + type: string + description: | + A reservation id as returned by a servers multiple create call. server_name_query: description: | Filters the response by a server name, as a string. You can use regular expressions @@ -465,6 +512,40 @@ server_status_query: in: query required: false type: string +# TODO(sdague): when server-tags actually get documented, these should +# be updated. +tags_query: + in: query + required: false + type: string + description: | + A list of tags to filter the server list by. Servers that match + all tags in this list will be returned. + min_version: 2.26 +tags_any_query: + in: query + required: false + type: string + description: | + A list of tags to filter the server list by. Servers that match + any tag in this list will be returned. + min_version: 2.26 +not_tags_query: + in: query + required: false + type: string + description: | + A list of tags to filter the server list by. Servers that don't + match all tags in this list will be returned. + min_version: 2.26 +not_tags_any_query: + in: query + required: false + type: string + description: | + A list of tags to filter the server list by. Servers that don't + match any tags in this list will be returned. + min_version: 2.26 type_1: description: | Filters the response by an image type. For example, ``snapshot`` or ``backup``. @@ -500,7 +581,7 @@ OS-DCF:diskConfig: in: body required: false type: string -OS-DCF:diskConfig_1: +disk_config: description: | Disk configuration. The value is either: @@ -597,11 +678,25 @@ accessIPv4: required: true type: string description: | - IPv4 address that should be used to access this server. + IPv4 address that should be used to access this server. May be + automatically set by the provider. accessIPv6: in: body required: true type: string + description: | + IPv6 address that should be used to access this server. May be + automatically set by the provider. +accessIPv4_in: + in: body + required: false + type: string + description: | + IPv4 address that should be used to access this server. +accessIPv6_in: + in: body + required: false + type: string description: | IPv6 address that should be used to access this server. addFixedIp: @@ -761,6 +856,12 @@ config_drive: in: body required: false type: boolean +config_drive_resp: + description: | + Indicates whether or not a config drive was used for this server. + in: body + required: true + type: boolean confirmResize: description: | The action. @@ -1257,7 +1358,7 @@ key_name: in: body required: false type: string -key_name_1: +key_name_resp: description: | The name of associated key pair, if any. in: body @@ -1346,10 +1447,10 @@ metadata_1: in: body required: false type: object -metadata_2: +metadata_compat: description: | A dictionary of metadata key-and-value pairs, which is maintained for backward - compatibility. The API always returns an empty metadata dictionary. + compatibility. in: body required: true type: object @@ -1428,6 +1529,15 @@ server_name: in: body required: true type: string +server_description: + type: string + in: body + required: false + min_version: 2.19 + description: | + A free form description of the server. Limited to 255 characters + in length. Before microversion 2.19 this was set to the server + name. name_8: description: | Name of the extension. @@ -2000,6 +2110,12 @@ tag: in: body required: false type: string +tenant_id_body: + description: | + The UUID of the tenant this server is owned by. + in: body + required: true + type: string to_port: description: | The port at end of range. diff --git a/api-ref/source/servers.inc b/api-ref/source/servers.inc index 452a775b1c..843929132b 100644 --- a/api-ref/source/servers.inc +++ b/api-ref/source/servers.inc @@ -1,5 +1,6 @@ .. -*- rst -*- -.. needs:parameter_verification +.. TODO(sdague) parameter microversions need to be gone through in the + response (request side should be good) .. needs:example_verification .. needs:body_verification @@ -156,14 +157,24 @@ Request .. rest_parameters:: parameters.yaml - tenant_id: tenant_id - - changes-since: changes-since + - limit: limit + - marker: marker + - sort_key: sort_key + - sort_dir: sort_dir + - changes-since: changes_since_server - image: image_query - flavor: flavor_query - name: server_name_query - status: server_status_query - - host: host_query - - limit: limit - - marker: marker + - ip: ip_query + - reservation_id: reservation_id_query + - all_tenants: all_tenants_query + - deleted: deleted_query + - ip6: ip6_query + - tags: tags_query + - tags-any: tags_any_query + - not-tags: not_tags_query + - not-tags-any: not_tags_any_query Response -------- @@ -273,6 +284,9 @@ Request - imageRef: imageRef - security_groups: security_groups - metadata: metadata + - accessIPv4: accessIPv4_in + - accessIPv6: accessIPv6_in + - adminPass: adminPass - user_data: user_data - os-availability-zone:availability_zone: os-availability-zone:availability_zone - networks: networks @@ -291,6 +305,7 @@ Request - key_name: key_name - os:scheduler_hints: os:scheduler_hints - OS-DCF:diskConfig: OS-DCF:diskConfig + - description: server_description **Example Create Server: JSON request** @@ -303,15 +318,42 @@ Response .. rest_parameters:: parameters.yaml - server: server - - adminPass: adminPass + - addresses: addresses + - created: created + - flavor: flavor + - hostId: hostId - id: server_id + - image: image + - key_name: key_name_resp - links: links - - OS-DCF:diskConfig: OS-DCF:diskConfig - - security_groups: security_groups + - metadata: metadata_compat + - name: server_name + - accessIPv4: accessIPv4 + - accessIPv6: accessIPv6 + - config_drive: config_drive_resp + - OS-DCF:diskConfig: disk_config + - OS-EXT-AZ:availability_zone: OS-EXT-AZ:availability_zone + - OS-EXT-SRV-ATTR:host: OS-EXT-SRV-ATTR:host + - OS-EXT-SRV-ATTR:hypervisor_hostname: OS-EXT-SRV-ATTR:hypervisor_hostname + - OS-EXT-SRV-ATTR:instance_name: OS-EXT-SRV-ATTR:instance_name + - OS-EXT-STS:power_state: OS-EXT-STS:power_state + - OS-EXT-STS:task_state: OS-EXT-STS:task_state + - OS-EXT-STS:vm_state: OS-EXT-STS:vm_state + - os-extended-volumes:volumes_attached: os-extended-volumes:volumes_attached + - OS-SRV-USG:launched_at: OS-SRV-USG:launched_at + - OS-SRV-USG:terminated_at: OS-SRV-USG:terminated_at + - progress: progress + - security_groups: security_groups_obj + - security_group.name: name + - status: server_status + - host_status: host_status + - tenant_id: tenant_id_body + - updated: updated + - user_id: user_id **Example Create Server: JSON response** -.. literalinclude:: ../../doc/api_samples/servers/server-create-resp.json +.. literalinclude:: ../../doc/api_samples/all_extensions/server-create-resp.json :language: javascript @@ -346,14 +388,24 @@ Request .. rest_parameters:: parameters.yaml - tenant_id: tenant_id - - changes-since: changes-since + - limit: limit + - marker: marker + - sort_key: sort_key + - sort_dir: sort_dir + - changes-since: changes_since_server - image: image_query - flavor: flavor_query - name: server_name_query - status: server_status_query - - host: host_query - - limit: limit - - marker: marker + - ip: ip_query + - reservation_id: reservation_id_query + - all_tenants: all_tenants_query + - deleted: deleted_query + - ip6: ip6_query + - tags: tags_query + - tags-any: tags_any_query + - not-tags: not_tags_query + - not-tags-any: not_tags_any_query Response -------- @@ -367,11 +419,14 @@ Response - hostId: hostId - id: server_id - image: image - - key_name: key_name + - key_name: key_name_resp - links: links - - metadata: metadata - - name: name - - OS-DCF:diskConfig: OS-DCF:diskConfig + - metadata: metadata_compat + - name: server_name + - accessIPv4: accessIPv4 + - accessIPv6: accessIPv6 + - config_drive: config_drive_resp + - OS-DCF:diskConfig: disk_config - OS-EXT-AZ:availability_zone: OS-EXT-AZ:availability_zone - OS-EXT-SRV-ATTR:host: OS-EXT-SRV-ATTR:host - OS-EXT-SRV-ATTR:hypervisor_hostname: OS-EXT-SRV-ATTR:hypervisor_hostname @@ -384,19 +439,16 @@ Response - OS-SRV-USG:terminated_at: OS-SRV-USG:terminated_at - progress: progress - security_groups: security_groups_obj - - security_group.description: description - - security_group.id: id - security_group.name: name - - security_group.rules: rules - status: server_status - host_status: host_status - - tenant_id: tenant_id + - tenant_id: tenant_id_body - updated: updated - user_id: user_id **Example List Servers Detailed: JSON response** -.. literalinclude:: /../../doc/api_samples/servers/servers-details-resp.json +.. literalinclude:: /../../doc/api_samples/all_extensions/servers-details-resp.json :language: javascript @@ -446,11 +498,14 @@ Response - hostId: hostId - id: server_id - image: image - - key_name: key_name + - key_name: key_name_resp - links: links - - metadata: metadata + - metadata: metadata_compat - name: server_name - - OS-DCF:diskConfig: OS-DCF:diskConfig + - accessIPv4: accessIPv4 + - accessIPv6: accessIPv6 + - config_drive: config_drive_resp + - OS-DCF:diskConfig: disk_config - OS-EXT-AZ:availability_zone: OS-EXT-AZ:availability_zone - OS-EXT-SRV-ATTR:host: OS-EXT-SRV-ATTR:host - OS-EXT-SRV-ATTR:hypervisor_hostname: OS-EXT-SRV-ATTR:hypervisor_hostname @@ -463,19 +518,16 @@ Response - OS-SRV-USG:terminated_at: OS-SRV-USG:terminated_at - progress: progress - security_groups: security_groups_obj - - security_group.description: description - - security_group.id: id - security_group.name: name - - security_group.rules: rules - status: server_status - host_status: host_status - - tenant_id: tenant_id + - tenant_id: tenant_id_body - updated: updated - user_id: user_id **Example Show Server Details: JSON response** -.. literalinclude:: ../../doc/api_samples/servers/server-get-resp.json +.. literalinclude:: ../../doc/api_samples/all_extensions/server-get-resp.json :language: javascript Update Server @@ -483,13 +535,7 @@ Update Server .. rest_method:: PUT /v2.1/{tenant_id}/servers/{server_id} -Updates the editable attributes of a server. - -Preconditions - -The server must exist. - -You can edit the ``accessIPv4``, ``accessIPv6``, ``diskConfig`` and ``name`` attributes. +Updates the editable attributes of an existing server. Normal response codes: 200 @@ -503,10 +549,11 @@ Request - tenant_id: tenant_id - server_id: server_id_path - - accessIPv4: accessIPv4 - - accessIPv6: accessIPv6 + - accessIPv4: accessIPv4_in + - accessIPv6: accessIPv6_in - name: server_name - OS-DCF:diskConfig: OS-DCF:diskConfig + - description: server_description **Example Update server name: JSON request** @@ -542,7 +589,9 @@ Response - key_name: key_name - links: links - metadata: metadata - - name: name + - name: server_name + - accessIPv4: accessIPv4 + - accessIPv6: accessIPv6 - OS-DCF:diskConfig: OS-DCF:diskConfig - OS-EXT-AZ:availability_zone: OS-EXT-AZ:availability_zone - OS-EXT-SRV-ATTR:host: OS-EXT-SRV-ATTR:host @@ -556,10 +605,7 @@ Response - OS-SRV-USG:terminated_at: OS-SRV-USG:terminated_at - progress: progress - security_groups: security_groups_obj - - security_group.description: description - - security_group.id: id - security_group.name: name - - security_group.rules: rules - status: server_status - host_status: host_status - tenant_id: tenant_id