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
+}