3rdparty/modules/openstacklib/README.md

   1 openstacklib
   2 ============
   3
   4 5.1.0 - 2014.2 - Juno
   5 #### Table of Contents
   6
   7 1. [Overview - What is the openstacklib module?](#overview)
   8 2. [Module Description - What does the module do?](#module-description)
   9 3. [Setup - The basics of getting started with openstacklib](#setup)
  10 4. [Implementation - An under-the-hood peek at what the module is doing](#implementation)
  11 5. [Limitations - OS compatibility, etc.](#limitations)
  12 6. [Development - Guide for contributing to the module](#development)
  13 7. [Contributors - Those with commits](#contributors)
  14
  15 Overview
  16 --------
  17
  18 The openstacklib module is a part of [Stackforge](https://github.com/stackforge),
  19 an effort by the Openstack infrastructure team to provide continuous integration
  20 testing and code review for Openstack and Openstack community projects not part
  21 of the core software.  The module itself is used to expose common functionality
  22 between Openstack modules as a library that can be utilized to avoid code
  23 duplication.
  24
  25 Module Description
  26 ------------------
  27
  28 The openstacklib module is a library module for other Openstack modules to
  29 utilize. A thorough description will be added later.
  30
  31 This module is tested in combination with other modules needed to build and
  32 leverage an entire Openstack software stack.  These modules can be found, all
  33 pulled together in the [openstack module](https://github.com/stackforge/puppet-openstack).
  34
  35 Setup
  36 -----
  37
  38 ### Installing openstacklib
  39
  40     example% puppet module install puppetlabs/openstacklib
  41
  42 Usage
  43 -----
  44
  45 ### Classes and Defined Types
  46
  47 #### Defined type: openstacklib::db::mysql
  48
  49 The db::mysql resource is a library resource that can be used by nova, cinder,
  50 ceilometer, etc., to create a mysql database with configurable privileges for
  51 a user connecting from defined hosts.
  52
  53 Typically this resource will be declared with a notify parameter to configure
  54 the sync command to execute when the database resource is changed.
  55
  56 For example, in heat::db::mysql you might declare:
  57
  58 ```
  59 ::openstacklib::db::mysql { 'heat':
  60     password_hash => mysql_password($password),
  61     dbname        => $dbname,
  62     user          => $user,
  63     host          => $host,
  64     charset       => $charset,
  65     collate       => $collate,
  66     allowed_hosts => $allowed_hosts,
  67     notify        => Exec['heat-dbsync'],
  68   }
  69 ```
  70
  71 Some modules should ensure that the database is created before the service is
  72 set up. For example, in keystone::db::mysql you would have:
  73
  74 ```
  75 ::openstacklib::db::mysql { 'keystone':
  76     password_hash => mysql_password($password),
  77     dbname        => $dbname,
  78     user          => $user,
  79     host          => $host,
  80     charset       => $charset,
  81     collate       => $collate,
  82     allowed_hosts => $allowed_hosts,
  83     notify        => Exec['keystone-manage db_sync'],
  84     before        => Service['keystone'],
  85   }
  86 ```
  87
  88 ** Parameters for openstacklib::db::mysql: **
  89
  90 #####`password_hash`
  91 Password hash to use for the database user for this service;
  92 string; required
  93
  94 #####`dbname`
  95 The name of the database
  96 string; optional; default to the $title of the resource, i.e. 'nova'
  97
  98 #####`user`
  99 The database user to create;
 100 string; optional; default to the $title of the resource, i.e. 'nova'
 101
 102 #####`host`
 103 The IP address or hostname of the user in mysql_grant;
 104 string; optional; default to '127.0.0.1'
 105
 106 #####`charset`
 107 The charset to use for the database;
 108 string; optional; default to 'utf8'
 109
 110 #####`collate`
 111 The collate to use for the database;
 112 string; optional; default to 'utf8_general_ci'
 113
 114 #####`allowed_hosts`
 115 Additional hosts that are allowed to access this database;
 116 array or string; optional; default to undef
 117
 118 #####`privileges`
 119 Privileges given to the database user;
 120 string or array of strings; optional; default to 'ALL'
 121
 122 #### Defined type: openstacklib::db::postgresql
 123
 124 The db::postgresql resource is a library resource that can be used by nova,
 125 cinder, ceilometer, etc., to create a postgresql database and a user with
 126 configurable privileges.
 127
 128 Typically this resource will be declared with a notify parameter to configure
 129 the sync command to execute when the database resource is changed.
 130
 131 For example, in heat::db::postgresql you might declare:
 132
 133 ```
 134 ::openstacklib::db::postgresql { $dbname:
 135   password_hash => postgresql_password($user, $password),
 136   dbname        => $dbname,
 137   user          => $user,
 138   notify        => Exec['heat-dbsync'],
 139 }
 140 ```
 141
 142 Some modules should ensure that the database is created before the service is
 143 set up. For example, in keystone::db::postgresql you would have:
 144
 145 ```
 146 ::openstacklib::db::postgresql { $dbname:
 147   password_hash => postgresql_password($user, $password),
 148   dbname        => $dbname,
 149   user          => $user,
 150   notify        => Exec['keystone-manage db_sync'],
 151   before        => Service['keystone'],
 152 }
 153 ```
 154
 155 ** Parameters for openstacklib::db::postgresql: **
 156
 157 #####`password_hash`
 158 Password hash to use for the database user for this service;
 159 string; required
 160
 161 #####`dbname`
 162 The name of the database
 163 string; optional; default to the $title of the resource, i.e. 'nova'
 164
 165 #####`user`
 166 The database user to create;
 167 string; optional; default to the $title of the resource, i.e. 'nova'
 168
 169 #####`encoding`
 170 The encoding use for the database;
 171 string; optional; default to undef
 172
 173 #####`privileges`
 174 Privileges given to the database user;
 175 string or array of strings; optional; default to 'ALL'
 176
 177 #### Defined type: openstacklib::service_validation
 178
 179 The service_validation resource is a library resource that can be used by nova, cinder,
 180 ceilometer, etc., to validate that a resource is actually up and running.
 181
 182 For example, in nova::api you might declare:
 183
 184 ```
 185 ::openstacklib::service_validation { 'nova-api':
 186     command => 'nova list',
 187   }
 188 ```
 189 This defined resource creates an exec-anchor pair where the anchor depends upon
 190 the successful exec run.
 191
 192 ** Parameters for openstacklib::service_validation: **
 193
 194 #####`command`
 195 Command to run for validating the service;
 196 string; required
 197
 198 #####`service_name`
 199 The name of the service to validate;
 200 string; optional; default to the $title of the resource, i.e. 'nova-api'
 201
 202 #####`path`
 203 The path of the command to validate the service;
 204 string; optional; default to '/usr/bin:/bin:/usr/sbin:/sbin'
 205
 206 #####`provider`
 207 The provider to use for the exec command;
 208 string; optional; default to 'shell'
 209
 210 #####`tries`
 211 Number of times to retry validation;
 212 string; optional; default to '10'
 213
 214 #####`try_sleep`
 215 Number of seconds between validation attempts;
 216 string; optional; default to '2'
 217
 218 ### Types and Providers
 219
 220 #### Aviator
 221
 222 #####`Puppet::add_aviator_params`
 223
 224 The aviator type is not a real type, but it serves to simulate a mixin model,
 225 whereby other types can call out to the Puppet::add\_aviator\_params method in
 226 order to add aviator-specific parameters to themselves. Currently this adds the
 227 auth parameter to the given type. The method must be called after the type is
 228 declared, e.g.:
 229
 230 ```puppet
 231 require 'puppet/type/aviator'
 232 Puppet::Type.newtype(:my_type) do
 233 # ...
 234 end
 235 Puppet::add_aviator_params(:my_type)
 236 ```
 237
 238 #####`Puppet::Provider::Aviator`
 239
 240 The aviator provider is a parent provider intended to serve as a base for other
 241 providers that need to authenticate against keystone in order to accomplish a
 242 task.
 243
 244 **`Puppet::Provider::Aviator#authenticate`**
 245
 246 Either creates an authenticated session or sets up an unauthenticated session
 247 with instance variables initialized with a token to inject into the next request.
 248 It takes as arguments a set of authentication parameters as a hash and a path
 249 to a log file. Puppet::Provider::Aviator#authencate looks for five different
 250 possible methods of authenticating, in the following order:
 251
 252 1) Username and password credentials in the auth parameters
 253 2) The path to an openrc file containing credentials to read in the auth
 254    parameters
 255 3) A service token in the auth parameters
 256 4) Environment variables set for the environment in which Puppet is running
 257 5) A service token in /etc/keystone/keystone.conf. This option provides
 258    backwards compatibility with earlier keystone providers.
 259
 260 If the provider has password credentials, it can create an authenticated
 261 session. If it only has a service token, it initializes an unauthenciated
 262 session and a hash of session data that can be injected into a future request.
 263
 264 **`Puppet::Provider::Aviator#make_request`**
 265
 266 After creating a session, the make\_request method provides an interface that
 267 providers can use to make requests without worrying about whether they have an
 268 authenticated or unauthenticated session. It takes as arguments the
 269 Aviator::Service it is making a request at (for example, keystone), a symbol for
 270 the request (for example, :list\_tenants), and optionally a block to execute
 271 that will set parameters for an update request.
 272
 273 Implementation
 274 --------------
 275
 276 ### openstacklib
 277
 278 openstacklib is a combination of Puppet manifest and ruby code to delivery
 279 configuration and extra functionality through types and providers.
 280
 281 Limitations
 282 -----------
 283
 284 The python-migrate system package for RHEL 6 and below is out of date and may
 285 fail to correctly migrate postgresql databases. While this module does not
 286 handle database migrations, it is common to set up refresh relationships
 287 between openstacklib::db::postgresql resource and the database sync exec
 288 resource. Relying on this behavior may cause errors.
 289
 290 Beaker-Rspec
 291 ------------
 292
 293 This module has beaker-rspec tests
 294
 295 To run:
 296
 297 ```shell
 298 bundle install
 299 bundle exec rspec spec/acceptance
 300 ```
 301
 302 Development
 303 -----------
 304
 305 Developer documentation for the entire puppet-openstack project.
 306
 307 * https://wiki.openstack.org/wiki/Puppet-openstack#Developer_documentation
 308
 309 Contributors
 310 ------------
 311
 312 * https://github.com/stackforge/puppet-openstacklib/graphs/contributors
 313
 314 Versioning
 315 ----------
 316
 317 This module has been given version 5 to track the puppet-openstack modules. The
 318 versioning for the puppet-openstack modules are as follows:
 319
 320 ```
 321 Puppet Module :: OpenStack Version :: OpenStack Codename
 322 2.0.0         -> 2013.1.0          -> Grizzly
 323 3.0.0         -> 2013.2.0          -> Havana
 324 4.0.0         -> 2014.1.0          -> Icehouse
 325 5.0.0         -> 2014.2.0          -> Juno
 326 ```