X-Git-Url: https://gerrit.opnfv.org/gerrit/gitweb?a=blobdiff_plain;f=puppet%2Fservices%2FREADME.rst;h=856b306e508c71e7944332642ee18d42caf2f040;hb=5bf7181aa20d1e42af23e49cd80f7364bc39aabf;hp=3accff3687331fee47343d507af55be34f9aefcb;hpb=227ec53c36adfd34c0e179c4979aeab2d40312b8;p=apex-tripleo-heat-templates.git

diff --git a/puppet/services/README.rst b/puppet/services/README.rst
index 3accff36..223c3ed0 100644
--- a/puppet/services/README.rst
+++ b/puppet/services/README.rst
@@ -19,11 +19,24 @@ environment to set per service parameters.
 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.
 
-Steps
------
+ * 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
+----------------
 
 Each service may define an output variable which returns a puppet manifest
 snippet that will run at each of the following steps. Earlier manifests
@@ -48,3 +61,71 @@ are re-asserted when applying latter ones.
    4) General OpenStack Services
 
    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
+-------------
+
+Each service template may optionally define a `upgrade_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.
+
+   Steps/tages correlate to the following:
+
+   1) Quiesce the control-plane, e.g disable LoadBalancer, stop pacemaker cluster
+
+   2) Stop all control-plane services, ready for upgrade
+
+   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
+
+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
+-----------------------------
+
+One can use the hook of type `OS::TripleO::ServiceServerMetadataHook` to pass
+entries to the nova instances' metadata. It is, however, disabled by default.
+In order to overwrite it one needs to define it in the resource registry. An
+implementation of this hook needs to conform to the following:
+
+* It needs to define an input called `RoleData` of json type. This gets as
+  input the contents of the `role_data` for each role's ServiceChain.
+
+* This needs to define an output called `metadata` which will be given to the
+  Nova Server resource as the instance's metadata.