From f30aa064f9366a3164f44c0665d8d9ffb21b1276 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Thu, 18 Oct 2018 14:32:47 +0100 Subject: [PATCH] api-ref: 'os-hypervisors' doesn't reflect overcommit ratio We could/should introduce an API microversion to correct this or remove it, given that placement should be the go-to reference for this stuff going forward. However, for now we take the path of least resistance and document the broken behavior. Change-Id: Id8532d5a9480e4f71a9390e3b98886c85e27d003 --- api-ref/source/os-hypervisors.inc | 18 +++++++++++++ api-ref/source/parameters.yaml | 44 ++++++++++++++++++++++--------- 2 files changed, 50 insertions(+), 12 deletions(-) diff --git a/api-ref/source/os-hypervisors.inc b/api-ref/source/os-hypervisors.inc index b6e661f85996..4011e69490ee 100644 --- a/api-ref/source/os-hypervisors.inc +++ b/api-ref/source/os-hypervisors.inc @@ -147,6 +147,15 @@ Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the ``policy.json`` file. +.. note:: + + As noted, some of the parameters in the response representing totals do not + take allocation ratios into account. This can result in a disparity between + the totals and the usages. A more accurate representation of state can be + obtained using `placement`__. + + __ https://developer.openstack.org/api-ref/placement/#list-resource-provider-usages + Normal response codes: 200 Error response codes: unauthorized(401), forbidden(403) @@ -186,6 +195,15 @@ Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the ``policy.json`` file. +.. note:: + + As noted, some of the parameters in the response representing totals do not + take allocation ratios into account. This can result in a disparity between + the totals and the usages. A more accurate representation of state can be + obtained using `placement`__. + + __ https://developer.openstack.org/api-ref/placement/#show-resource-provider-usages + Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404) diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 31d329c135b3..70a2d3cf819f 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -2303,13 +2303,15 @@ disabled_reason_body: type: string disk_available_least: description: | - The actual free disk on this hypervisor(in GiB). + The actual free disk on this hypervisor(in GiB). If allocation ratios used + for overcommit are configured, this may be negative. in: body required: true type: integer disk_available_least_total: description: | - The actual free disk on all hypervisors(in GiB). + The actual free disk on all hypervisors(in GiB). If allocation ratios used + for overcommit are configured, this may be negative. in: body required: true type: integer @@ -3197,13 +3199,15 @@ forceDelete: type: none free_ram_mb: description: | - The free RAM in this hypervisor(in MiB). + The free RAM in this hypervisor(in MiB). This does not take allocation + ratios used for overcommit into account so this value may be negative. in: body required: true type: integer free_ram_mb_total: description: | - The free RAM on all hypervisors(in MiB). + The free RAM on all hypervisors(in MiB). This does not take allocation + ratios used for overcommit into account so this value may be negative. in: body required: true type: integer @@ -3482,13 +3486,17 @@ hypervisor_diagnostics: min_version: 2.48 hypervisor_free_disk_gb: description: | - The free disk remaining on this hypervisor(in GiB). + The free disk remaining on this hypervisor(in GiB). This does not take + allocation ratios used for overcommit into account so this value may be + negative. in: body required: true type: integer hypervisor_free_disk_gb_total: description: | - The free disk remaining on all hypervisors(in GiB). + The free disk remaining on all hypervisors(in GiB). This does not take + allocation ratios used for overcommit into account so this value may be + negative. in: body required: true type: integer @@ -3595,13 +3603,17 @@ hypervisor_type_body: type: string hypervisor_vcpus: description: | - The number of vcpu in this hypervisor. + The number of vcpu in this hypervisor. This does not take allocation + ratios used for overcommit into account so there may be disparity between + this and the used count. in: body required: true type: integer hypervisor_vcpus_total: description: | - The number of vcpu on all hypervisors. + The number of vcpu on all hypervisors. This does not take allocation + ratios used for overcommit into account so there may be disparity between + this and the used count. in: body required: true type: integer @@ -4209,7 +4221,9 @@ links: type: array local_gb: description: | - The disk in this hypervisor(in GiB). + The disk in this hypervisor(in GiB). This does not take allocation + ratios used for overcommit into account so there may be disparity between + this and the used count. in: body required: true type: integer @@ -4229,7 +4243,9 @@ local_gb_simple_tenant_usage_optional: type: integer local_gb_total: description: | - The disk on all hypervisors(in GiB). + The disk on all hypervisors(in GiB). This does not take allocation + ratios used for overcommit into account so there may be disparity between + this and the used count. in: body required: true type: integer @@ -4309,7 +4325,9 @@ memory_details_diagnostics: min_version: 2.48 memory_mb: description: | - The memory of this hypervisor(in MiB). + The memory of this hypervisor(in MiB). This does not take allocation + ratios used for overcommit into account so there may be disparity between + this and the used count. in: body required: true type: integer @@ -4327,7 +4345,9 @@ memory_mb_simple_tenant_usage_optional: type: integer memory_mb_total: description: | - The memory of all hypervisors(in MiB). + The memory of all hypervisors(in MiB). This does not take allocation + ratios used for overcommit into account so there may be disparity between + this and the used count. in: body required: true type: integer