Merge "Limit the number of Ansible forks used to 10"

doc/source/developer-docs/scripts.rst

@@ -58,6 +58,18 @@ to skip the execution of the Ceilometer playbook, execute:
 
     export DEPLOY_CEILOMETER='no'
 
+The default MaxSessions setting for the OpenSSH Daemon is 10. Each Ansible
+fork makes use of a Session. By default Ansible sets the number of forks to 5,
+but the ``run-playbooks.sh`` script sets the number of forks used based on the
+number of CPU's on the deployment host up to a maximum of 10.
+
+If a developer wishes to increase the number of forks used when using this
+script, override the FORKS environment variable. For example:
+
+.. code-block:: bash
+
+    export FORKS=20
+
 run-tempest.sh
 --------------
 

doc/source/install-guide/app-tips.rst

@@ -0,0 +1,27 @@
+`Home <index.html>`__ OpenStack Ansible Installation Guide
+
+Appendix C. Tips and Tricks
+---------------------------
+
+Ansible Forks
+~~~~~~~~~~~~~
+
+The default MaxSessions setting for the OpenSSH Daemon is 10. Each Ansible
+fork makes use of a Session. By default Ansible sets the number of forks to 5,
+but a deployer may wish to increase the number of forks used in order to
+improve deployment performance in large environments.
+
+This may be done on a permanent basis by adding the `forks`_ configuration
+entry in ``ansible.cfg``, or for a particular playbook execution by using the
+``--forks`` CLI parameter. For example, to execute the
+``os-keystone-install.yml`` playbook using 10 forks:
+
+.. code-block:: bash
+
+    openstack-ansible --forks 10 os-keystone-install.yml
+
+.. _forks: http://docs.ansible.com/ansible/intro_configuration.html#forks
+
+--------------
+
+.. include:: navigation.txt

doc/source/install-guide/index.rst

@@ -60,3 +60,4 @@ Appendices
 
    app-configfiles.rst
    app-resources.rst
+   app-tips.rst

scripts/scripts-library.sh

@@ -23,8 +23,20 @@ REPORT_DATA=${REPORT_DATA:-""}
 ANSIBLE_PARAMETERS=${ANSIBLE_PARAMETERS:-""}
 STARTTIME="${STARTTIME:-$(date +%s)}"
 
-# the number of forks is set as the number of CPU's present
-FORKS=${FORKS:-$(grep -c ^processor /proc/cpuinfo)}
+# The default SSHD configuration has MaxSessions = 10. If a deployer changes
+#  their SSHD config, then the FORKS may be set to a higher number. We set the
+#  value to 10 or the number of CPU's, whichever is less. This is to balance
+#  between performance gains from the higher number, and CPU consumption. If
+#  FORKS is already set to a value, then we leave it alone.
+if [ -z "${FORKS:-}" ]; then
+  CPU_NUM=$(grep -c ^processor /proc/cpuinfo)
+  if [ ${CPU_NUM} -lt "10" ]; then
+    FORKS=${CPU_NUM}
+  else
+    FORKS=10
+  fi
+fi
+
 
 ## Functions -----------------------------------------------------------------
 # Used to retry a process that may fail due to random issues.