Merge "Enable docker for all roles"

[apex-tripleo-heat-templates.git] / puppet / services / README.rst

diff --git a/puppet/services/README.rst b/puppet/services/README.rst
index 6e4e9c1..223c3ed 100644 (file)
--- a/puppet/services/README.rst
+++ b/puppet/services/README.rst
@@ -19,8 +19,21 @@ environment to set per service parameters.
 Config Settings
 ---------------
 
 Config Settings
 ---------------
 

-Each service may define a config_settings output variable which returns
-Hiera settings to be configured.
+Each service may define three ways in which to output variables to configure Hiera
+settings on the nodes.
+
+ * config_settings: the hiera keys will be pushed on all roles of which the service
+   is a part of.
+
+ * global_config_settings: the hiera keys will be distributed to all roles
+
+ * service_config_settings: Takes an extra key to wire in values that are
+   defined for a service that need to be consumed by some other service.
+   For example:
+   service_config_settings:
+     haproxy:
+       foo: bar
+   This will set the hiera key 'foo' on all roles where haproxy is included.

 
 Deployment Steps
 ----------------
 
 Deployment Steps
 ----------------


@@ -49,6 +62,32 @@ are re-asserted when applying latter ones.
 
    5) Service activation (Pacemaker)
 
 
    5) Service activation (Pacemaker)
 

+Batch Upgrade Steps
+-------------------
+
+Each service template may optionally define a `upgrade_batch_tasks` key, which
+is a list of ansible tasks to be performed during the upgrade process.
+
+Similar to the step_config, we allow a series of steps for the per-service
+upgrade sequence, defined as ansible tasks with a tag e.g "step1" for the first
+step, "step2" for the second, etc (currently only two steps are supported, but
+more may be added when required as additional services get converted to batched
+upgrades).
+
+Note that each step is performed in batches, then we move on to the next step
+which is also performed in batches (we don't perform all steps on one node,
+then move on to the next one which means you can sequence rolling upgrades of
+dependent services via the step value).
+
+The tasks performed at each step is service specific, but note that all batch
+upgrade steps are performed before the `upgrade_tasks` described below.  This
+means that all services that support rolling upgrades can be upgraded without
+downtime during `upgrade_batch_tasks`, then any remaining services are stopped
+and upgraded during `upgrade_tasks`
+
+The default batch size is 1, but this can be overridden for each role via the
+`upgrade_batch_size` option in roles_data.yaml
+

 Upgrade Steps
 -------------
 
 Upgrade Steps
 -------------
 


@@ -65,15 +104,17 @@ step, "step2" for the second, etc.
 
    2) Stop all control-plane services, ready for upgrade
 
 
    2) Stop all control-plane services, ready for upgrade
 

-   3) Perform a package update, (either specific packages or the whole system)
+   3) Perform a package update and install new packages: A general
+      upgrade is done, and only new package should go into service
+      ansible tasks.

 
    4) Start services needed for migration tasks (e.g DB)
 
    5) Perform any migration tasks, e.g DB sync commands
 
 
    4) Start services needed for migration tasks (e.g DB)
 
    5) Perform any migration tasks, e.g DB sync commands
 

-   6) Start control-plane services
-
-   7) Any additional online migration tasks (e.g data migrations)
+Note that the services are not started in the upgrade tasks - we instead re-run
+puppet which does any reconfiguration required for the new version, then starts
+the services.

 
 Nova Server Metadata Settings
 -----------------------------
 
 Nova Server Metadata Settings
 -----------------------------