Clarify the overcloud net_cidr parameter descriptions

These values are ignored in a typical OVB deployment so there is no
need to change them.  Let users know that since we are exposing the
parameters in the sample environments.

doc/source/deploy/baremetal.rst

@@ -59,7 +59,11 @@ method, which creates most of the resources needed automatically.
 
 #. Copy the example env file and edit it to reflect the host environment::
 
-    cp templates/env.yaml.example env.yaml
+   .. note:: Some of the parameters in the base environment file are only
+             used for QuintupleO deployments.  Their values will be ignored
+             in a plain virtual-baremetal deployment.
+
+    cp environments/base.yaml env.yaml
     vi env.yaml
 
 #. Deploy the stack::

doc/source/deploy/quintupleo.rst

@@ -7,15 +7,9 @@ deployment method is able to deploy a full TripleO development environment
 in one command.  It should be useful for non-TripleO users of OVB as well,
 however.
 
-#. Copy the example env file and edit it to reflect the host environment:
+#. Copy the example env file and edit it to reflect the host environment::
 
-   .. note:: QuintupleO environments require a few more configuration
-             parameters to be set.  It also allows enabling a few more
-             features in env.yaml.
-
-   ::
-
-      cp templates/env.yaml.example env.yaml
+      cp environments/base.yaml env.yaml
       vi env.yaml
 
 #. Deploy a QuintupleO stack::
@@ -35,7 +29,10 @@ however.
              file will be ``env-${id}.yaml``.  This new file should be passed
              to build-nodes-json instead of the original.
 
-#. Wait for Heat stack to complete:
+   .. note:: There are a number of
+
+#. Wait for Heat stack to complete.  To make this easier, the ``--poll``
+   option can be passed to ``deploy.py``.
 
    .. note:: The BMC instance does post-deployment configuration that can
              take a while to complete, so the Heat stack completing does
@@ -55,6 +52,10 @@ however.
     bin/build-nodes-json
     scp nodes.json centos@[undercloud floating ip]:~/instackenv.json
 
+   .. note:: Only the base environment file needs to be passed to this command.
+             Additional option environments that may have been passed to the
+             deploy command should *not* be included here.
+
    .. note:: ``build-nodes-json`` also outputs a file named ``bmc_bm_pairs``
              that lists which BMC address corresponds to a given baremetal
              instance.
@@ -64,3 +65,15 @@ however.
              ``--env`` parameter.  Example::
 
                 bin/build-nodes-json --env env-foo.yaml
+
+Advanced Options
+----------------
+
+There are also a number of advanced options that can be enabled for a
+QuintupleO deployment.  For each such option there is a sample environment
+to be passed to the deploy command.
+
+For example, to deploy using the Neutron port-security extension to allow
+DHCP and PXE booting, the following command could be used::
+
+    bin/deploy.py --quintupleo -e env.yaml -e environments/port-security.yaml

environments/all-networks-port-security.yaml

@@ -15,7 +15,8 @@ parameter_defaults:
   # Type: string
   overcloud_internal_net: overcloud_internal
 
-  # CIDR for internal API network subnet
+  # CIDR for internal API network subnet.  This is typically irrelevant and
+  # does not need to be changed.
   # Type: string
   overcloud_internal_net_cidr: 172.17.0.0/24
 
@@ -23,7 +24,8 @@ parameter_defaults:
   # Type: string
   overcloud_storage_mgmt_net: overcloud_storage_mgmt
 
-  # CIDR for storage management network subnet
+  # CIDR for storage management network subnet.  This is typically irrelevant
+  # and does not need to be changed.
   # Type: string
   overcloud_storage_mgmt_net_cidr: 172.19.0.0/24
 
@@ -31,7 +33,8 @@ parameter_defaults:
   # Type: string
   overcloud_storage_net: overcloud_storage
 
-  # CIDR for storage network subnet
+  # CIDR for storage network subnet.  This is typically irrelevant and
+  # does not need to be changed.
   # Type: string
   overcloud_storage_net_cidr: 172.18.0.0/24
 
@@ -39,7 +42,8 @@ parameter_defaults:
   # Type: string
   overcloud_tenant_net: overcloud_tenant
 
-  # CIDR for tenant network subnet
+  # CIDR for tenant network subnet.  This is typically irrelevant and
+  # does not need to be changed.
   # Type: string
   overcloud_tenant_net_cidr: 172.16.0.0/24
 

environments/all-networks-public-bond-port-security.yaml

@@ -17,7 +17,8 @@ parameter_defaults:
   # Type: string
   overcloud_internal_net: overcloud_internal
 
-  # CIDR for internal API network subnet
+  # CIDR for internal API network subnet.  This is typically irrelevant and
+  # does not need to be changed.
   # Type: string
   overcloud_internal_net_cidr: 172.17.0.0/24
 
@@ -25,7 +26,8 @@ parameter_defaults:
   # Type: string
   overcloud_storage_mgmt_net: overcloud_storage_mgmt
 
-  # CIDR for storage management network subnet
+  # CIDR for storage management network subnet.  This is typically irrelevant
+  # and does not need to be changed.
   # Type: string
   overcloud_storage_mgmt_net_cidr: 172.19.0.0/24
 
