From e2688277bcb3c7254a1b5ba32f3476ab52e5a9ce Mon Sep 17 00:00:00 2001 From: Sean Dague Date: Mon, 9 May 2016 10:35:43 -0400 Subject: [PATCH] api-ref: verify flavors.inc This completes the verification of flavors.inc across all phases. References to the 500 error that create could do have been removed because it turns out that code isn't reachable any more (see Ic848db8c3df75054c389e87b2405134262b531e2) Part of bp:api-ref-in-rst Change-Id: I9e89a737df558c930a2ca028ed169a5b3e383a3d --- api-ref/source/flavors.inc | 133 +++++++++++++++++++++++++-------- api-ref/source/parameters.yaml | 131 ++++++++++++++++++++++++++++---- 2 files changed, 216 insertions(+), 48 deletions(-) diff --git a/api-ref/source/flavors.inc b/api-ref/source/flavors.inc index e07f43e08185..14fe35ed7fb7 100644 --- a/api-ref/source/flavors.inc +++ b/api-ref/source/flavors.inc @@ -1,24 +1,25 @@ .. -*- rst -*- -.. needs:parameter_verification -.. needs:example_verification -.. needs:body_verification -============================================ - Flavors with extended attributes (flavors) -============================================ +========= + Flavors +========= -Shows information about flavors. +Show and manage server flavors. + +Flavors are a way to describe the basic dimensions of a server to be +created including how much ``cpu``, ``ram``, and ``disk space`` are +allocated to a server built with this flavor. List Flavors ============ .. rest_method:: GET /v2.1/{tenant_id}/flavors -Lists flavors. +Lists all flavors accessible to your project. Normal response codes: 200 -Error response codes: badRequest(400), unauthorized(401), forbidden(403) +Error response codes: unauthorized(401), forbidden(403) Request ------- @@ -26,23 +27,28 @@ Request .. rest_parameters:: parameters.yaml - tenant_id: tenant_id - -Query Parameters -~~~~~~~~~~~~~~~~ - -.. rest_parameters:: parameters.yaml - - - minDisk: minDisk - - minRam: minRam - sort_key: sort_key - sort_dir: sort_dir - limit: limit - marker: marker + - minDisk: minDisk + - minRam: minRam + - is_public: flavor_is_public_query Response -------- -**Example List Flavors: JSON response** +.. rest_parameters:: parameters.yaml + + - flavors: flavors + - id: flavor_id_body + - name: flavor_name + - links: links + +**Example List Flavors** + +Showing all the default flavors of a Liberty era Nova installation +that was not customized by the site operators. .. literalinclude:: ../../doc/api_samples/flavors/flavors-list-resp.json :language: javascript @@ -54,19 +60,32 @@ Create Flavor Creates a flavor. +Creating a flavor is typically only available to administrators of a +cloud because this has implications for scheduling efficiently in the cloud. + Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), -conflict(409), computeFault(500) +conflict(409) Request ------- .. rest_parameters:: parameters.yaml - - tenant_id: tenant_id + - tenant_id: tenant_id + - flavor: flavor + - name: flavor_name + - id: flavor_id_body + - ram: flavor_ram + - disk: flavor_disk + - vcpus: flavor_cpus + - OS-FLV-EXT-DATA:ephemeral: flavor_ephem_disk_in + - swap: flavor_swap_in + - rxtx_factor: flavor_rxtx_factor_in + - os-flavor-access:is_public: flavor_is_public_in -**Example Create Flavor: JSON request** +**Example Create Flavor** .. literalinclude:: ../../doc/api_samples/flavor-manage/flavor-create-post-req.json :language: javascript @@ -74,7 +93,24 @@ Request Response -------- -**Example Create Flavor: JSON response** +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id + - flavor: flavor + - name: flavor_name + - id: flavor_id_body + - ram: flavor_ram + - disk: flavor_disk + - vcpus: flavor_cpus + - links: links + - OS-FLV-EXT-DATA:ephemeral: flavor_ephem_disk + - OS-FLV-DISABLED:disabled: flavor_disabled + - swap: flavor_swap + - rxtx_factor: flavor_rxtx_factor + - os-flavor-access:is_public: flavor_is_public + + +**Example Create Flavor** .. literalinclude:: ../../doc/api_samples/flavor-manage/flavor-create-post-resp.json :language: javascript @@ -96,23 +132,35 @@ Request .. rest_parameters:: parameters.yaml - tenant_id: tenant_id - -Query Parameters -~~~~~~~~~~~~~~~~ - -.. rest_parameters:: parameters.yaml - - - minDisk: minDisk - - minRam: minRam - sort_key: sort_key - sort_dir: sort_dir - limit: limit - marker: marker + - minDisk: minDisk + - minRam: minRam + - is_public: flavor_is_public_query + Response -------- -**Example List Flavors With Details: JSON response** +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id + - flavors: flavors + - name: flavor_name + - id: flavor_id_body + - ram: flavor_ram + - disk: flavor_disk + - vcpus: flavor_cpus + - links: links + - OS-FLV-EXT-DATA:ephemeral: flavor_ephem_disk + - OS-FLV-DISABLED:disabled: flavor_disabled + - swap: flavor_swap + - rxtx_factor: flavor_rxtx_factor + - os-flavor-access:is_public: flavor_is_public + +**Example List Flavors With Details** .. literalinclude:: ../../doc/api_samples/flavors/flavors-detail-resp.json :language: javascript @@ -139,7 +187,23 @@ Request Response -------- -**Example Show Flavor Details: JSON response** +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id + - flavor: flavor + - name: flavor_name + - id: flavor_id_body + - ram: flavor_ram + - disk: flavor_disk + - vcpus: flavor_cpus + - links: links + - OS-FLV-EXT-DATA:ephemeral: flavor_ephem_disk + - OS-FLV-DISABLED:disabled: flavor_disabled + - swap: flavor_swap + - rxtx_factor: flavor_rxtx_factor + - os-flavor-access:is_public: flavor_is_public + +**Example Show Flavor Details** .. literalinclude:: ../../doc/api_samples/flavors/flavor-get-resp.json :language: javascript @@ -151,6 +215,10 @@ Delete Flavor Deletes a flavor. +This is typically an admin only action. Deleting a flavor that is in use by +existing servers is not recommended as it can cause incorrect data to +be returned to the user under some operations. + Normal response codes: 202 Error response codes: unauthorized(401), forbidden(403), itemNotFound(404) @@ -166,3 +234,4 @@ Request Response -------- +No body content is returned on a successful DELETE. diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 901948257889..ce3959eadc35 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -365,6 +365,15 @@ exclude: in: query required: false type: string +flavor_is_public_query: + in: query + required: false + type: boolean + description: | + Filters the flavor list by only public flavors. By default ``non + admin`` users only see public flavors, and ``admin`` users can see + additional non public flavors. + flavor_query: description: | Filters the response by a flavor, as a UUID. A flavor is a combination of memory, @@ -424,25 +433,13 @@ marker: type: string minDisk: description: | - Filters the response by a minimum disk space, in GiB. - in: query - required: false - type: integer -minDisk_1: - description: | - Filters the response by a minimum disk size. For example, ``100``. + Filters the response by a minimum disk space, in GiB. For example, ``100``. in: query required: false type: integer minRam: description: | - Filters the response by a minimum RAM, in MB. - in: query - required: false - type: integer -minRam_1: - description: | - Filters the response by a minimum RAM size. For example, ``512``. + Filters the response by a minimum RAM, in MB. For example, ``512``. in: query required: false type: integer @@ -1067,22 +1064,124 @@ flavor: type: object flavor_access: description: | - A list of dictionaries, each with the keys ``flavor_id`` and ``tenant_id``. + A list of objects, each with the keys ``flavor_id`` and ``tenant_id``. in: body required: true type: array +flavor_cpus: + in: body + required: true + type: int + description: | + The number of virtual cpus that will be allocated to the server. +flavor_disabled: + in: body + required: false + type: boolean + description: | + Whether or not the flavor has been administratively disabled. + This is typically only visible to administrative users. +flavor_disk: + in: body + required: true + type: int + description: | + The size of the root disk that will be created in GiB. If 0 the + root disk will be set to exactly the size of the image used to + deploy the instance. +flavor_ephem_disk: + in: body + required: true + type: int + description: | + The size of the ephemeral disk that will be created, in + GiB. Ephemeral disks may be written over on server state + changes. So should only be used as a scratch space for + applications that are aware of it's limitations. Defaults to 0. +flavor_ephem_disk_in: + in: body + required: false + type: int + description: | + The size of the ephemeral disk that will be created, in + GiB. Ephemeral disks may be written over on server state + changes. So should only be used as a scratch space for + applications that are aware of it's limitations. Defaults to 0. flavor_id_body: description: | - The ID of the flavor. + The ID of the flavor. While people often make this look like + an int, this is really a string. in: body required: true type: string +flavor_is_public: + in: body + required: true + type: boolean + description: | + Wheter the flavor is public (available to all projects) or scoped + to a set of projects. Default is True if not specified. +flavor_is_public_in: + in: body + required: false + type: boolean + description: | + Wheter the flavor is public (available to all projects) or scoped + to a set of projects. Default is True if not specified. +flavor_name: + in: body + required: true + type: string + description: | + The display name of a flavor. +flavor_ram: + in: body + required: true + type: int + description: | + The amount of RAM a flavor has, in MiB. +flavor_rxtx_factor: + in: body + required: true + type: float + description: | + The receive / transimit factor (as a float) that will be set on + ports if the network backend supports the QOS extension. + Otherwise it will be ignored. It defaults to 1.0. +flavor_rxtx_factor_in: + in: body + required: false + type: float + description: | + The receive / transimit factor (as a float) that will be set on + ports if the network backend supports the QOS extension. + Otherwise it will be ignored. It defaults to 1.0. +flavor_swap: + in: body + required: true + type: int + description: | + The size of a dedicated swap disk that will be allocated, in + GiB. If 0 (the default), no dedicated swap disk will be created. +flavor_swap_in: + in: body + required: false + type: int + description: | + The size of a dedicated swap disk that will be allocated, in + GiB. If 0 (the default), no dedicated swap disk will be created. flavorRef: description: | The flavor reference, as a UUID or full URL, for the flavor for your server instance. in: body required: true type: string +flavors: + description: | + An array of flavor objects. + in: body + required: true + type: array floating_ip_pool_name: description: | The name of the floating ip pool.