diff --git a/doc/source/developer-docs/scripts.rst b/doc/source/developer-docs/scripts.rst index 06caa77388..3dad43058c 100644 --- a/doc/source/developer-docs/scripts.rst +++ b/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 -------------- diff --git a/doc/source/install-guide/app-tips.rst b/doc/source/install-guide/app-tips.rst index a3533f884a..3ece753053 100644 --- a/doc/source/install-guide/app-tips.rst +++ b/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 -------------- diff --git a/releasenotes/notes/ansible-forks-fa70caf5155c5d25.yaml b/releasenotes/notes/ansible-forks-fa70caf5155c5d25.yaml new file mode 100644 index 0000000000..7c038484b3 --- /dev/null +++ b/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. diff --git a/scripts/scripts-library.sh b/scripts/scripts-library.sh index 10fad128e3..906db64e9d 100755 --- a/scripts/scripts-library.sh +++ b/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 {