puppet/services/README.rst

   1 ========
   2 services
   3 ========
   4
   5 A TripleO nested stack Heat template that encapsulates generic configuration
   6 data to configure a specific service. This generally includes everything
   7 needed to configure the service excluding the local bind ports which
   8 are still managed in the per-node role templates directly (controller.yaml,
   9 compute.yaml, etc.). All other (global) service settings go into
  10 the puppet/service templates.
  11
  12 Input Parameters
  13 ----------------
  14
  15 Each service may define its own input parameters and defaults.
  16 Operators will use the parameter_defaults section of any Heat
  17 environment to set per service parameters.
  18
  19 Config Settings
  20 ---------------
  21
  22 Each service may define three ways in which to output variables to configure Hiera
  23 settings on the nodes.
  24
  25  * config_settings: the hiera keys will be pushed on all roles of which the service
  26    is a part of.
  27
  28  * global_config_settings: the hiera keys will be distributed to all roles
  29
  30  * service_config_settings: Takes an extra key to wire in values that are
  31    defined for a service that need to be consumed by some other service.
  32    For example:
  33    service_config_settings:
  34      haproxy:
  35        foo: bar
  36    This will set the hiera key 'foo' on all roles where haproxy is included.
  37
  38 Deployment Steps
  39 ----------------
  40
  41 Each service may define an output variable which returns a puppet manifest
  42 snippet that will run at each of the following steps. Earlier manifests
  43 are re-asserted when applying latter ones.
  44
  45  * config_settings: Custom hiera settings for this service.
  46
  47  * global_config_settings: Additional hiera settings distributed to all roles.
  48
  49  * step_config: A puppet manifest that is used to step through the deployment
  50    sequence. Each sequence is given a "step" (via hiera('step') that provides
  51    information for when puppet classes should activate themselves.
  52
  53    Steps correlate to the following:
  54
  55    1) Load Balancer configuration
  56
  57    2) Core Services (Database/Rabbit/NTP/etc.)
  58
  59    3) Early Openstack Service setup (Ringbuilder, etc.)
  60
  61    4) General OpenStack Services
  62
  63    5) Service activation (Pacemaker)
  64
  65 Batch Upgrade Steps
  66 -------------------
  67
  68 Each service template may optionally define a `upgrade_batch_tasks` key, which
  69 is a list of ansible tasks to be performed during the upgrade process.
  70
  71 Similar to the step_config, we allow a series of steps for the per-service
  72 upgrade sequence, defined as ansible tasks with a tag e.g "step1" for the first
  73 step, "step2" for the second, etc (currently only two steps are supported, but
  74 more may be added when required as additional services get converted to batched
  75 upgrades).
  76
  77 Note that each step is performed in batches, then we move on to the next step
  78 which is also performed in batches (we don't perform all steps on one node,
  79 then move on to the next one which means you can sequence rolling upgrades of
  80 dependent services via the step value).
  81
  82 The tasks performed at each step is service specific, but note that all batch
  83 upgrade steps are performed before the `upgrade_tasks` described below.  This
  84 means that all services that support rolling upgrades can be upgraded without
  85 downtime during `upgrade_batch_tasks`, then any remaining services are stopped
  86 and upgraded during `upgrade_tasks`
  87
  88 The default batch size is 1, but this can be overridden for each role via the
  89 `upgrade_batch_size` option in roles_data.yaml
  90
  91 Upgrade Steps
  92 -------------
  93
  94 Each service template may optionally define a `upgrade_tasks` key, which is a
  95 list of ansible tasks to be performed during the upgrade process.
  96
  97 Similar to the step_config, we allow a series of steps for the per-service
  98 upgrade sequence, defined as ansible tasks with a tag e.g "step1" for the first
  99 step, "step2" for the second, etc.
 100
 101    Steps/tages correlate to the following:
 102
 103    1) Stop all control-plane services.
 104
 105    2) Quiesce the control-plane, e.g disable LoadBalancer, stop
 106       pacemaker cluster: this will stop the following resource:
 107       - ocata:
 108         - galera
 109         - rabbit
 110         - redis
 111         - haproxy
 112         - vips
 113         - cinder-volumes
 114         - cinder-backup
 115         - manilla-share
 116         - rbd-mirror
 117
 118       The exact order is controlled by the cluster constraints.
 119
 120    3) Perform a package update and install new packages: A general
 121       upgrade is done, and only new package should go into service
 122       ansible tasks.
 123
 124    4) Start services needed for migration tasks (e.g DB)
 125
 126    5) Perform any migration tasks, e.g DB sync commands
 127
 128 Note that the services are not started in the upgrade tasks - we instead re-run
 129 puppet which does any reconfiguration required for the new version, then starts
 130 the services.
 131
 132 Nova Server Metadata Settings
 133 -----------------------------
 134
 135 One can use the hook of type `OS::TripleO::ServiceServerMetadataHook` to pass
 136 entries to the nova instances' metadata. It is, however, disabled by default.
 137 In order to overwrite it one needs to define it in the resource registry. An
 138 implementation of this hook needs to conform to the following:
 139
 140 * It needs to define an input called `RoleData` of json type. This gets as
 141   input the contents of the `role_data` for each role's ServiceChain.
 142
 143 * This needs to define an output called `metadata` which will be given to the
 144   Nova Server resource as the instance's metadata.