Merge pull request #3429 from bmbouter/add-docs-on-deploying-pulp

Adds WSGI and Architecture Docs

docs/arch_and_scale/index.rst

@@ -0,0 +1,33 @@
+.. _RabbitMQ Clustering Guide: https://www.rabbitmq.com/clustering.html
+
+Architecture and Scaling
+========================
+
+Pulp's architecture has five components to it. Each of these can be horizontally scaled
+independently for both high availability and/or additional capacity for that part of the
+architecture.
+
+WSGI application
+  Pulp's web application is served by one or more WSGI webservers. See the
+  :ref:`wsgi-application` docs for more info on deploying and scaling this component.
+
+Workers
+  Pulp's tasking system requires at least one running worker. Additional workers can be added to add
+  capacity to the tasking system.
+
+Resource Manager
+  Pulp's tasking system requires at least one running resource manager. Although it's required for
+  correctness, it is almost always idle even in very large Pulp environments. As such, additional
+  scaling may increase availability but will not increase tasking system throughput.
+
+SQL Database
+  Refer to the database documentation on how to scale it and/or make it highly available.
+
+RabbitMQ
+  Refer to the `RabbitMQ Clustering Guide`_ on how to cluster and scale RabbitMQ.
+
+
+.. toctree::
+   :maxdepth: 3
+
+   webserver

docs/arch_and_scale/webserver.rst

@@ -0,0 +1,27 @@
+.. _wsgi-application:
+
+WSGI Application
+================
+
+Pulp is a Django based WSGI application that serves three types of URLs (aka views in Django). This
+document outlines the deployment needs of the different parts of the Pulp web application.
+
+By understanding the different parts, you can choose to deploy and scale them separately.
+
+REST API
+  The Pulp REST API is rooted at ``/pulp/api/v3/``. To serve the REST API, have a WSGI compatible
+  webserver route urls matching ``/pulp/api/v3/`` to the Pulp WSGI application.
+
+Content
+  A Publication that is available via a Distribution is how Pulp serves stored content to clients
+  through its web application. To serve this content,  have a WSGI compatible webserver route urls
+  matching ``/pulp/content/`` to the Pulp WSGI application.
+
+Plugin Views
+  Plugins can contribute views anywhere in the url namespace are are not restricted to ``/pulp/``.
+  Refer to your plugin documentation to understand the url needs of any given plugin. Another option
+  is to route ``/``.
+
+Using the urls above you can choose which webservers and how many will serve the different parts of
+the Pulp application. If you want to have a single rule to serve all components of the Pulp web
+application, routing ``/`` to it will is simple and will always work.

docs/index.rst

@@ -6,6 +6,7 @@ Pulp Documentation
    installation/index
    workflows/index
    cli_guide/index
+   arch_and_scale/index
    integration_guide/index
    contributing/index
    plugins/index