docs(managing_deis): add store documentation

carmstrong · carmstrong · commit 779fdad57260 · 2014-10-07T10:38:48.000-06:00
[skip ci]
diff --git a/docs/managing_deis/builder_settings.rst b/docs/managing_deis/builder_settings.rst
@@ -13,8 +13,6 @@ Requires: :ref:`controller <controller_settings>`, :ref:`registry <registry_sett
 
 Required by: :ref:`router <router_settings>`
 
-Considerations: must live on the same host as controller (see `#985`_)
-
 Settings set by builder
 -----------------------
 The following etcd keys are set by the builder component, typically in its /bin/boot script.
diff --git a/docs/managing_deis/controller_settings.rst b/docs/managing_deis/controller_settings.rst
@@ -13,7 +13,7 @@ Requires: :ref:`controller <controller_settings>`, :ref:`cache <cache_settings>`
 
 Required by: :ref:`router <router_settings>`
 
-Considerations: must live on the same host as both builder and logger (see `#985`_)
+Considerations: must live on the same host as logger (see `#985`_)
 
 Settings set by controller
 --------------------------
diff --git a/docs/managing_deis/database_settings.rst b/docs/managing_deis/database_settings.rst
@@ -9,7 +9,7 @@ The following settings are tunable for the :ref:`database` component.
 
 Dependencies
 ------------
-Requires: none
+Requires: :ref:`store-gateway <store_gateway_settings>`
 
 Required by: :ref:`controller <controller_settings>`
 
@@ -22,19 +22,29 @@ The following etcd keys are set by the database component, typically in its /bin
 ===========================              =================================================================================
 setting                                  description
 ===========================              =================================================================================
+/deis/database/adminPass                 database admin password (default: changeme123)
+/deis/database/adminUser                 database admin user (default: postgres)
+/deis/database/bucketName                store component bucket used for database WAL logs and backups (default: db_wal)
+/deis/database/engine                    database engine (default: postgresql_psycopg2)
 /deis/database/host                      IP address of the host running database
+/deis/database/name                      database name (default: deis)
+/deis/database/password                  database password (default: changeme123)
 /deis/database/port                      port used by the database service (default: 5432)
-/deis/database/engine                    database engine (default: postgresql_psycopg2)
-/deis/database/adminUser                 database admin user (default: postgres)
-/deis/database/adminPass                 database admin password (default: changeme123)
 /deis/database/user                      database user (default: deis)
-/deis/database/password                  database password (default: changeme123)
-/deis/database/name                      database name (default: deis)
 ===========================              =================================================================================
 
 Settings used by database
 -------------------------
-The database component uses no keys from etcd other than the ones it sets.
+The following etcd keys are used by the database component.
+
+====================================      ====================================================================================
+setting                                   description
+====================================      ====================================================================================
+/deis/store/gateway/accessKey             S3 API access used to access the deis store gateway (set by store-gateway)
+/deis/store/gateway/host                  host of the store gateway component (set by store-gateway)
+/deis/store/gateway/port                  port of the store gateway component (set by store-gateway)
+/deis/store/gateway/secretKey             S3 API secret key used to access the deis store gateway (set by store-gateway)
+====================================      ====================================================================================
 
 Using a custom database image
 -----------------------------
diff --git a/docs/managing_deis/index.rst b/docs/managing_deis/index.rst
@@ -18,6 +18,9 @@ Managing Deis
     logger_settings
     registry_settings
     router_settings
+    store_daemon_settings
+    store_gateway_settings
+    store_monitor_settings
     managing_users
     platform_logging
     platform_monitoring
diff --git a/docs/managing_deis/registry_settings.rst b/docs/managing_deis/registry_settings.rst
@@ -9,7 +9,7 @@ The following settings are tunable for the :ref:`registry` component.
 
 Dependencies
 ------------
-Requires: :ref:`cache <cache_settings>`
+Requires: :ref:`cache <cache_settings>`, :ref:`store-gateway <store_gateway_settings>`
 
 Required by: :ref:`builder <builder_settings>`, :ref:`controller <controller_settings>`
 
@@ -22,6 +22,7 @@ The following etcd keys are set by the registry component, typically in its /bin
 ===========================              =================================================================================
 setting                                  description
 ===========================              =================================================================================
+/deis/registry/bucketName                store component bucket used for registry image layers (default: registry)
 /deis/registry/host                      IP address of the host running registry
 /deis/registry/port                      port used by the registry service (default: 5000)
 /deis/registry/protocol                  protocol for registry (default: http)
@@ -32,12 +33,16 @@ Settings used by registry
 ---------------------------
 The following etcd keys are used by the registry component.
 
