diff --git a/doc/source/deploy/drivers.rst b/doc/source/deploy/drivers.rst
index c14f6dd1aa..370dbbcd0c 100644
--- a/doc/source/deploy/drivers.rst
+++ b/doc/source/deploy/drivers.rst
@@ -7,19 +7,11 @@ Enabling drivers
 Ironic-Python-Agent (agent)
 ---------------------------
 
-To enable IPA, add the appropriate ironic agent driver to the ``enabled_drivers``
-line of the ironic.conf file.
+Ironic-Python-Agent is an agent that handles *ironic* bare metal
+nodes in various actions such as inspection and deployment of such
+nodes, and runs processes inside of a ramdisk.
 
-Several variants are currently supported, they are:
-    * agent_ilo
-    * agent_ipmitool
-    * agent_pyghmi
-    * agent_ssh
-    * agent_vbox
-
-.. note:: Starting with the Kilo release IPA ramdisk may also be used with ironic PXE drivers.
-
-For more information see the `ironic-python-agent GitHub repo <https://github.com/openstack/ironic-python-agent/>`_
+For more information on this, see :ref:`IPA`.
 
 DRAC
 ----
diff --git a/doc/source/deploy/user-guide.rst b/doc/source/deploy/user-guide.rst
index 0681ef54f7..b586379eae 100644
--- a/doc/source/deploy/user-guide.rst
+++ b/doc/source/deploy/user-guide.rst
@@ -211,6 +211,13 @@ Deploy Process
 #. Images from Glance are pulled down to the local disk of the Ironic
    conductor servicing the bare metal node.
 
+   #. For pxe_* drivers these include all images: both the deploy ramdisk and
+      user instance images.
+
+   #. For agent_* drivers only the deploy ramdisk is stored locally. Temporary
+      URLs in OpenStack's Object Storage service are created for user instance
+      images.
+
 #. Virtual interfaces are plugged in and Neutron API updates DHCP port to
    support PXE/TFTP options.
 
@@ -222,10 +229,16 @@ Deploy Process
 #. The IPMI driver issues command to enable network boot of a node and power
    it on.
 
-#. The DHCP boots the deploy ramdisk. The PXE driver actually copies the image
-   over iSCSI to the physical node. It connects to the iSCSI end point,
-   partitions volume, "dd" the image and closes the iSCSI connection. The
-   deployment is done. The Ironic conductor will switch pxe config to service
+#. The DHCP boots the deploy ramdisk. Next, depending on the exact driver
+   used, either the conductor copies the image over iSCSI to the physical node
+   (pxe_* group of drivers) or the deploy ramdisk downloads the image from
+   a temporary URL (agent_* group of drivers), which can be generated by
+   a variety of object stores, e.g. *swift*, *radosgw*, etc, and uploaded
+   to OpenStack's Object Storage service. In the former case, the conductor
+   connects to the iSCSI end point, partitions volume, "dd" the image and
+   closes the iSCSI connection.
+
+   The deployment is done. The Ironic conductor will switch pxe config to service
    mode and notify ramdisk agent on the successful deployment.
 
 #. The IPMI driver reboots the bare metal node. Note that there are 2 power
@@ -236,8 +249,10 @@ Deploy Process
 #. The bare metal node status is updated and the node instance is made
    available.
 
-Example 1: PXE Deploy Process
---------------------------------
+Example 1: PXE Boot and iSCSI Deploy Process
+--------------------------------------------
+
+This process is used with pxe_* family of drivers.
 
 .. seqdiag::
    :scale: 80
@@ -277,8 +292,10 @@ Example 1: PXE Deploy Process
 
 (From a `talk`_  and `slides`_)
 
-Example 2: Agent Deploy Process
----------------------------------
+Example 2: PXE Boot and Direct Deploy Process
+----------------------------------------------
+
+This process is used with agent_* family of drivers.
 
 .. seqdiag::
    :scale: 80
diff --git a/doc/source/dev/dev-quickstart.rst b/doc/source/dev/dev-quickstart.rst
index 5ea560dd93..aaf718f0b3 100644
--- a/doc/source/dev/dev-quickstart.rst
+++ b/doc/source/dev/dev-quickstart.rst
@@ -351,8 +351,9 @@ Switch to the stack user and clone DevStack::
     git clone https://github.com/openstack-dev/devstack.git devstack
 
 Create devstack/local.conf with minimal settings required to enable Ironic.
-Note that Ironic under devstack can only support running *either* the PXE
-or the agent driver, not both. The default is the PXE driver.::
+You can use either of two drivers for deploy: pxe_* or agent_*, see :ref:`IPA`
+for explanation. An example local.conf that enables both types of drivers
+and uses the ``pxe_ssh`` driver by default::
 
     cd devstack
     cat >local.conf <<END
@@ -363,6 +364,8 @@ or the agent driver, not both. The default is the PXE driver.::
     RABBIT_PASSWORD=password
     SERVICE_PASSWORD=password
     SERVICE_TOKEN=password
+    SWIFT_HASH=password
+    SWIFT_TEMPURL_KEY=password
 
     # Enable Ironic API and Ironic Conductor
     enable_service ironic
@@ -379,6 +382,12 @@ or the agent driver, not both. The default is the PXE driver.::
     enable_service q-meta
     enable_service neutron
 
