Description of problem:

After a number of escalations where our minium requirement for ram and swap have not been followed it has become clear that our current documentation is not explicit enough and customers are deploying cloud in ways that lead to cases and esclations that would otherwise be avoided.

To correct this and ensure that future and exsitng customer do not encounter the same issues we need to make a number of enhancements to our current docs


Version-Release number of selected component (if applicable):
 16.1+



proposed changes

A "important" or "Note" callout should be added to 


https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.2/html-single/recommendations_for_large_deployments/index#assembly-recommended-specifications-for-your-large-openstack-deployment_recommendations-large-deployments

and

https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.2/html/director_installation_and_usage/assembly_planning-your-overcloud


with the following content

"""
Redhat required 16GB of swap on all OSP hosts and recommends increasing that to 64GB on hosts with >64GB of ram. Additional swap is required on all compute node if they have memory overcommit but these minimum must be fulfilled even if memory overcommit is not in use in this deployment. For detail on how to configure swap refer to ...
"""

the tables of requirement in both of those section for the controller and computes
should also have a new line added for swap expiclty


we need to add details to the of how to configure swapfiles to meet this requirement to Chapter 7. Configuring a basic overcloud

https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.2/html/director_installation_and_usage/assembly_configuring-a-basic-overcloud#doc-wrapper

i would add this as a new chapter 7.12
imidealy after 7.11. Creating an environment file that defines node counts and flavors

https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.2/html/director_installation_and_usage/assembly_configuring-a-basic-overcloud#proc_creating-an-environment-file-that-defines-node-counts-and-flavors_basic


the new section should provide an example of confirution our minium required swap on all host of 16GB

we should also add a more detailed chapter in the advance overcloud customisation doc
that captures our recommendation for larger hosts and larger deployments and how to use a swap portion if desired. ooo support configuring swap as a swap file or portion we should prefer the swap file approach and only document that in the basic config but the advance config chapter can document both.

https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.2/html-single/advanced_overcloud_customization/index


finally the existing docs we have for swap

https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.2/html/configuring_the_compute_service_for_instance_creation/assembly_configuring-the-compute-service_osp#ref_calculating-swap-size_configuring-compute

should be enhanced to call out that the swpa requirement for over-commit are in addition to the swap requirement in general.

That section was already meant to be general swap requirements for all nodes but because of where its located we have received feedback that that is not how customer interpret it.

with that addition of the new section on swap we can make this  more targeted to just overcommit.