-====================================      ======================================================
+====================================      =================================================================================
 setting                                   description
-====================================      ======================================================
+====================================      =================================================================================
 /deis/cache/host                          host of the cache component (set by cache)
 /deis/cache/port                          port of the cache component (set by cache)
-====================================      ======================================================
+/deis/store/gateway/accessKey             S3 API access used to access store-gateway (set by store-gateway)
+/deis/store/gateway/host                  host of the store-gateway component (set by store-gateway)
+/deis/store/gateway/port                  port of the store-gateway component (set by store-gateway)
+/deis/store/gateway/secretKey             S3 API secret key used to access store-gateway (set by store-gateway)
+====================================      =================================================================================
 
 The Deis registry component inherits from the Docker registry container, so additional configuration
 options can be supplied. For a full explanation of these settings, see the Docker registry `README`_.
diff --git a/docs/managing_deis/router_settings.rst b/docs/managing_deis/router_settings.rst
@@ -9,7 +9,7 @@ The following settings are tunable for the :ref:`router` component.
 
 Dependencies
 ------------
-Requires: :ref:`builder <builder_settings>`, :ref:`controller <controller_settings>`
+Requires: :ref:`builder <builder_settings>`, :ref:`controller <controller_settings>`, :ref:`store-gateway <store_gateway_settings>`
 
 Required by: none
 
@@ -33,12 +33,11 @@ The following etcd keys are used by the router component.
 =======================================      ==================================================================================================================================================================================================================================================================================================================================
 setting                                      description
 =======================================      ==================================================================================================================================================================================================================================================================================================================================
