Document connection types (#15155)

* first description of non ssh based connection types

* fixed formatting

docsite/rst/intro_inventory.rst

@@ -7,7 +7,7 @@ Inventory
 
 Ansible works against multiple systems in your infrastructure at the
 same time.  It does this by selecting portions of systems listed in
-Ansible's inventory file, which defaults to being saved in 
+Ansible's inventory file, which defaults to being saved in
 the location /etc/ansible/hosts.
 
 Not only is this inventory configurable, but you can also use
@@ -35,7 +35,7 @@ The format for /etc/ansible/hosts is an INI-like format and looks like this::
 The things in brackets are group names, which are used in classifying systems
 and deciding what systems you are controlling at what times and for what purpose.
 
-It is ok to put systems in more than one group, for instance a server could be both a webserver and a dbserver.  
+It is ok to put systems in more than one group, for instance a server could be both a webserver and a dbserver.
 If you do, note that variables will come from all of the groups they are a member of, and variable precedence is detailed in a later chapter.
 
 If you have hosts that run on non-standard SSH ports you can put the port number
@@ -149,7 +149,7 @@ The preferred practice in Ansible is actually not to store variables in the main
 
 In addition to storing variables directly in the INI file, host
 and group variables can be stored in individual files relative to the
-inventory file.  
+inventory file.
 
 These variable files are in YAML format. Valid file extensions include '.yml', '.yaml', '.json',
 or no file extension. See :doc:`YAMLSyntax` if you are new to YAML.
@@ -203,7 +203,7 @@ As alluded to above, setting the following variables controls how ansible intera
 Host connection:
 
 ansible_connection
-    Connection type to the host. This can be the name of any of ansible's connection plugins.  Common connection types are local, smart, ssh or paramiko.  The default is smart.
+    Connection type to the host. This can be the name of any of ansible's connection plugins. SSH protocol types are smart, ssh or paramiko.  The default is smart. Non-SSH based types are described in the next section.
 
 
 .. include:: ansible_ssh_changes_note.rst
@@ -276,6 +276,50 @@ Examples from a host file::
   freebsd_host      ansible_python_interpreter=/usr/local/bin/python
   ruby_module_host  ansible_ruby_interpreter=/usr/bin/ruby.1.9.3
 
+Non-SSH connection types
+++++++++++++++++++++++++
+
+As stated in the previous section, Ansible is executing playbooks over SSH but is not limited to.
+With the host specific parameter ``ansible_connection=<connector>`` the connection type can be changed.
+Following non SSH based connectors are available:
+
+**local**
+
+This connector can be used to deploy the playbook to the control machine itself.
+
+**docker**
+
+This connector deploys the playbook directly into Docker containers using the local Docker client. Following parameters are processed by this connector:
+
+ansible_host
+    The name of the Docker container to connect to.
+ansible_user
+    The user name to operate within the container. The user must exist inside the container.
+ansible_become
+    If set to ``true`` the ``become_user`` will be used to operate within the container.
+ansible_docker_extra_args
+    Could be a string with any additional arguments understood by Docker, which are not command specific. This parameter is mainly used to configure a remote Docker daemon to use.
+
+Here an example of how to instantly depoloy to created containers::
+
+  - name: create jenkins container
+    docker:
+      name: my_jenkins
+      image: jenkins
+
+  - name: add container to inventory
+    add_host:
+      name: my_jenkins
+      ansible_connection: docker
+      ansible_docker_extra_args: "--tlsverify --tlscacert=/path/to/ca.pem --tlscert=/path/to/client-cert.pem --tlskey=/path/to/client-key.pem -H=tcp://myserver.net:4243"
+      ansible_user: jenkins
+    changed_when: false
+
+  - name: create directory for ssh keys
+    delegate_to: my_jenkins
+    file:
+      path: "/var/jenkins_home/.ssh/jupiter"
+      state: directory
 
 .. seealso::
 
@@ -289,4 +333,3 @@ Examples from a host file::
        Questions? Help? Ideas?  Stop by the list on Google Groups
    `irc.freenode.net <http://irc.freenode.net>`_
        #ansible IRC chat channel
-