Revert "Revert "Fix AZ related API docs""

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. This reverts commit 92ca21abd6. Co-Authored-By: Sylvain Bauza <sbauza@redhat.com> Co-Authored-By: Stephen Finucane <stephenfin@redhat.com> Change-Id: Ie4bfe32bbef0f8060bfc0ad4190f262d4a8bd3b2
2017-09-10 18:24:33 +00:00 · 2017-09-10 18:24:33 +00:00 · f657efcdc5
parent 92ca21abd6
commit f657efcdc5
28 changed files with 67 additions and 58 deletions
--- 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
--- 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"
    }
-}
+}
--- 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,
--- 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
--- 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
--- 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
--- 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",
--- 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
--- 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"
    }
-}
+}
--- 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"
    }
-}
+}
--- 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"
    }
-}
+}
--- 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"
        }
    ]
-}
+}
--- 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"
    }
-}
+}
--- 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"
    }
-}
+}
--- a/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/aggregate-post-req.json.tpl
+++ b/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/aggregate-post-req.json.tpl
@ -2,6 +2,6 @@
    "aggregate":
    {
        "name": "name",
-        "availability_zone": "nova"
+        "availability_zone": "london"
    }
 }
--- a/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/aggregate-post-resp.json.tpl
+++ b/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/aggregate-post-resp.json.tpl
@ -1,6 +1,6 @@
 {
    "aggregate": {
-        "availability_zone": "nova",
+        "availability_zone": "london",
        "created_at": "%(strtime)s",
        "deleted": false,
        "deleted_at": null,
--- a/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/aggregates-add-host-post-resp.json.tpl
+++ b/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/aggregates-add-host-post-resp.json.tpl
@ -1,6 +1,6 @@
 {
    "aggregate": {
-        "availability_zone": "nova",
+        "availability_zone": "london",
        "created_at": "%(strtime)s",
        "deleted": false,
        "deleted_at": null,
@ -9,7 +9,7 @@
        ],
        "id": 1,
        "metadata": {
-            "availability_zone": "nova"
+            "availability_zone": "london"
        },
        "name": "name",
        "updated_at": null
--- a/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/aggregates-get-resp.json.tpl
+++ b/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/aggregates-get-resp.json.tpl
@ -1,13 +1,13 @@
 {
    "aggregate": {
-        "availability_zone": "nova",
+        "availability_zone": "london",
        "created_at": "%(strtime)s",
        "deleted": false,
        "deleted_at": null,
        "hosts": [],
        "id": 1,
        "metadata": {
-            "availability_zone": "nova"
+            "availability_zone": "london"
        },
        "name": "name",
        "updated_at": null
--- a/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/aggregates-list-get-resp.json.tpl
+++ b/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/aggregates-list-get-resp.json.tpl
@ -1,7 +1,7 @@
 {
    "aggregates": [
        {
-            "availability_zone": "nova",
+            "availability_zone": "london",
            "created_at": "%(strtime)s",
            "deleted": false,
            "deleted_at": null,
@ -10,7 +10,7 @@
            ],
            "id": 1,
            "metadata": {
-                "availability_zone": "nova"
+                "availability_zone": "london"
            },
            "name": "name",
            "updated_at": null
--- a/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/aggregates-metadata-post-resp.json.tpl
+++ b/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/aggregates-metadata-post-resp.json.tpl
@ -1,13 +1,13 @@
 {
    "aggregate": {
-        "availability_zone": "nova",
+        "availability_zone": "london",
        "created_at": "%(strtime)s",
        "deleted": false,
        "deleted_at": null,
        "hosts": [],
        "id": 1,
        "metadata": {
-            "availability_zone": "nova",
+            "availability_zone": "london",
            "key": "value"
        },
        "name": "name",
--- a/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/aggregates-remove-host-post-resp.json.tpl
+++ b/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/aggregates-remove-host-post-resp.json.tpl
@ -1,13 +1,13 @@
 {
    "aggregate": {
-        "availability_zone": "nova",
+        "availability_zone": "london",
        "created_at": "%(strtime)s",
        "deleted": false,
        "deleted_at": null,
        "hosts": [],
        "id": 1,
        "metadata": {
-            "availability_zone": "nova"
+            "availability_zone": "london"
        },
        "name": "name",
        "updated_at": null
--- a/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/v2.41/aggregate-post-req.json.tpl
+++ b/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/v2.41/aggregate-post-req.json.tpl
@ -2,6 +2,6 @@
    "aggregate":
    {
        "name": "name",
-        "availability_zone": "nova"
+        "availability_zone": "london"
    }
 }
--- a/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/v2.41/aggregate-post-resp.json.tpl
+++ b/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/v2.41/aggregate-post-resp.json.tpl
@ -1,6 +1,6 @@
 {
    "aggregate": {
-        "availability_zone": "nova",
+        "availability_zone": "london",
        "created_at": "%(strtime)s",
        "deleted": false,
        "deleted_at": null,
--- a/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/v2.41/aggregates-add-host-post-resp.json.tpl
+++ b/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/v2.41/aggregates-add-host-post-resp.json.tpl
@ -1,6 +1,6 @@
 {
    "aggregate": {
-        "availability_zone": "nova",
+        "availability_zone": "london",
        "created_at": "%(strtime)s",
        "deleted": false,
        "deleted_at": null,
@ -9,7 +9,7 @@
        ],
        "id": 1,
        "metadata": {
-            "availability_zone": "nova"
+            "availability_zone": "london"
        },
        "name": "name",
        "updated_at": null,
--- a/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/v2.41/aggregates-get-resp.json.tpl
+++ b/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/v2.41/aggregates-get-resp.json.tpl
@ -1,13 +1,13 @@
 {
    "aggregate": {
-        "availability_zone": "nova",
+        "availability_zone": "london",
        "created_at": "%(strtime)s",
        "deleted": false,
        "deleted_at": null,
        "hosts": [],
        "id": 1,
        "metadata": {
-            "availability_zone": "nova"
+            "availability_zone": "london"
        },
        "name": "name",
        "updated_at": null,
--- a/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/v2.41/aggregates-list-get-resp.json.tpl
+++ b/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/v2.41/aggregates-list-get-resp.json.tpl
@ -1,7 +1,7 @@
 {
    "aggregates": [
        {
-            "availability_zone": "nova",
+            "availability_zone": "london",
            "created_at": "%(strtime)s",
            "deleted": false,
            "deleted_at": null,
@ -10,7 +10,7 @@
            ],
            "id": 1,
            "metadata": {
-                "availability_zone": "nova"
+                "availability_zone": "london"
            },
            "name": "name",
            "updated_at": null,
--- a/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/v2.41/aggregates-metadata-post-resp.json.tpl
+++ b/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/v2.41/aggregates-metadata-post-resp.json.tpl
@ -1,13 +1,13 @@
 {
    "aggregate": {
-        "availability_zone": "nova",
+        "availability_zone": "london",
        "created_at": "%(strtime)s",
        "deleted": false,
        "deleted_at": null,
        "hosts": [],
        "id": 1,
        "metadata": {
-            "availability_zone": "nova",
+            "availability_zone": "london",
            "key": "value"
        },
        "name": "name",
--- a/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/v2.41/aggregates-remove-host-post-resp.json.tpl
+++ b/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/v2.41/aggregates-remove-host-post-resp.json.tpl
@ -1,13 +1,13 @@
 {
    "aggregate": {
-        "availability_zone": "nova",
+        "availability_zone": "london",
        "created_at": "%(strtime)s",
        "deleted": false,
        "deleted_at": null,
        "hosts": [],
        "id": 1,
        "metadata": {
-            "availability_zone": "nova"
+            "availability_zone": "london"
        },
        "name": "name",
        "updated_at": null,