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