Update docs for shell-type driver config

Change-Id: I08aa454ed55992f444a602abc2d52777edb7daac

doc/source/aws.rst

@@ -194,11 +194,15 @@ section of the configuration.
          :default: sh
 
          The shell type of the node's default shell executable. Used by Zuul
-         to set ``ansible_shell_type``.  This setting should not be used
-         unless the default shell is a non-Bourne (sh) compatible shell, e.g
-         ``csh`` or ``fish``. For a windows image with the experimental
-         `connection-type` ``ssh``, ``cmd`` or ``powershell`` should be set
+         to set ``ansible_shell_type``. This setting should only be used
+
+         - For a windows image with the experimental `connection-type` ``ssh``
+           in which case ``cmd`` or ``powershell`` should be set
            and reflect the node's ``DefaultShell`` configuration.
+         - If the default shell is not Bourne compatible (sh), but instead
+           e.g. ``csh`` or ``fish``, and the user is aware that there is a
+           long-standing issue with ``ansible_shell_type`` in combination
+           with ``become``
 
    .. attr:: pools
       :type: list

doc/source/gce.rst

@@ -158,11 +158,15 @@ section of the configuration.
          :default: sh
 
          The shell type of the node's default shell executable. Used by Zuul
-         to set ``ansible_shell_type``.  This setting should not be used
-         unless the default shell is a non-Bourne (sh) compatible shell, e.g.
-         ``csh`` or ``fish``. For a windows image with the experimental
-         `connection-type` ``ssh``, ``cmd`` or ``powershell`` should be set
+         to set ``ansible_shell_type``. This setting should only be used
+
+         - For a windows image with the experimental `connection-type` ``ssh``
+           in which case ``cmd`` or ``powershell`` should be set
            and reflect the node's ``DefaultShell`` configuration.
+         - If the default shell is not Bourne compatible (sh), but instead
+           e.g. ``csh`` or ``fish``, and the user is aware that there is a
+           long-standing issue with ``ansible_shell_type`` in combination
+           with ``become``
 
       .. attr:: connection-type
          :type: str

doc/source/kubernetes.rst

@@ -135,11 +135,15 @@ Selecting the kubernetes driver adds the following options to the
             :default: sh
 
             The shell type of the node's default shell executable. Used by Zuul
-            to set ``ansible_shell_type``.  This setting should not be used
-            unless the default shell is a non-Bourne (sh) compatible shell, e.g.
-            ``csh`` or ``fish``. For a windows image with the experimental
-            `connection-type` ``ssh``, ``cmd`` or ``powershell`` should be set
+            to set ``ansible_shell_type``. This setting should only be used
+
+            - For a windows pod with the experimental `connection-type`
+              ``ssh``, in which case ``cmd`` or ``powershell`` should be set
               and reflect the node's ``DefaultShell`` configuration.
+            - If the default shell is not Bourne compatible (sh), but instead
+              e.g. ``csh`` or ``fish``, and the user is aware that there is a
+              long-standing issue with ``ansible_shell_type`` in combination
+              with ``become``
 
          .. attr:: cpu
             :type: int

doc/source/openshift-pods.rst

@@ -116,11 +116,15 @@ Selecting the openshift pods driver adds the following options to the
          :default: sh
 
          The shell type of the node's default shell executable. Used by Zuul
-         to set ``ansible_shell_type``.  This setting should not be used
-         unless the default shell is a non-Bourne (sh) compatible shell, e.g
-         ``csh`` or ``fish``. For a windows node with the experimental
-         `connection-type` ``ssh``, ``cmd`` or ``powershell`` should be set
+         to set ``ansible_shell_type``. This setting should only be used
+
+         - For a windows pod with the experimental `connection-type`
+           ``ssh``, in which case ``cmd`` or ``powershell`` should be set
            and reflect the node's ``DefaultShell`` configuration.
+         - If the default shell is not Bourne compatible (sh), but instead
+           e.g. ``csh`` or ``fish``, and the user is aware that there is a
+           long-standing issue with ``ansible_shell_type`` in combination
+           with ``become``
 
       .. attr:: env
          :type: list

doc/source/openshift.rst

@@ -143,11 +143,15 @@ Selecting the openshift driver adds the following options to the
          :default: sh
 
          The shell type of the node's default shell executable. Used by Zuul
-         to set ``ansible_shell_type``.  This setting should not be used
-         unless the default shell is a non-Bourne (sh) compatible shell, e.g
-         ``csh`` or ``fish``. For a windows image with the experimental
-         `connection-type` ``ssh``, ``cmd`` or ``powershell`` should be set
+         to set ``ansible_shell_type``. This setting should only be used
+
+         - For a windows image with the experimental `connection-type`
+           ``ssh``, in which case ``cmd`` or ``powershell`` should be set
            and reflect the node's ``DefaultShell`` configuration.
+         - If the default shell is not Bourne compatible (sh), but instead
+           e.g. ``csh`` or ``fish``, and the user is aware that there is a
+           long-standing issue with ``ansible_shell_type`` in combination
+           with ``become``
 
       .. attr:: cpu
          :type: int

doc/source/openstack.rst

@@ -352,11 +352,15 @@ Selecting the OpenStack driver adds the following options to the
         :default: sh
 
         The shell type of the node's default shell executable. Used by Zuul
-        to set ``ansible_shell_type``.  This setting should not be used
-        unless the default shell is a non-Bourne (sh) compatible shell, e.g
-        ``csh`` or ``fish``. For a windows image with the experimental
-        `connection-type` ``ssh``, ``cmd`` or ``powershell`` should be set
+        to set ``ansible_shell_type``. This setting should only be used
+
+        - For a windows image with the experimental `connection-type`
+          ``ssh``, in which case ``cmd`` or ``powershell`` should be set
           and reflect the node's ``DefaultShell`` configuration.
+        - If the default shell is not Bourne compatible (sh), but instead
+          e.g. ``csh`` or ``fish``, and the user is aware that there is a
+          long-standing issue with ``ansible_shell_type`` in combination
+          with ``become``
 
      .. attr:: connection-type
         :type: str

doc/source/static.rst

@@ -150,11 +150,15 @@ Selecting the static driver adds the following options to the
             :default: sh
 
             The shell type of the node's default shell executable. Used by Zuul
-            to set ``ansible_shell_type``.  This setting should not be used
-            unless the default shell is a non-Bourne (sh) compatible shell, e.g
-            ``csh`` or ``fish``. For a windows node with the experimental
-            `connection-type` ``ssh``, ``cmd`` or ``powershell`` should be set
+            to set ``ansible_shell_type``. This setting should only be used
+
+            - For a windows node with the experimental `connection-type`
+              ``ssh``, in which case ``cmd`` or ``powershell`` should be set
               and reflect the node's ``DefaultShell`` configuration.
+            - If the default shell is not Bourne compatible (sh), but instead
+              e.g. ``csh`` or ``fish``, and the user is aware that there is a
+              long-standing issue with ``ansible_shell_type`` in combination
+              with ``become``
 
          .. attr:: max-parallel-jobs
             :type: int

releasenotes/notes/shell-type-config-ee83971f4cdae0d9.yaml

@@ -0,0 +1,11 @@
+---
+features:
+  - |
+    AWS EC2, GCE, Kubernetes, Openshift, Openshift Pods, OpenStack and Static
+    drivers now support a shell-type config. Shell-type config is intended
+    to enable setting of cmd or powershell as shell type for Windows workers
+    with connection-type ssh.
+
+    For Linux workers, there is a long standing ansible issue with using
+    non-default shell type and become, so care should be taken if using
+    it for such workers.