Add notes for better UX with subsequent updates/upgrades

When assuming subsequent update/upgrade of deployments in the
context:
* Place a note for overcloud deploy commands to always contain
full environments.
* Note as well an alternative resource for the
OS::TripleO::NodeUserData is the OS::TripleO::NodeExtraConfigPost.

Change-Id: Iec834320c04be509761ec45483fa9c9708505f21
Signed-off-by: Bogdan Dobrelya <bdobreli@redhat.com>

doc/source/install/advanced_deployment/deploy_manila.rst

@@ -15,6 +15,11 @@ Overcloud::
     -e /usr/share/openstack-tripleo-heat-templates/environments/services/ceph-mds.yaml \
     -e /usr/share/openstack-tripleo-heat-templates/environments/manila-cephfsnative-config.yaml
 
+.. note::
+   These and any other environment files or options passed to the overcloud
+   deploy command, are referenced below as the "full environment". We assumed
+   the ``--plan`` flag is not what we want to use for this example.
+
 Network Isolation
 ~~~~~~~~~~~~~~~~~
 When mounting a ceph share from a user instance, the user instance needs access
@@ -145,9 +150,10 @@ Deploying the Overcloud with an External Backend
 
 #. Continue following the TripleO instructions for deploying an overcloud.
    Before entering the command to deploy the overcloud, add the environment
-   file that you just configured as an argument::
+   file that you just configured as an argument. For example::
 
-    openstack overcloud deploy --templates -e ~/manila-[generic or netapp]-config.yaml
+    openstack overcloud deploy --templates \
+      -e <full environment> -e ~/manila-[generic or netapp]-config.yaml
 
 #. Wait for the completion of the overcloud deployment process.
 

doc/source/install/advanced_deployment/extra_config.rst

@@ -84,11 +84,18 @@ via a heat environment file::
 
 You may then deploy your overcloud referencing the additional environment file::
 
-    openstack overcloud deploy --templates -e userdata_env.yaml
+    openstack overcloud deploy --templates \
+      -e <full environment> -e userdata_env.yaml
 
 .. note::
 
-    The userdata is applied to *all* nodes in the deployment.  If you need role
+    Make sure you pass the same environment parameters that were used at
+    deployment time in addition to your customization environments at the
+    end (`userdata_env.yaml`).
+
+.. note::
+
+    The userdata is applied to *all* nodes in the deployment. If you need role
     specific logic, the userdata scripts can contain conditionals which use
     e.g the node hostname to determine the role.
 
@@ -96,7 +103,9 @@ You may then deploy your overcloud referencing the additional environment file::
 
     OS::TripleO::NodeUserData is only applied on initial node deployment,
     not on any subsequent stack update, because cloud-init only processes the
-    nova user-data once, on first boot.
+    nova user-data once, on first boot. If you need to add custom configuration
+    that runs on all stack creates and updates, see the
+    `Post-Deploy extra configuration`_ section below.
 
 For a more complete example, which creates an additional user and configures
 SSH keys by accessing the nova metadata server, see
@@ -108,7 +117,7 @@ on the undercloud node or the tripleo-heat-templates_ repo.
 Per-node extra configuration
 ----------------------------
 
-This configuration happens after after any "firstboot" configuration is applied,
+This configuration happens after any "firstboot" configuration is applied,
 but before any Post-Deploy configuration takes place.
 
 Typically these interfaces are suitable for preparing each node for service
@@ -263,4 +272,5 @@ The extra config may be enabled via an environment file::
 
 You may then deploy your overcloud referencing the additional environment file::
 
-    openstack overcloud deploy --templates -e post_config_env.yaml
+    openstack overcloud deploy --templates \
+      -e <full environment> -e post_config_env.yaml

doc/source/install/advanced_deployment/security_hardening.rst

@@ -4,6 +4,12 @@ Security Hardening
 TripleO can deploy Overcloud nodes with various Security Hardening values
 passed in as environment files to the ``openstack overcloud deploy`` command.
 
+.. note::
+   It is especially important to remember that you **must** include all
+   environment files needed to deploy the overcloud. Make sure
+   you pass the full environment in addition to your customization environments
+   at the end of each of the ``openstack overcloud deploy`` command.
+
 Horizon Password Validation
 ---------------------------
 
@@ -23,7 +29,8 @@ characters in length::
 If the above yaml was saved as ``horizon_password.yaml`` we can then pass this
 into the overcloud deploy command as follows::
 
-    openstack overcloud deploy --templates -e  horizon_password.yaml
+    openstack overcloud deploy --templates \
+      -e <full environment> -e  horizon_password.yaml
 
 Default Security Values in Horzion
 ----------------------------------
@@ -99,7 +106,8 @@ As with the previous Horizon Password Validation example, saving the above into
 a yaml file, will allow passing the aforementioned parameters into the overcloud
 deploy command::
 
-    openstack overcloud deploy --templates -e  ssh_banner.yaml
+    openstack overcloud deploy --templates \
+      -e <full environment> -e  ssh_banner.yaml
 
 Audit
 -----

doc/source/install/post_deployment/scale_roles.rst

@@ -13,7 +13,14 @@ first an environment file should be created::
 
 Then following command can be used to deploy it::
 
-    openstack overcloud deploy --templates [templates dir] -e ~/environment.yaml
+    openstack overcloud deploy --templates [templates dir] \
+      -e <full environment> -e ~/environment.yaml
+
+.. note::
+   It is especially important to remember that you **must** include all
+   environment files that were used to deploy the overcloud. Make sure
+   you pass those in addition to your customization environments at the
+   end (`environment.yaml`).
 
 .. note::
    Scaling out assumes that newly added nodes has already been