diff --git a/api-ref/source/flavors.inc b/api-ref/source/flavors.inc index e07f43e081..14fe35ed7f 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 9019482578..ce3959eadc 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.