@@ -33,7 +35,8 @@ parameter_defaults:
   # Type: string
   overcloud_storage_net: overcloud_storage
 
-  # CIDR for storage network subnet
+  # CIDR for storage network subnet.  This is typically irrelevant and
+  # does not need to be changed.
   # Type: string
   overcloud_storage_net_cidr: 172.18.0.0/24
 
@@ -41,7 +44,8 @@ parameter_defaults:
   # Type: string
   overcloud_tenant_net: overcloud_tenant
 
-  # CIDR for tenant network subnet
+  # CIDR for tenant network subnet.  This is typically irrelevant and
+  # does not need to be changed.
   # Type: string
   overcloud_tenant_net_cidr: 172.16.0.0/24
 

environments/all-networks-public-bond.yaml

@@ -15,7 +15,8 @@ parameter_defaults:
   # Type: string
   overcloud_internal_net: overcloud_internal
 
-  # CIDR for internal API network subnet
+  # CIDR for internal API network subnet.  This is typically irrelevant and
+  # does not need to be changed.
   # Type: string
   overcloud_internal_net_cidr: 172.17.0.0/24
 
@@ -23,7 +24,8 @@ parameter_defaults:
   # Type: string
   overcloud_storage_mgmt_net: overcloud_storage_mgmt
 
-  # CIDR for storage management network subnet
+  # CIDR for storage management network subnet.  This is typically irrelevant
+  # and does not need to be changed.
   # Type: string
   overcloud_storage_mgmt_net_cidr: 172.19.0.0/24
 
@@ -31,7 +33,8 @@ parameter_defaults:
   # Type: string
   overcloud_storage_net: overcloud_storage
 
-  # CIDR for storage network subnet
+  # CIDR for storage network subnet.  This is typically irrelevant and
+  # does not need to be changed.
   # Type: string
   overcloud_storage_net_cidr: 172.18.0.0/24
 
@@ -39,7 +42,8 @@ parameter_defaults:
   # Type: string
   overcloud_tenant_net: overcloud_tenant
 
-  # CIDR for tenant network subnet
+  # CIDR for tenant network subnet.  This is typically irrelevant and
+  # does not need to be changed.
   # Type: string
   overcloud_tenant_net_cidr: 172.16.0.0/24
 

environments/all-networks.yaml

@@ -13,7 +13,8 @@ parameter_defaults:
   # Type: string
   overcloud_internal_net: overcloud_internal
 
-  # CIDR for internal API network subnet
+  # CIDR for internal API network subnet.  This is typically irrelevant and
+  # does not need to be changed.
   # Type: string
   overcloud_internal_net_cidr: 172.17.0.0/24
 
@@ -21,7 +22,8 @@ parameter_defaults:
   # Type: string
   overcloud_storage_mgmt_net: overcloud_storage_mgmt
 
-  # CIDR for storage management network subnet
+  # CIDR for storage management network subnet.  This is typically irrelevant
+  # and does not need to be changed.
   # Type: string
   overcloud_storage_mgmt_net_cidr: 172.19.0.0/24
 
@@ -29,7 +31,8 @@ parameter_defaults:
   # Type: string
   overcloud_storage_net: overcloud_storage
 
-  # CIDR for storage network subnet
+  # CIDR for storage network subnet.  This is typically irrelevant and
+  # does not need to be changed.
   # Type: string
   overcloud_storage_net_cidr: 172.18.0.0/24
 
@@ -37,7 +40,8 @@ parameter_defaults:
   # Type: string
   overcloud_tenant_net: overcloud_tenant
 
-  # CIDR for tenant network subnet
+  # CIDR for tenant network subnet.  This is typically irrelevant and
+  # does not need to be changed.
   # Type: string
   overcloud_tenant_net_cidr: 172.16.0.0/24
 

templates/baremetal-networks-all.yaml

@@ -11,7 +11,9 @@ parameters:
 
   overcloud_internal_net_cidr:
     type: string
-    description: CIDR for internal API network subnet
+    description: |
+      CIDR for internal API network subnet.  This is typically irrelevant and
+      does not need to be changed.
     default: 172.17.0.0/24
 
   overcloud_storage_net:
@@ -21,7 +23,9 @@ parameters:
 
   overcloud_storage_net_cidr:
     type: string
-    description: CIDR for storage network subnet
+    description: |
+      CIDR for storage network subnet.  This is typically irrelevant and
+      does not need to be changed.
     default: 172.18.0.0/24
 
   overcloud_storage_mgmt_net:
@@ -31,7 +35,9 @@ parameters:
 
   overcloud_storage_mgmt_net_cidr:
     type: string
-    description: CIDR for storage management network subnet
+    description: |
+      CIDR for storage management network subnet.  This is typically irrelevant
+      and does not need to be changed.
     default: 172.19.0.0/24
 
   overcloud_tenant_net:
@@ -41,7 +47,9 @@ parameters:
 
   overcloud_tenant_net_cidr:
     type: string
-    description: CIDR for tenant network subnet
+    description: |
+      CIDR for tenant network subnet.  This is typically irrelevant and
+      does not need to be changed.
     default: 172.16.0.0/24
 
 resources: