3rdparty/modules/keystone/README.md

   1 keystone
   2 =======
   3
   4 5.1.0 - 2014.2 - Juno
   5
   6 #### Table of Contents
   7
   8 1. [Overview - What is the keystone module?](#overview)
   9 2. [Module Description - What does the module do?](#module-description)
  10 3. [Setup - The basics of getting started with keystone](#setup)
  11 4. [Implementation - An under-the-hood peek at what the module is doing](#implementation)
  12 5. [Limitations - OS compatibility, etc.](#limitations)
  13 6. [Development - Guide for contributing to the module](#development)
  14 7. [Contributors - Those with commits](#contributors)
  15 8. [Release Notes - Notes on the most recent updates to the module](#release-notes)
  16
  17 Overview
  18 --------
  19
  20 The keystone module is a part of [Stackforge](https://github.com/stackfoge), an effort by the Openstack infrastructure team to provide continuous integration testing and code review for Openstack and Openstack community projects not part of the core software.  The module its self is used to flexibly configure and manage the identify service for Openstack.
  21
  22 Module Description
  23 ------------------
  24
  25 The keystone module is a thorough attempt to make Puppet capable of managing the entirety of keystone.  This includes manifests to provision region specific endpoint and database connections.  Types are shipped as part of the keystone module to assist in manipulation of configuration files.
  26
  27 This module is tested in combination with other modules needed to build and leverage an entire Openstack software stack.  These modules can be found, all pulled together in the [openstack module](https://github.com/stackfoge/puppet-openstack).
  28
  29 Setup
  30 -----
  31
  32 **What the keystone module affects**
  33
  34 * keystone, the identify service for Openstack.
  35
  36 ### Installing keystone
  37
  38     example% puppet module install puppetlabs/keystone
  39
  40 ### Beginning with keystone
  41
  42 To utilize the keystone module's functionality you will need to declare multiple resources.  The following is a modified excerpt from the [openstack module](https://github.com/stackfoge/puppet-openstack).  This is not an exhaustive list of all the components needed, we recommend you consult and understand the [openstack module](https://github.com/stackforge/puppet-openstack) and the [core openstack](http://docs.openstack.org) documentation.
  43
  44 **Define a keystone node**
  45
  46 ```puppet
  47 class { 'keystone':
  48   verbose        => True,
  49   catalog_type   => 'sql',
  50   admin_token    => 'random_uuid',
  51   sql_connection => 'mysql://keystone_admin:super_secret_db_password@openstack-controller.example.com/keystone',
  52 }
  53
  54 # Adds the admin credential to keystone.
  55 class { 'keystone::roles::admin':
  56   email        => 'admin@example.com',
  57   password     => 'super_secret',
  58 }
  59
  60 # Installs the service user endpoint.
  61 class { 'keystone::endpoint':
  62   public_address   => '10.16.0.101',
  63   admin_address    => '10.16.1.101',
  64   internal_address => '10.16.2.101',
  65   region           => 'example-1',
  66 }
  67 ```
  68
  69 **Leveraging the Native Types**
  70
  71 Keystone ships with a collection of native types that can be used to interact with the data stored in keystone.  The following, related to user management could live throughout your Puppet code base.  They even support puppet's ability to introspect the current environment much the same as `puppet resource user`, `puppet resouce keystone_tenant` will print out all the currently stored tenants and their parameters.
  72
  73 ```puppet
  74 keystone_tenant { 'openstack':
  75   ensure  => present,
  76   enabled => True,
  77 }
  78 keystone_user { 'openstack':
  79   ensure  => present,
  80   enabled => True,
  81 }
  82 keystone_role { 'admin':
  83   ensure => present,
  84 }
  85 keystone_user_role { 'admin@openstack':
  86   roles => ['admin', 'superawesomedude'],
  87   ensure => present
  88 }
  89 ```
  90
  91 These two will seldom be used outside openstack related classes, like nova or cinder.  These are modified examples form Class['nova::keystone::auth'].
  92
  93 ```puppet
  94 # Setup the nova keystone service
  95 keystone_service { 'nova':
  96   ensure      => present,
  97   type        => 'compute',
  98   description => 'Openstack Compute Service',
  99 }
 100
 101 # Setup nova keystone endpoint
 102 keystone_endpoint { 'example-1-west/nova':
 103    ensure       => present,
 104    public_url   => "http://127.0.0.1:8774/v2/%(tenant_id)s",
 105    admin_url    => "http://127.0.0.1:8774/v2/%(tenant_id)s",
 106    internal_url => "http://127.0.0.1:8774/v2/%(tenant_id)s",
 107 }
 108 ```
 109
 110 **Setting up a database for keystone**
 111
 112 A keystone database can be configured separately from the keystone services.
 113
 114 If one needs to actually install a fresh database they have the choice of mysql or postgres.  Use the mysql::server or postgreql::server classes to do this setup then the Class['keystone::db::mysql'] or Class['keystone::db::postgresql'] for adding the needed databases and users that will be needed by keystone.
 115
 116 * For mysql
 117
 118 ```puppet
 119 class { 'mysql::server': }
 120
 121 class { 'keystone::db::mysql':
 122   password      => 'super_secret_db_password',
 123   allowed_hosts => '%',
 124 }
 125 ```
 126
 127 * For postgresql
 128
 129 ```puppet
 130 class { 'postgresql::server': }
 131
 132 class { 'keystone::db::postgresql': password => 'super_secret_db_password', }
 133 ```
 134
 135 Implementation
 136 --------------
 137
 138 ### keystone
 139
 140 keystone is a combination of Puppet manifest and ruby code to delivery configuration and extra functionality through types and providers.
 141
 142 Limitations
 143 ------------
 144
 145 * All the keystone types use the CLI tools and so need to be ran on the keystone node.
 146
 147 ### Upgrade warning
 148
 149 * If you've setup Openstack using previous versions of this module you need to be aware that it used UUID as the dedault to the token_format parameter but now defaults to PKI.  If you're using this module to manage a Grizzly Openstack deployment that was set up using a development release of the modules or are attempting an upgrade from Folsom then you'll need to make sure you set the token_format to UUID at classification time.
 150
 151 Development
 152 -----------
 153
 154 Developer documentation for the entire puppet-openstack project.
 155
 156 * https://wiki.openstack.org/wiki/Puppet-openstack#Developer_documentation
 157
 158 Contributors
 159 ------------
 160
 161 * https://github.com/stackforge/puppet-keystone/graphs/contributors
 162
 163 Release Notes
 164 -------------
 165
 166 **5.1.0**
 167
 168 * Allow disabling or delaying the token_flush cron
 169 * crontab: ensure the script is run with shell
 170 * Use openstackclient for keystone_* providers
 171 * Add lib directories to $LOAD_PATH if not present
 172 * Remove keystone.rb provider for keystone_endpoint
 173 * Add timeout to API requests
 174 * Test keystone_user password with Net::HTTP
 175 * service_identity: add user/role ordering
 176 * Fix password check for SSL endpoints
 177 * add require json for to_json dependency
 178 * spec: pin rspec-puppet to 1.0.1
 179 * Switch to TLSv1
 180 * handle missing project/tenant when using ldap backend
 181 * Add support for LDAP connection pools
 182 * Sync keystone.py with upstream to function with Juno
 183 * Create resource cache upon creation
 184 * Implement caching lookup for keystone_user_role
 185 * Remove warnings from openstack responses
 186 * Properly handle embedded newlines in csv
 187 * support the ldap user_enabled_invert parameter
 188 * Shorten HTTP request timeout length
 189 * Tag packages with 'openstack'
 190 * Allow Keystone to be queried when using IPv6 ::0
 191 * Add ::keystone::policy class for policy management
 192 * New option replace_password for keystone_user
 193 * Pin puppetlabs-concat to 1.2.1 in fixtures
 194 * Set WSGI process display-name
 195 * Rename resource instance variable
 196 * Add native types for keystone paste configuration
 197 * Update .gitreview file for project rename
 198
 199 **5.0.0**
 200
 201 * Stable Juno release
 202 * Updated token driver, logging, and ldap config parameters for Juno
 203 * Changed admin_roles parameter to accept an array in order to configure multiple admin roles
 204 * Installs python-ldappool package for ldap
 205 * Added new parameters to keystone class to configure pki signing
 206 * Changed keystone class to inherit from keystone::params
 207 * Changed pki_setup to run regardless of token provider
 208 * Made UUID the default token provider
 209 * Made keystone_user_role idempotent
 210 * Added parameters to control whether to configure users
 211 * Stopped managing _member_ role since it is created automatically
 212 * Stopped overriding token_flush log file
 213 * Changed the usage of admin_endpoint to not include the API version
 214 * Allowed keystone_user_role to accept email as username
 215 * Added ability to set up keystone using Apache mod_wsgi
 216 * Migrated the keystone::db::mysql class to use openstacklib::db::mysql and deprecated the mysql_module parameter
 217 * Installs python-memcache when using token driver memcache
 218 * Enabled setting cert and key paths for PKI token signing
 219 * Added parameters for SSL communication between keystone and rabbitmq
 220 * Added parameter ignore_default_tenant to keystone::role::admin
 221 * Added parameter service_provider to keystone class
 222 * Added parameters for service validation to keystone class
 223
 224 **4.2.0**
 225
 226 * Added class for extended logging options
 227 * Fixed rabbit password leaking
 228 * Added parameters to set tenant descriptions
 229 * Fixed keystone user authorization error handling
 230
 231 **4.1.0**
 232
 233 * Added token flushing with cron.
 234 * Updated database api for consistency with other projects.
 235 * Fixed admin_token with secret parameter.
 236 * Fixed deprecated catalog driver.
 237
 238 **4.0.0**
 239
 240 * Stable Icehouse release.
 241 * Added template_file parameter to specify catalog.
 242 * Added keystone::config to handle additional custom options.
 243 * Added notification parameters.
 244 * Added support for puppetlabs-mysql 2.2 and greater.
 245 * Fixed deprecated sql section header in keystone.conf.
 246 * Fixed deprecated bind_host parameter.
 247 * Fixed example for native type keystone_service.
 248 * Fixed LDAP module bugs.
 249 * Fixed variable for host_access dependency.
 250 * Reduced default token duration to one hour.
 251
 252 **3.2.0**
 253
 254 * Added ability to configure any catalog driver.
 255 * Ensures log_file is absent when using syslog.
 256
 257 **3.1.1**
 258
 259 * Fixed inconsistent variable for mysql allowed hosts.
 260
 261 **3.1.0**
 262
 263 * Added ability to disable pki_setup.
 264 * Load tenant un-lazily if needed.
 265 * Add log_dir param, with option to disable.
 266 * Updated endpoint argument.
 267 * Added support to enable SSL.
 268 * Removes setting of Keystone endpoint by default.
 269 * Relaxed regex when keystone refuses connections.
 270
 271 **3.0.0**
 272
 273 * Major release for OpenStack Havana.
 274 * Fixed duplicated keystone endpoints.
 275 * Refactored keystone_endpoint to use prefetch and flush paradigm.
 276 * Switched from signing/format to token/provider.
 277 * Created memcache_servers option to allow for multiple cache servers.
 278 * Enabled serving Keystone from Apache mod_wsgi.
 279 * Moved db_sync to its own class.
 280 * Removed creation of Member role.
 281 * Improved performance of Keystone providers.
 282 * Updated endpoints to support paths and ssl.
 283 * Added support for token expiration parameter.
 284
 285 **2.2.0**
 286
 287 * Optimized tenant and user queries.
 288 * Added syslog support.
 289 * Added support for token driver backend.
 290 * Various bug and lint fixes.
 291
 292 **2.1.0**
 293
 294 * Tracks release of puppet-quantum
 295 * Fixed allowed_hosts contitional statement
 296 * Pinned depedencies
 297 * Select keystone endpoint based on SSL setting
 298 * Improved tenant_hash usage in keystone_tenant
 299 * Various cleanup and bug fixes.
 300
 301 **2.0.0**
 302
 303 * Upstream is now part of stackfoge.
 304 * keystone_user can be used to change passwords.
 305 * service tenant name now configurable.
 306 * keystone_user is now idempotent.
 307 * Various cleanups and bug fixes.