From fe3b328023b946413a675a0ffdbafcad353aca44 Mon Sep 17 00:00:00 2001
From: Jesse Pretorius <jesse.pretorius@rackspace.co.uk>
Date: Thu, 1 Oct 2015 10:12:03 +0100
Subject: [PATCH] Limit the number of Ansible forks used to 10

The default MaxSessions setting for SSHD is 10. Each Ansible fork makes use of
a Session, so this patch still uses the CPU number to set the number of forks
used but limits it to 10 forks when the number of CPU's is larger.

Developer Docs and Install Guide Docs entries have been included.

Closes-Bug: #1479812
Change-Id: I9abd33e184c706796ede9963393876a8aae9837c
---
 doc/source/developer-docs/scripts.rst | 12 ++++++++++++
 doc/source/install-guide/app-tips.rst | 27 +++++++++++++++++++++++++++
 doc/source/install-guide/index.rst    |  1 +
 scripts/scripts-library.sh            | 16 ++++++++++++++--
 4 files changed, 54 insertions(+), 2 deletions(-)
 create mode 100644 doc/source/install-guide/app-tips.rst

diff --git a/doc/source/developer-docs/scripts.rst b/doc/source/developer-docs/scripts.rst
index 2d4f7424cd..bc4d27ef94 100644
--- a/doc/source/developer-docs/scripts.rst
+++ b/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
 --------------
 
diff --git a/doc/source/install-guide/app-tips.rst b/doc/source/install-guide/app-tips.rst
new file mode 100644
index 0000000000..2a31b3b460
--- /dev/null
+++ b/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
diff --git a/doc/source/install-guide/index.rst b/doc/source/install-guide/index.rst
index 843c44f730..30f8e4f72f 100644
--- a/doc/source/install-guide/index.rst
+++ b/doc/source/install-guide/index.rst
@@ -60,3 +60,4 @@ Appendices
 
    app-configfiles.rst
    app-resources.rst
+   app-tips.rst
diff --git a/scripts/scripts-library.sh b/scripts/scripts-library.sh
index 5bd169c66e..73f519d999 100755
--- a/scripts/scripts-library.sh
+++ b/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.