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  * networks: (list), optional list of networks which the role will have
  62    access to when network isolation is enabled. The names should match
  63    those defined in network_data.yaml.
  64
  65 Working with Roles
  66 ==================
  67 The tripleoclient provides a series of commands that can be used to view
  68 roles and generate a roles_data.yaml file for deployment.
  69
  70 Listing Available Roles
  71 -----------------------
  72 The ``openstack overcloud role list`` command can be used to view the list
  73 of roles provided by tripleo-heat-templates.
  74
  75 Usage
  76 ^^^^^
  77 .. code-block::
  78
  79   usage: openstack overcloud role list [-h] [--roles-path <roles directory>]
  80
  81   List availables roles
  82
  83   optional arguments:
  84     -h, --help            show this help message and exit
  85     --roles-path <roles directory>
  86                           Filesystem path containing the role yaml files. By
  87                           default this is /usr/share/openstack-tripleo-heat-
  88                           templates/roles
  89
  90 Example
  91 ^^^^^^^
  92 .. code-block::
  93
  94   [user@host ~]$ openstack overcloud role list
  95   BlockStorage
  96   CephStorage
  97   Compute
  98   Controller
  99   ControllerOpenstack
 100   Database
 101   Messaging
 102   Networker
 103   ObjectStorage
 104   Telemetry
 105   Undercloud
 106
 107 Viewing Role Details
 108 --------------------
 109 The ``openstack overcloud role show`` command can be used as a quick way to
 110 view some of the information about a role.
 111
 112 Usage
 113 ^^^^^
 114 .. code-block::
 115
 116   usage: openstack overcloud role show [-h] [--roles-path <roles directory>]
 117                                        <role>
 118
 119   Show information about a given role
 120
 121   positional arguments:
 122     <role>                Role to display more information about.
 123
 124   optional arguments:
 125     -h, --help            show this help message and exit
 126     --roles-path <roles directory>
 127                           Filesystem path containing the role yaml files. By
 128                           default this is /usr/share/openstack-tripleo-heat-
 129                           templates/roles
 130
 131 Example
 132 ^^^^^^^
 133 .. code-block::
 134
 135   [user@host ~]$ openstack overcloud role show Compute
 136   ###############################################################################
 137   # Role Data for 'Compute'
 138   ###############################################################################
 139   HostnameFormatDefault: '%stackname%-novacompute-%index%'
 140   ServicesDefault:
 141    * OS::TripleO::Services::AuditD
 142    * OS::TripleO::Services::CACerts
 143    * OS::TripleO::Services::CephClient
 144    * OS::TripleO::Services::CephExternal
 145    * OS::TripleO::Services::CertmongerUser
 146    * OS::TripleO::Services::Collectd
 147    * OS::TripleO::Services::ComputeCeilometerAgent
 148    * OS::TripleO::Services::ComputeNeutronCorePlugin
 149    * OS::TripleO::Services::ComputeNeutronL3Agent
 150    * OS::TripleO::Services::ComputeNeutronMetadataAgent
 151    * OS::TripleO::Services::ComputeNeutronOvsAgent
 152    * OS::TripleO::Services::Docker
 153    * OS::TripleO::Services::FluentdClient
 154    * OS::TripleO::Services::Kernel
 155    * OS::TripleO::Services::MySQLClient
 156    * OS::TripleO::Services::NeutronSriovAgent
 157    * OS::TripleO::Services::NeutronVppAgent
 158    * OS::TripleO::Services::NovaCompute
 159    * OS::TripleO::Services::NovaLibvirt
 160    * OS::TripleO::Services::Ntp
 161    * OS::TripleO::Services::OpenDaylightOvs
 162    * OS::TripleO::Services::Securetty
 163    * OS::TripleO::Services::SensuClient
 164    * OS::TripleO::Services::Snmp
 165    * OS::TripleO::Services::Sshd
 166    * OS::TripleO::Services::Timezone
 167    * OS::TripleO::Services::TripleoFirewall
 168    * OS::TripleO::Services::TripleoPackages
 169    * OS::TripleO::Services::Vpp
 170   name: 'Compute'
 171
 172 Generate roles_data.yaml
 173 ------------------------
 174 The ``openstack overcloud roles generate`` command can be used to generate
 175 a roles_data.yaml file for deployments.
 176
 177 Usage
 178 ^^^^^
 179 .. code-block::
 180
 181   usage: openstack overcloud roles generate [-h]
 182                                             [--roles-path <roles directory>]
 183                                             [-o <output file>]
 184                                             <role> [<role> ...]
 185
 186   Generate roles_data.yaml file
 187
 188   positional arguments:
 189     <role>                List of roles to use to generate the roles_data.yaml
 190                           file for the deployment. NOTE: Ordering is important
 191                           if no role has the "primary" and "controller" tags. If
 192                           no role is tagged then the first role listed will be
 193                           considered the primary role. This usually is the
 194                           controller role.
 195
 196   optional arguments:
 197     -h, --help            show this help message and exit
 198     --roles-path <roles directory>
 199                           Filesystem path containing the role yaml files. By
 200                           default this is /usr/share/openstack-tripleo-heat-
 201                           templates/roles
 202     -o <output file>, --output-file <output file>
 203                           File to capture all output to. For example,
 204                           roles_data.yaml
 205
 206 Example
 207 ^^^^^^^
 208 .. code-block::
 209
 210   [user@host ~]$ openstack overcloud roles generate -o roles_data.yaml Controller Compute BlockStorage ObjectStorage CephStorage