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