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. Default mappings
  23    for service to network names are defined in
  24    ../network/service_net_map.j2.yaml, which may be overridden via
  25    ServiceNetMap values added to a user environment file via
  26    parameter_defaults.
  27
  28  * EndpointMap: Mapping of service endpoint -> protocol. Contains a mapping of
  29    endpoint data generated for all services, based on the data included in
  30    ../network/endpoints/endpoint_data.yaml.
  31
  32  * DefaultPasswords: Mapping of service -> default password. Used to pass some
  33    passwords from the parent templates, this is a legacy interface and should
  34    not be used by new services.
  35
  36  * RoleName: Name of the role on which this service is deployed. A service can
  37    be deployed in multiple roles. This is an internal parameter (should not be
  38    set via environment file), which is fetched from the name attribute of the
  39    roles_data.yaml template.
  40
  41  * RoleParameters: Parameter specific to a role on which the service is
  42    applied. Using the format "<RoleName>Parameters" in the parameter_defaults
  43    of user environment file, parameters can be provided for a specific role.
  44    For example, in order to provide a parameter specific to "Compute" role,
  45    below is the format::
  46
  47       parameter_defaults:
  48         ComputeParameters:
  49           Param1: value
  50
  51
  52 Config Settings
  53 ---------------
  54
  55 Each service may define three ways in which to output variables to configure Hiera
  56 settings on the nodes.
  57
  58  * config_settings: the hiera keys will be pushed on all roles of which the service
  59    is a part of.
  60
  61  * global_config_settings: the hiera keys will be distributed to all roles
  62
  63  * service_config_settings: Takes an extra key to wire in values that are
  64    defined for a service that need to be consumed by some other service.
  65    For example:
  66    service_config_settings:
  67      haproxy:
  68        foo: bar
  69    This will set the hiera key 'foo' on all roles where haproxy is included.
  70
  71 Deployment Steps
  72 ----------------
  73
  74 Each service may define an output variable which returns a puppet manifest
  75 snippet that will run at each of the following steps. Earlier manifests
  76 are re-asserted when applying latter ones.
  77
  78  * config_settings: Custom hiera settings for this service.
  79
  80  * global_config_settings: Additional hiera settings distributed to all roles.
  81
  82  * step_config: A puppet manifest that is used to step through the deployment
  83    sequence. Each sequence is given a "step" (via hiera('step') that provides
  84    information for when puppet classes should activate themselves.
  85
  86    Steps correlate to the following:
  87
  88    1) Load Balancer configuration
  89
  90    2) Core Services (Database/Rabbit/NTP/etc.)
  91
  92    3) Early Openstack Service setup (Ringbuilder, etc.)
  93
  94    4) General OpenStack Services
  95
  96    5) Service activation (Pacemaker)
  97
  98 It is also possible to use Mistral actions or workflows together with
  99 a deployment step, these are executed before the main configuration run.
 100 To describe actions or workflows from within a service use:
 101
 102   * workflow_tasks: One or more workflow task properties
 103
 104 which expects a map where the key is the step and the value a list of
 105 dictionaries descrbing each a workflow task, for example::
 106
 107   workflow_tasks:
 108     step2:
 109       - name: echo
 110         action: std.echo output=Hello
 111     step3:
 112       - name: external
 113         workflow: my-pre-existing-workflow-name
 114         input:
 115           workflow_param1: value
 116           workflow_param2: value
 117
 118 The Heat guide for the `OS::Mistral::Workflow task property
 119 <https://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Mistral::Workflow-prop-tasks>`_
 120 has more details about the expected dictionary.
 121
 122 Batch Upgrade Steps
 123 -------------------
 124
 125 Each service template may optionally define a `upgrade_batch_tasks` key, which
 126 is a list of ansible tasks to be performed during the upgrade process.
 127
 128 Similar to the step_config, we allow a series of steps for the per-service
 129 upgrade sequence, defined as ansible tasks with a tag e.g "step1" for the first
 130 step, "step2" for the second, etc (currently only two steps are supported, but
 131 more may be added when required as additional services get converted to batched
 132 upgrades).
 133
 134 Note that each step is performed in batches, then we move on to the next step
 135 which is also performed in batches (we don't perform all steps on one node,
 136 then move on to the next one which means you can sequence rolling upgrades of
 137 dependent services via the step value).
 138
 139 The tasks performed at each step is service specific, but note that all batch
 140 upgrade steps are performed before the `upgrade_tasks` described below.  This
 141 means that all services that support rolling upgrades can be upgraded without
 142 downtime during `upgrade_batch_tasks`, then any remaining services are stopped
 143 and upgraded during `upgrade_tasks`
 144
 145 The default batch size is 1, but this can be overridden for each role via the
 146 `upgrade_batch_size` option in roles_data.yaml
 147
 148 Upgrade Steps
 149 -------------
 150
 151 Each service template may optionally define a `upgrade_tasks` key, which is a
 152 list of ansible tasks to be performed during the upgrade process.
 153
 154 Similar to the step_config, we allow a series of steps for the per-service
 155 upgrade sequence, defined as ansible tasks with a tag e.g "step1" for the first
 156 step, "step2" for the second, etc.
 157
 158    Steps/tags correlate to the following:
 159
 160    1) Stop all control-plane services.
 161
 162    2) Quiesce the control-plane, e.g disable LoadBalancer, stop
 163       pacemaker cluster: this will stop the following resource:
 164       - ocata:
 165         - galera
 166         - rabbit
 167         - redis
 168         - haproxy
 169         - vips
 170         - cinder-volumes
 171         - cinder-backup
 172         - manilla-share
 173         - rbd-mirror
 174
 175       The exact order is controlled by the cluster constraints.
 176
 177    3) Perform a package update and install new packages: A general
 178       upgrade is done, and only new package should go into service
 179       ansible tasks.
 180
 181    4) Start services needed for migration tasks (e.g DB)
 182
 183    5) Perform any migration tasks, e.g DB sync commands
 184
 185 Note that the services are not started in the upgrade tasks - we instead re-run
 186 puppet which does any reconfiguration required for the new version, then starts
 187 the services.
 188
 189 Update Steps
 190 ------------
 191
 192 Each service template may optionally define a `update_tasks` key, which is a
 193 list of ansible tasks to be performed during the minor update process.
 194
 195 Similar to the upgrade_tasks, we allow a series of steps for the per-service
 196 update sequence, but note update_task selects the steps via a conditional
 197 referencing the step variable e.g when: step == 2, which is different to the
 198 tags based approach used for upgrade_tasks (the two may be aligned in future).
 199
 200
 201 Nova Server Metadata Settings
 202 -----------------------------
 203
 204 One can use the hook of type `OS::TripleO::ServiceServerMetadataHook` to pass
 205 entries to the nova instances' metadata. It is, however, disabled by default.
 206 In order to overwrite it one needs to define it in the resource registry. An
 207 implementation of this hook needs to conform to the following:
 208
 209 * It needs to define an input called `RoleData` of json type. This gets as
 210   input the contents of the `role_data` for each role's ServiceChain.
 211
 212 * This needs to define an output called `metadata` which will be given to the
 213   Nova Server resource as the instance's metadata.