1 files changed, 81 insertions, 0 deletions
diff --git a/doc/rtd/topics/dir_layout.rst b/doc/rtd/topics/dir_layout.rst
new file mode 100644
index 00000000..8815d33d
--- /dev/null
+++ b/doc/rtd/topics/dir_layout.rst
@@ -0,0 +1,81 @@
+=========
+Directory layout
+=========
+
+Cloudinits's directory structure is somewhat different from a regular application::
+
+  /var/lib/cloud/
+      - data/
+         - instance-id  
+         - previous-instance-id
+         - datasource
+         - previous-datasource
+         - previous-hostname
+      - handlers/
+      - instance
+      - instances/
+          i-00000XYZ/
+            - boot-finished
+            - cloud-config.txt
+            - datasource
+            - handlers/
+            - obj.pkl
+            - scripts/
+            - sem/
+            - user-data.txt
+            - user-data.txt.i
+      - scripts/
+         - per-boot/
+         - per-instance/
+         - per-once/
+      - seed/
+      - sem/
+
+``/var/lib/cloud``
+
+  The main directory containing the cloud-init specific subdirectories.
+  It is typically located at ``/var/lib`` but there are certain configuration
+  scenarios where this can be altered. 
+
+  TBD, describe this overriding more.
+
+``data/``
+
+  Contains information releated to instance ids, datasources and hostnames of the previous
+  and current instance if they are different. These can be examined as needed to
+  determine any information releated to a previous boot (if applicable).
+
+``handlers/``
+
+  Custom ``part-handlers`` code is written out here. Files that end up here are written
+  out with in the scheme of ``part-handler-XYZ`` where ``XYZ`` is the handler number (the
+  first handler found starts at 0).
+
+
+``instance``
+
+  A symlink to the current ``instances/`` subdirectory that points to the currently
+  active instance (which is active is dependent on the datasource loaded).
+
+``instances/``
+
+  All instances that were created using this image end up with instance identifer
+  subdirectories (and corresponding data for each instance). The currently active
+  instance will be symlinked the the ``instance`` symlink file defined previously.
+
+``scripts/``
+
+  Scripts that are downloaded/created by the corresponding ``part-handler`` will end up
+  in one of these subdirectories.
+
+``seed/``
+
+  TBD
+
+``sem/``
+
+  Cloud-init has a concept of a module sempahore, which basically consists
+  of the module name and its frequency. These files are used to ensure a module
+  is only ran `per-once`, `per-instance`, `per-always`. This folder contains 
+  sempaphore `files` which are only supposed to run `per-once` (not tied to the instance id).
+