+    # Enable Swift for agent_* drivers
+    enable_service s-proxy
+    enable_service s-object
+    enable_service s-container
+    enable_service s-account
+
     # Disable Horizon
     disable_service horizon
 
@@ -388,10 +397,21 @@ or the agent driver, not both. The default is the PXE driver.::
     # Disable Cinder
     disable_service cinder c-sch c-api c-vol
 
+    # Swift temp URL's are required for agent_* drivers.
+    SWIFT_ENABLE_TEMPURLS=True
+
     # Create 3 virtual machines to pose as Ironic's baremetal nodes.
     IRONIC_VM_COUNT=3
     IRONIC_VM_SSH_PORT=22
     IRONIC_BAREMETAL_BASIC_OPS=True
+    IRONIC_DEPLOY_DRIVER_ISCSI_WITH_IPA=True
+
+    # Enable Ironic drivers.
+    IRONIC_ENABLED_DRIVERS=fake,agent_ssh,agent_ipmitool,pxe_ssh,pxe_ipmitool
+
+    # Change this to alter the default driver for nodes created by devstack.
+    # This driver should be in the enabled list above.
+    IRONIC_DEPLOY_DRIVER=pxe_ssh
 
     # The parameters below represent the minimum possible values to create
     # functional nodes.
@@ -401,6 +421,9 @@ or the agent driver, not both. The default is the PXE driver.::
     # Size of the ephemeral partition in GB. Use 0 for no ephemeral partition.
     IRONIC_VM_EPHEMERAL_DISK=0
 
+    # To build your own IPA ramdisk from source, set this to True
+    IRONIC_BUILD_DEPLOY_RAMDISK=False
+
     VIRT_DRIVER=ironic
 
     # By default, DevStack creates a 10.0.0.0/24 network for instances.
@@ -417,31 +440,6 @@ or the agent driver, not both. The default is the PXE driver.::
 
     END
 
-If running with the agent driver (instead of PXE driver), add these additional
-settings to local.conf::
-
-    cat >>local.conf <<END
-    # Agent driver requires swift with tempurls
-    # Enable swift services
-    enable_service s-proxy
-    enable_service s-object
-    enable_service s-container
-    enable_service s-account
-
-    # Enable tempurls and set credentials
-    SWIFT_HASH=password
-    SWIFT_TEMPURL_KEY=password
-    SWIFT_ENABLE_TEMPURLS=True
-
-    # Enable agent driver
-    IRONIC_ENABLED_DRIVERS=fake,agent_ssh,agent_ipmitool
-    IRONIC_DEPLOY_DRIVER=agent_ssh
-
-    # To build your own IPA ramdisk from source, set this to True
-    IRONIC_BUILD_DEPLOY_RAMDISK=False
-
-    END
-
 Run stack.sh::
 
     ./stack.sh
diff --git a/doc/source/drivers/ipa.rst b/doc/source/drivers/ipa.rst
new file mode 100644
index 0000000000..7cbe842abd
--- /dev/null
+++ b/doc/source/drivers/ipa.rst
@@ -0,0 +1,49 @@
+.. _IPA:
+
+===================
+Ironic Python Agent
+===================
+
+Overview
+========
+
+*Ironic Python Agent* (also often called *IPA* or just *agent*) is a
+Python-based agent which handles *ironic* bare metal nodes in a
+variety of actions such as inspect, configure, clean and deploy images.
+IPA is distributed over nodes and runs, inside of a ramdisk, the
+process of booting this ramdisk on the node.
+
+For more information see the `ironic-python-agent documentation
+<http://docs.openstack.org/developer/ironic-python-agent/>`_.
+
+Drivers
+=======
+
+Starting with the Kilo release all drivers (except for fake ones) are using
+IPA for deployment. There are two types of them, which can be distinguished
+by prefix:
+
+* For drivers with ``pxe_`` or ``iscsi_`` prefix IPA exposes the root hard
+  drive as an iSCSI share and calls back to the ironic conductor. The
+  conductor mounts the share and copies an image there. It then signals back
+  to IPA for post-installation actions like setting up a bootloader for local
+  boot support.
+
+* For drivers with ``agent_`` prefix the conductor prepares a swift temporary
+  URL for an image. IPA then handles the whole deployment process:
+  downloading an image from swift, putting it on the machine and doing any
+  post-deploy actions.
+
+Which one to choose depends on your environment. iSCSI-based drivers put
+higher load on conductors, agent-based drivers currently require the whole
+image to fit in the node's memory.
+
+.. todo: other differences?
+
+.. todo: explain configuring swift for temporary URL's
+
+Requirements
+~~~~~~~~~~~~
+
+Using IPA requires it to be present and configured on the deploy ramdisk, see
+:ref:`BuildingDeployRamdisk` for details.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 0d265b78bb..f7627e5a80 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -39,6 +39,7 @@ Overview
   Installation Guide <deploy/install-guide>
   Upgrade Guide <deploy/upgrade-guide>
   Configuration Reference (Liberty) <http://docs.openstack.org/liberty/config-reference/content/ch_configuring-openstack-bare-metal.html>
+  drivers/ipa
   deploy/drivers
   deploy/cleaning