Change to using ANSIBLE_FORKS and update related tip

Instead of using a custom 'FORKS' parameter, this patch switches
to using the standard Ansible environment variable 'ANSIBLE_FORKS'.

The patch also updates the documentation related to forks to use
the right parameter and also to give better examples.

Change-Id: I7fcf152ee945c17bd8c9f6d4ff111805e9e2d0b8

doc/source/developer-docs/scripts.rst

@@ -73,11 +73,11 @@ 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:
+script, override the ANSIBLE_FORKS environment variable. For example:
 
 .. code-block:: bash
 
-    export FORKS=20
+    export ANSIBLE_FORKS=20
 
 run-tempest.sh
 --------------

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

@@ -8,20 +8,36 @@ 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.
-However, you can increase the number of forks used in order to improve deployment
-performance in large environments.
+fork makes use of a Session. By default, Ansible sets the number of forks to
+5. However, you can 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:
+Note that a number of forks larger than 10 will cause issues for any playbooks
+which make use of ``delegate_to`` or ``local_action`` in the tasks. It is
+recommended that the number of forks are not raised when executing against the
+Control Plane, as this is where delegation is most often used.
+
+The number of forks used may be changed on a permanent basis by including
+the appropriate change to the ``ANSIBLE_FORKS`` in your ``.bashrc`` file.
+Alternatively it can be changed for a particular playbook execution by using
+the ``--forks`` CLI parameter. For example, the following executes the nova
+playbook against the control plane with 10 forks, then against the compute
+nodes with 50 forks.
 
 .. code-block:: shell-session
 
-    # openstack-ansible --forks 10 os-keystone-install.yml
+    # openstack-ansible --forks 10 os-nova-install.yml --limit compute_containers
+    # openstack-ansible --forks 50 os-nova-install.yml --limit compute_hosts
 
+For more information about forks, please see the following references:
+
+* OpenStack-Ansible `Bug 1479812`_
+* Ansible `forks`_ entry for ansible.cfg
+* `Ansible Performance Tuning`_
+
+.. _Bug 1479812: https://bugs.launchpad.net/openstack-ansible/+bug/1479812
 .. _forks: http://docs.ansible.com/ansible/intro_configuration.html#forks
+.. _Ansible Performance Tuning: https://www.ansible.com/blog/ansible-performance-tuning
 
 --------------
 

releasenotes/notes/ansible-forks-fa70caf5155c5d25.yaml

@@ -0,0 +1,4 @@
+---
+upgrade:
+  - The environment variable ``FORKS`` is no longer used. The standard
+    Ansible environment variable ``ANSIBLE_FORKS`` should be used instead.

scripts/scripts-library.sh

@@ -24,16 +24,18 @@ STARTTIME="${STARTTIME:-$(date +%s)}"
 PIP_INSTALL_OPTIONS=${PIP_INSTALL_OPTIONS:-'pip==8.1.1 setuptools==20.9.0 wheel==0.29.0 '}
 
 # 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
+#  their SSHD config, then the ANSIBLE_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 ANSIBLE_FORKS is already set to a value, then we leave it
+#  alone.
+#  ref: https://bugs.launchpad.net/openstack-ansible/+bug/1479812
+if [ -z "${ANSIBLE_FORKS:-}" ]; then
   CPU_NUM=$(grep -c ^processor /proc/cpuinfo)
   if [ ${CPU_NUM} -lt "10" ]; then
-    FORKS=${CPU_NUM}
+    ANSIBLE_FORKS=${CPU_NUM}
   else
-    FORKS=10
+    ANSIBLE_FORKS=10
   fi
 fi
 
@@ -67,9 +69,8 @@ function successerator {
 }
 
 function install_bits {
-  # Use the successerator to run openstack-ansible with
-  # the appropriate number of forks
-  successerator openstack-ansible ${ANSIBLE_PARAMETERS} --forks ${FORKS} $@
+  # Use the successerator to run openstack-ansible
+  successerator openstack-ansible ${ANSIBLE_PARAMETERS} $@
 }
 
 function ssh_key_create {