-/deis/domains/*                              domain configuration for applications (set by controller)
-/deis/services/*                             application configuration (set by application unit files)
 /deis/builder/host                           host of the builder component (set by builder)
 /deis/builder/port                           port of the builder component (set by builder)
 /deis/controller/host                        host of the controller component (set by controller)
 /deis/controller/port                        port of the controller component (set by controller)
+/deis/domains/*                              domain configuration for applications (set by controller)
 /deis/router/bodySize                        nginx body size setting (default: 1m)
 /deis/router/builder/timeout/connect         proxy_connect_timeout for deis-builder (default: 10000). Unit in miliseconds
 /deis/router/builder/timeout/read            proxy_read_timeout for deis-builder (default: 1200000). Unit in miliseconds
@@ -48,13 +47,16 @@ setting                                      description
 /deis/router/controller/timeout/read         proxy_read_timeout for deis-controller (default: 20m)
 /deis/router/controller/timeout/send         proxy_send_timeout for deis-controller (default: 20m)
 /deis/router/gzip                            nginx gzip setting (default: on)
-/deis/router/gzipHttpVersion                 nginx gzipHttpVersion setting (default: 1.1)
 /deis/router/gzipCompLevel                   nginx gzipCompLevel setting (default: 5)
-/deis/router/gzipProxied                     nginx gzipProxied setting (default: any)
-/deis/router/gzipVary                        nginx gzipVary setting (default: on)
 /deis/router/gzipDisable                     nginx gzipDisable setting (default: "msie6")
-/deis/router/gzipTypes                       nginx gzipTypes setting (default: "application/atom+xml application/javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component")
+/deis/router/gzipHttpVersion                 nginx gzipHttpVersion setting (default: 1.1)
 /deis/router/gzipMinLength                   nginx gzipMinLength setting (default: 256)
+/deis/router/gzipProxied                     nginx gzipProxied setting (default: any)
+/deis/router/gzipTypes                       nginx gzipTypes setting (default: "application/atom+xml application/javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component")
+/deis/router/gzipVary                        nginx gzipVary setting (default: on)
+/deis/services/*                             application configuration (set by application unit files)
+/deis/store/gateway/host                     host of the store gateway component (set by store-gateway)
+/deis/store/gateway/port                     port of the store gateway component (set by store-gateway)
 =======================================      ==================================================================================================================================================================================================================================================================================================================================
 
 Using a custom router image
diff --git a/docs/managing_deis/store_daemon_settings.rst b/docs/managing_deis/store_daemon_settings.rst
@@ -0,0 +1,61 @@
+:title: Customizing store-daemon
+:description: Learn how to tune custom Deis settings.
+
+.. _store_daemon_settings:
+
+Customizing store-daemon
+=========================
+The following settings are tunable for the :ref:`store` component's daemon service.
+
+Dependencies
+------------
+Requires: :ref:`store-monitor <store_monitor_settings>`
+
+Required by: :ref:`store-gateway <store_gateway_settings>`
+
+Considerations: none
+
+Settings set by store-daemon
+-----------------------------
+The following etcd keys are set by the store-daemon component, typically in its /bin/boot script.
+
+=============================            =================================================================================
+setting                                  description
+=============================            =================================================================================
+/deis/store/osds/$HOST                   Ceph OSD ID for this OSD instance (generated by Ceph)
+=============================            =================================================================================
+
+Settings used by store-daemon
+------------------------------
+The following etcd keys are used by the store-daemon component.
+
+====================================      ============================================================================
+setting                                   description
+====================================      ============================================================================
+/deis/store/adminKeyring                  keyring for an admin user to access the Ceph cluster (set by store-monitor)
+/deis/store/conf                          Ceph configuration file shared by store components (set by store-monitor)
+/deis/store/hosts                         deis-monitor hosts (set by store-monitor)
+/deis/store/monKeyring                    keyring for the monitor to access the Ceph cluster (set by store-monitor)
+/deis/store/monSetupComplete              set when the Ceph cluster setup is complete
+====================================      ============================================================================
+
+Using a custom store-daemon image
+---------------------------------
+You can use a custom Docker image for the store-daemon component instead of the image
+supplied with Deis:
+
+.. code-block:: console
+
+    $ etcdctl set /deis/store-daemon/image myaccount/myimage:latest
+
+This will pull the image from the public Docker registry. You can also pull from a private
+registry:
+
+.. code-block:: console
+
+    $ etcdctl set /deis/store-daemon/image registry.mydomain.org:5000/myaccount/myimage:latest
+
+Be sure that your custom image functions in the same way as the `stock store-daemon image`_ shipped with
+Deis. Specifically, ensure that it sets and reads appropriate etcd keys.
+
+.. _`stock store-daemon image`: https://github.com/deis/deis/tree/master/store/daemon
diff --git a/docs/managing_deis/store_gateway_settings.rst b/docs/managing_deis/store_gateway_settings.rst
@@ -0,0 +1,64 @@
+:title: Customizing store-gateway
+:description: Learn how to tune custom Deis settings.
+
+.. _store_gateway_settings:
+
+Customizing store-gateway
+=========================
+The following settings are tunable for the :ref:`store` component's gateway service.
+
+Dependencies
+------------
+Requires: :ref:`store-daemon <store_daemon_settings>`, :ref:`store-monitor <store_monitor_settings>`
+
+Required by: :ref:`database <database_settings>`, :ref:`registry <registry_settings>`
+
+Considerations: none
+
+Settings set by store-gateway
+-----------------------------
+The following etcd keys are set by the store-gateway component, typically in its /bin/boot script.
+
+=============================            =================================================================================
+setting                                  description
+=============================            =================================================================================
+/deis/store/gatewayKeyring               keyring for the gateway user to access the Ceph cluster (generated by Ceph)
+/deis/store/gateway/accessKey            S3 API access used to access store-gateway (generated by Ceph)
+/deis/store/gateway/host                 IP address of the host running store-gateway
+/deis/store/gateway/port                 port used by the store-gateway service (default: 8888)
+/deis/store/gateway/secretKey            S3 API secret key used to access store-gateway (generated by Ceph)
+=============================            =================================================================================
+
+Settings used by store-gateway
+------------------------------
+The following etcd keys are used by the store-gateway component.
+
+====================================      ============================================================================
+setting                                   description
+====================================      ============================================================================
+/deis/store/adminKeyring                  keyring for an admin user to access the Ceph cluster (set by store-monitor)
+/deis/store/conf                          Ceph configuration file shared by store components (set by store-monitor)
+/deis/store/hosts                         deis-monitor hosts (set by store-monitor)
+/deis/store/monKeyring                    keyring for the monitor to access the Ceph cluster (set by store-monitor)
+====================================      ============================================================================
+
+Using a custom store-gateway image
+----------------------------------
+You can use a custom Docker image for the store-gateway component instead of the image
+supplied with Deis:
+
+.. code-block:: console
+
+    $ etcdctl set /deis/store-gateway/image myaccount/myimage:latest
+
+This will pull the image from the public Docker registry. You can also pull from a private
+registry:
+
+.. code-block:: console
+
+    $ etcdctl set /deis/store-gateway/image registry.mydomain.org:5000/myaccount/myimage:latest
+
+Be sure that your custom image functions in the same way as the `stock store-gateway image`_ shipped with
+Deis. Specifically, ensure that it sets and reads appropriate etcd keys.
+
+.. _`stock store-gateway image`: https://github.com/deis/deis/tree/master/store/gateway
diff --git a/docs/managing_deis/store_monitor_settings.rst b/docs/managing_deis/store_monitor_settings.rst
diff --git a/docs/understanding_deis/architecture.rst b/docs/understanding_deis/architecture.rst
