From 71a7eda44b6da00c05bd3e136d0465086c30e721 Mon Sep 17 00:00:00 2001 From: Sylvain Bauza Date: Thu, 13 Apr 2017 16:48:04 +0200 Subject: [PATCH] Fix AZ related API docs While we have a big fat comment in the development docs explaining why it's so terrible to use default AZ values for either booting an instance or setting an aggregate AZ metadata, we still have confusing API docs that provide the wrong name for the AZ... Fixing that and trying to explain the problem within the docs, too. Change-Id: I811d0f219142ca435b2b206e9b11ccd5ac611997 Co-Authored-By: Stephen Finucane --- api-ref/source/parameters.yaml | 17 +++++++++++++---- .../os-aggregates/aggregate-post-req.json | 4 ++-- .../os-aggregates/aggregate-post-resp.json | 2 +- .../aggregates-add-host-post-resp.json | 4 ++-- .../os-aggregates/aggregates-get-resp.json | 4 ++-- .../os-aggregates/aggregates-list-get-resp.json | 4 ++-- .../aggregates-metadata-post-resp.json | 4 ++-- .../aggregates-remove-host-post-resp.json | 4 ++-- .../v2.41/aggregate-post-resp.json | 4 ++-- .../v2.41/aggregates-add-host-post-resp.json | 6 +++--- .../v2.41/aggregates-get-resp.json | 6 +++--- .../v2.41/aggregates-list-get-resp.json | 6 +++--- .../v2.41/aggregates-metadata-post-resp.json | 6 +++--- .../v2.41/aggregates-remove-host-post-resp.json | 6 +++--- 14 files changed, 43 insertions(+), 34 deletions(-) diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index ec4b893ab2a1..b96cb5c7fa70 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -1302,7 +1302,9 @@ aggregate_az: type: string aggregate_az_optional: description: | - The availability zone of the host aggregate. + The availability zone of the host aggregate. You should use a custom + availability zone rather than the default returned by the + os-availability-zone API. in: body required: false type: string @@ -4162,9 +4164,11 @@ os: type: string os-availability-zone:availability_zone: 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. + 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, an admin user will 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 @@ -4172,6 +4176,11 @@ os-availability-zone:availability_zone: 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. + You can list the available availability zones by calling the + os-availability-zone API, but you should avoid using the default + availability zone when booting the instance. In general, the + default availability zone is named ``nova``. This AZ is only shown + when listing the availability zones as an admin. in: body required: false type: string diff --git a/doc/api_samples/os-aggregates/aggregate-post-req.json b/doc/api_samples/os-aggregates/aggregate-post-req.json index 82272c2936b5..deeb3bc55a9e 100644 --- a/doc/api_samples/os-aggregates/aggregate-post-req.json +++ b/doc/api_samples/os-aggregates/aggregate-post-req.json @@ -2,6 +2,6 @@ "aggregate": { "name": "name", - "availability_zone": "nova" + "availability_zone": "london" } -} \ No newline at end of file +} diff --git a/doc/api_samples/os-aggregates/aggregate-post-resp.json b/doc/api_samples/os-aggregates/aggregate-post-resp.json index 1f8ab18093ea..c265bcc842dd 100644 --- a/doc/api_samples/os-aggregates/aggregate-post-resp.json +++ b/doc/api_samples/os-aggregates/aggregate-post-resp.json @@ -1,6 +1,6 @@ { "aggregate": { - "availability_zone": "nova", + "availability_zone": "london", "created_at": "2013-08-18T12:17:55.751757", "deleted": false, "deleted_at": null, diff --git a/doc/api_samples/os-aggregates/aggregates-add-host-post-resp.json b/doc/api_samples/os-aggregates/aggregates-add-host-post-resp.json index 568be44eb449..0952cdfb85a7 100644 --- a/doc/api_samples/os-aggregates/aggregates-add-host-post-resp.json +++ b/doc/api_samples/os-aggregates/aggregates-add-host-post-resp.json @@ -1,6 +1,6 @@ { "aggregate": { - "availability_zone": "nova", + "availability_zone": "london", "created_at": "2013-08-18T12:17:56.297823", "deleted": false, "deleted_at": null, @@ -9,7 +9,7 @@ ], "id": 1, "metadata": { - "availability_zone": "nova" + "availability_zone": "london" }, "name": "name", "updated_at": null diff --git a/doc/api_samples/os-aggregates/aggregates-get-resp.json b/doc/api_samples/os-aggregates/aggregates-get-resp.json index 08f4b8ed074d..8b9248caa1ab 100644 --- a/doc/api_samples/os-aggregates/aggregates-get-resp.json +++ b/doc/api_samples/os-aggregates/aggregates-get-resp.json @@ -1,13 +1,13 @@ { "aggregate": { - "availability_zone": "nova", + "availability_zone": "london", "created_at": "2013-08-18T12:17:56.380226", "deleted": false, "deleted_at": null, "hosts": [], "id": 1, "metadata": { - "availability_zone": "nova" + "availability_zone": "london" }, "name": "name", "updated_at": null diff --git a/doc/api_samples/os-aggregates/aggregates-list-get-resp.json b/doc/api_samples/os-aggregates/aggregates-list-get-resp.json index 3887b096f87c..1913a7dee1e3 100644 --- a/doc/api_samples/os-aggregates/aggregates-list-get-resp.json +++ b/doc/api_samples/os-aggregates/aggregates-list-get-resp.json @@ -1,14 +1,14 @@ { "aggregates": [ { - "availability_zone": "nova", + "availability_zone": "london", "created_at": "2013-08-18T12:17:56.856455", "deleted": false, "deleted_at": null, "hosts": ["21549b2f665945baaa7101926a00143c"], "id": 1, "metadata": { - "availability_zone": "nova" + "availability_zone": "london" }, "name": "name", "updated_at": null diff --git a/doc/api_samples/os-aggregates/aggregates-metadata-post-resp.json b/doc/api_samples/os-aggregates/aggregates-metadata-post-resp.json index bcfeacd8f314..d4c65717a01a 100644 --- a/doc/api_samples/os-aggregates/aggregates-metadata-post-resp.json +++ b/doc/api_samples/os-aggregates/aggregates-metadata-post-resp.json @@ -1,13 +1,13 @@ { "aggregate": { - "availability_zone": "nova", + "availability_zone": "london", "created_at": "2013-08-18T12:17:55.959571", "deleted": false, "deleted_at": null, "hosts": [], "id": 1, "metadata": { - "availability_zone": "nova", + "availability_zone": "london", "key": "value" }, "name": "name", diff --git a/doc/api_samples/os-aggregates/aggregates-remove-host-post-resp.json b/doc/api_samples/os-aggregates/aggregates-remove-host-post-resp.json index 732766b1f728..f543eec110ab 100644 --- a/doc/api_samples/os-aggregates/aggregates-remove-host-post-resp.json +++ b/doc/api_samples/os-aggregates/aggregates-remove-host-post-resp.json @@ -1,13 +1,13 @@ { "aggregate": { - "availability_zone": "nova", + "availability_zone": "london", "created_at": "2013-08-18T12:17:56.990581", "deleted": false, "deleted_at": null, "hosts": [], "id": 1, "metadata": { - "availability_zone": "nova" + "availability_zone": "london" }, "name": "name", "updated_at": null diff --git a/doc/api_samples/os-aggregates/v2.41/aggregate-post-resp.json b/doc/api_samples/os-aggregates/v2.41/aggregate-post-resp.json index 07b9ca318cbb..357e4d4eb27a 100644 --- a/doc/api_samples/os-aggregates/v2.41/aggregate-post-resp.json +++ b/doc/api_samples/os-aggregates/v2.41/aggregate-post-resp.json @@ -1,6 +1,6 @@ { "aggregate": { - "availability_zone": "nova", + "availability_zone": "london", "created_at": "2016-12-27T22:51:32.877711", "deleted": false, "deleted_at": null, @@ -9,4 +9,4 @@ "updated_at": null, "uuid": "86a0da0e-9f0c-4f51-a1e0-3c25edab3783" } -} \ No newline at end of file +} diff --git a/doc/api_samples/os-aggregates/v2.41/aggregates-add-host-post-resp.json b/doc/api_samples/os-aggregates/v2.41/aggregates-add-host-post-resp.json index 0f1a40f2cc3e..f0e3f06f3c62 100644 --- a/doc/api_samples/os-aggregates/v2.41/aggregates-add-host-post-resp.json +++ b/doc/api_samples/os-aggregates/v2.41/aggregates-add-host-post-resp.json @@ -1,6 +1,6 @@ { "aggregate": { - "availability_zone": "nova", + "availability_zone": "london", "created_at": "2016-12-27T23:47:30.594805", "deleted": false, "deleted_at": null, @@ -9,10 +9,10 @@ ], "id": 1, "metadata": { - "availability_zone": "nova" + "availability_zone": "london" }, "name": "name", "updated_at": null, "uuid": "d1842372-89c5-4fbd-ad5a-5d2e16c85456" } -} \ No newline at end of file +} diff --git a/doc/api_samples/os-aggregates/v2.41/aggregates-get-resp.json b/doc/api_samples/os-aggregates/v2.41/aggregates-get-resp.json index 5cd1cf75ff88..5ce65fb49e34 100644 --- a/doc/api_samples/os-aggregates/v2.41/aggregates-get-resp.json +++ b/doc/api_samples/os-aggregates/v2.41/aggregates-get-resp.json @@ -1,16 +1,16 @@ { "aggregate": { - "availability_zone": "nova", + "availability_zone": "london", "created_at": "2016-12-27T23:47:30.563527", "deleted": false, "deleted_at": null, "hosts": [], "id": 1, "metadata": { - "availability_zone": "nova" + "availability_zone": "london" }, "name": "name", "updated_at": null, "uuid": "fd0a5b12-7e8d-469d-bfd5-64a6823e7407" } -} \ No newline at end of file +} diff --git a/doc/api_samples/os-aggregates/v2.41/aggregates-list-get-resp.json b/doc/api_samples/os-aggregates/v2.41/aggregates-list-get-resp.json index 6b68451fd921..0f4dc47c3cb2 100644 --- a/doc/api_samples/os-aggregates/v2.41/aggregates-list-get-resp.json +++ b/doc/api_samples/os-aggregates/v2.41/aggregates-list-get-resp.json @@ -1,7 +1,7 @@ { "aggregates": [ { - "availability_zone": "nova", + "availability_zone": "london", "created_at": "2016-12-27T23:47:32.911515", "deleted": false, "deleted_at": null, @@ -10,11 +10,11 @@ ], "id": 1, "metadata": { - "availability_zone": "nova" + "availability_zone": "london" }, "name": "name", "updated_at": null, "uuid": "6ba28ba7-f29b-45cc-a30b-6e3a40c2fb14" } ] -} \ No newline at end of file +} diff --git a/doc/api_samples/os-aggregates/v2.41/aggregates-metadata-post-resp.json b/doc/api_samples/os-aggregates/v2.41/aggregates-metadata-post-resp.json index 9dda7f83e2b7..e85034f50174 100644 --- a/doc/api_samples/os-aggregates/v2.41/aggregates-metadata-post-resp.json +++ b/doc/api_samples/os-aggregates/v2.41/aggregates-metadata-post-resp.json @@ -1,17 +1,17 @@ { "aggregate": { - "availability_zone": "nova", + "availability_zone": "london", "created_at": "2016-12-27T23:59:18.623100", "deleted": false, "deleted_at": null, "hosts": [], "id": 1, "metadata": { - "availability_zone": "nova", + "availability_zone": "london", "key": "value" }, "name": "name", "updated_at": "2016-12-27T23:59:18.723348", "uuid": "26002bdb-62cc-41bd-813a-0ad22db32625" } -} \ No newline at end of file +} diff --git a/doc/api_samples/os-aggregates/v2.41/aggregates-remove-host-post-resp.json b/doc/api_samples/os-aggregates/v2.41/aggregates-remove-host-post-resp.json index f1fde0d33829..657efe08fb55 100644 --- a/doc/api_samples/os-aggregates/v2.41/aggregates-remove-host-post-resp.json +++ b/doc/api_samples/os-aggregates/v2.41/aggregates-remove-host-post-resp.json @@ -1,16 +1,16 @@ { "aggregate": { - "availability_zone": "nova", + "availability_zone": "london", "created_at": "2016-12-27T23:47:30.594805", "deleted": false, "deleted_at": null, "hosts": [], "id": 1, "metadata": { - "availability_zone": "nova" + "availability_zone": "london" }, "name": "name", "updated_at": null, "uuid": "d1842372-89c5-4fbd-ad5a-5d2e16c85456" } -} \ No newline at end of file +}