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)
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
28 The openstacklib module is a library module for other Openstack modules to
29 utilize. A thorough description will be added later.
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).
38 ### Installing openstacklib
40 example% puppet module install puppetlabs/openstacklib
45 ### Classes and Defined Types
47 #### Defined type: openstacklib::db::mysql
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.
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.
56 For example, in heat::db::mysql you might declare:
59 ::openstacklib::db::mysql { 'heat':
60 password_hash => mysql_password($password),
66 allowed_hosts => $allowed_hosts,
67 notify => Exec['heat-dbsync'],
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:
75 ::openstacklib::db::mysql { 'keystone':
76 password_hash => mysql_password($password),
82 allowed_hosts => $allowed_hosts,
83 notify => Exec['keystone-manage db_sync'],
84 before => Service['keystone'],
88 ** Parameters for openstacklib::db::mysql: **
91 Password hash to use for the database user for this service;
95 The name of the database
96 string; optional; default to the $title of the resource, i.e. 'nova'
99 The database user to create;
100 string; optional; default to the $title of the resource, i.e. 'nova'
103 The IP address or hostname of the user in mysql_grant;
104 string; optional; default to '127.0.0.1'
107 The charset to use for the database;
108 string; optional; default to 'utf8'
111 The collate to use for the database;
112 string; optional; default to 'utf8_general_ci'
115 Additional hosts that are allowed to access this database;
116 array or string; optional; default to undef
119 Privileges given to the database user;
120 string or array of strings; optional; default to 'ALL'
122 #### Defined type: openstacklib::db::postgresql
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.
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.
131 For example, in heat::db::postgresql you might declare:
134 ::openstacklib::db::postgresql { $dbname:
135 password_hash => postgresql_password($user, $password),
138 notify => Exec['heat-dbsync'],
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:
146 ::openstacklib::db::postgresql { $dbname:
147 password_hash => postgresql_password($user, $password),
150 notify => Exec['keystone-manage db_sync'],
151 before => Service['keystone'],
155 ** Parameters for openstacklib::db::postgresql: **
158 Password hash to use for the database user for this service;
162 The name of the database
163 string; optional; default to the $title of the resource, i.e. 'nova'
166 The database user to create;
167 string; optional; default to the $title of the resource, i.e. 'nova'
170 The encoding use for the database;
171 string; optional; default to undef
174 Privileges given to the database user;
175 string or array of strings; optional; default to 'ALL'
177 #### Defined type: openstacklib::service_validation
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.
182 For example, in nova::api you might declare:
185 ::openstacklib::service_validation { 'nova-api':
186 command => 'nova list',
189 This defined resource creates an exec-anchor pair where the anchor depends upon
190 the successful exec run.
192 ** Parameters for openstacklib::service_validation: **
195 Command to run for validating the service;
199 The name of the service to validate;
200 string; optional; default to the $title of the resource, i.e. 'nova-api'
203 The path of the command to validate the service;
204 string; optional; default to '/usr/bin:/bin:/usr/sbin:/sbin'
207 The provider to use for the exec command;
208 string; optional; default to 'shell'
211 Number of times to retry validation;
212 string; optional; default to '10'
215 Number of seconds between validation attempts;
216 string; optional; default to '2'
218 ### Types and Providers
222 #####`Puppet::add_aviator_params`
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
231 require 'puppet/type/aviator'
232 Puppet::Type.newtype(:my_type) do
235 Puppet::add_aviator_params(:my_type)
238 #####`Puppet::Provider::Aviator`
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
244 **`Puppet::Provider::Aviator#authenticate`**
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:
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
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.
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.
264 **`Puppet::Provider::Aviator#make_request`**
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.
278 openstacklib is a combination of Puppet manifest and ruby code to delivery
279 configuration and extra functionality through types and providers.
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.
293 This module has beaker-rspec tests
299 bundle exec rspec spec/acceptance
305 Developer documentation for the entire puppet-openstack project.
307 * https://wiki.openstack.org/wiki/Puppet-openstack#Developer_documentation
312 * https://github.com/stackforge/puppet-openstacklib/graphs/contributors
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:
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