roles/README.rst

   1 Roles
   2 =====
   3
   4 The yaml files in this directory can be combined into a single roles_data.yaml
   5 and be used with TripleO to create custom deployments.
   6
   7 Use tripleoclient to build your own custom roles_data.yaml for your
   8 environment.
   9
  10 roles_data.yaml
  11 ---------------
  12
  13 The roles_data.yaml specifies which roles (groups of nodes) will be deployed.
  14 Note this file is used as an input the the various \*.j2.yaml jinja2 templates,
  15 so that they are converted into \*.yaml during the plan creation. This occurs
  16 via a mistral action/workflow. The file format of this file is a yaml list.
  17
  18 Role YAML files
  19 ===============
  20
  21 Each role yaml file should contain only a single role. The filename should
  22 match the role name. The name of the role is  mandatory and must be unique.
  23
  24 The role files in this folder should contain at least a role name and the
  25 default list of services for the role.
  26
  27 Role Options
  28 ------------
  29
  30 * CountDefault: (number) optional, default number of nodes, defaults to 0
  31   sets the default for the {{role.name}}Count parameter in overcloud.yaml
  32
  33 * HostnameFormatDefault: (string) optional default format string for hostname
  34   defaults to '%stackname%-{{role.name.lower()}}-%index%'
  35   sets the default for {{role.name}}HostnameFormat parameter in overcloud.yaml
  36
  37 * disable_constraints: (boolean) optional, whether to disable Nova and Glance
  38   constraints for each role specified in the templates.
  39
  40 * disable_upgrade_deployment: (boolean) optional, whether to run the
  41   ansible upgrade steps for all services that are deployed on the role. If set
  42   to True, the operator will drive the upgrade for this role's nodes.
  43
  44 * upgrade_batch_size: (number): batch size for upgrades where tasks are
  45   specified by services to run in batches vs all nodes at once.
  46   This defaults to 1, but larger batches may be specified here.
  47
  48 * ServicesDefault: (list) optional default list of services to be deployed
  49   on the role, defaults to an empty list. Sets the default for the
  50   {{role.name}}Services parameter in overcloud.yaml
  51
  52 * tags: (list) list of tags used by other parts of the deployment process to
  53   find the role for a specific type of functionality. Currently a role
  54   with both 'primary' and 'controller' is used as the primary role for the
  55   deployment process. If no roles have have 'primary' and 'controller', the
  56   first role in this file is used as the primary role.
  57
  58 * description: (string) as few sentences describing the role and information
  59   pertaining to the usage of the role.
  60
  61 Working with Roles
  62 ==================
  63 The tripleoclient provides a series of commands that can be used to view
  64 roles and generate a roles_data.yaml file for deployment.
  65
  66 Listing Available Roles
  67 -----------------------
  68 The ``openstack overcloud role list`` command can be used to view the list
  69 of roles provided by tripleo-heat-templates.
  70
  71 Usage
  72 ^^^^^
  73 .. code-block::
  74
  75   usage: openstack overcloud role list [-h] [--roles-path <roles directory>]
  76
  77   List availables roles
  78
  79   optional arguments:
  80     -h, --help            show this help message and exit
  81     --roles-path <roles directory>
  82                           Filesystem path containing the role yaml files. By
  83                           default this is /usr/share/openstack-tripleo-heat-
  84                           templates/roles
  85
  86 Example
  87 ^^^^^^^
  88 .. code-block::
  89
  90   [user@host ~]$ openstack overcloud role list
  91   BlockStorage
  92   CephStorage
  93   Compute
  94   Controller
  95   ControllerOpenstack
  96   Database
  97   Messaging
  98   Networker
  99   ObjectStorage
 100   Telemetry
 101   Undercloud
 102
 103 Viewing Role Details
 104 --------------------
 105 The ``openstack overcloud role show`` command can be used as a quick way to
 106 view some of the information about a role.
 107
 108 Usage
 109 ^^^^^
 110 .. code-block::
 111
 112   usage: openstack overcloud role show [-h] [--roles-path <roles directory>]
 113                                        <role>
 114
 115   Show information about a given role
 116
 117   positional arguments:
 118     <role>                Role to display more information about.
 119
 120   optional arguments:
 121     -h, --help            show this help message and exit
 122     --roles-path <roles directory>
 123                           Filesystem path containing the role yaml files. By
 124                           default this is /usr/share/openstack-tripleo-heat-
 125                           templates/roles
 126
 127 Example
 128 ^^^^^^^
 129 .. code-block::
 130
 131   [user@host ~]$ openstack overcloud role show Compute
 132   ###############################################################################
 133   # Role Data for 'Compute'
 134   ###############################################################################
 135   HostnameFormatDefault: '%stackname%-novacompute-%index%'
 136   ServicesDefault:
 137    * OS::TripleO::Services::AuditD
 138    * OS::TripleO::Services::CACerts
 139    * OS::TripleO::Services::CephClient
 140    * OS::TripleO::Services::CephExternal
 141    * OS::TripleO::Services::CertmongerUser
 142    * OS::TripleO::Services::Collectd
 143    * OS::TripleO::Services::ComputeCeilometerAgent
 144    * OS::TripleO::Services::ComputeNeutronCorePlugin
 145    * OS::TripleO::Services::ComputeNeutronL3Agent
 146    * OS::TripleO::Services::ComputeNeutronMetadataAgent
 147    * OS::TripleO::Services::ComputeNeutronOvsAgent
 148    * OS::TripleO::Services::Docker
 149    * OS::TripleO::Services::FluentdClient
 150    * OS::TripleO::Services::Kernel
 151    * OS::TripleO::Services::MySQLClient
 152    * OS::TripleO::Services::NeutronSriovAgent
 153    * OS::TripleO::Services::NeutronVppAgent
 154    * OS::TripleO::Services::NovaCompute
 155    * OS::TripleO::Services::NovaLibvirt
 156    * OS::TripleO::Services::Ntp
 157    * OS::TripleO::Services::OpenDaylightOvs
 158    * OS::TripleO::Services::Securetty
 159    * OS::TripleO::Services::SensuClient
 160    * OS::TripleO::Services::Snmp
 161    * OS::TripleO::Services::Sshd
 162    * OS::TripleO::Services::Timezone
 163    * OS::TripleO::Services::TripleoFirewall
 164    * OS::TripleO::Services::TripleoPackages
 165    * OS::TripleO::Services::Vpp
 166   name: 'Compute'
 167
 168 Generate roles_data.yaml
 169 ------------------------
 170 The ``openstack overcloud roles generate`` command can be used to generate
 171 a roles_data.yaml file for deployments.
 172
 173 Usage
 174 ^^^^^
 175 .. code-block::
 176
 177   usage: openstack overcloud roles generate [-h]
 178                                             [--roles-path <roles directory>]
 179                                             [-o <output file>]
 180                                             <role> [<role> ...]
 181
 182   Generate roles_data.yaml file
 183
 184   positional arguments:
 185     <role>                List of roles to use to generate the roles_data.yaml
 186                           file for the deployment. NOTE: Ordering is important
 187                           if no role has the "primary" and "controller" tags. If
 188                           no role is tagged then the first role listed will be
 189                           considered the primary role. This usually is the
 190                           controller role.
 191
 192   optional arguments:
 193     -h, --help            show this help message and exit
 194     --roles-path <roles directory>
 195                           Filesystem path containing the role yaml files. By
 196                           default this is /usr/share/openstack-tripleo-heat-
 197                           templates/roles
 198     -o <output file>, --output-file <output file>
 199                           File to capture all output to. For example,
 200                           roles_data.yaml
 201
 202 Example
 203 ^^^^^^^
 204 .. code-block::
 205
 206   [user@host ~]$ openstack overcloud roles generate -o roles_data.yaml Controller Compute BlockStorage ObjectStorage CephStorage