3rdparty/modules/rabbitmq/README.md

   1 # rabbitmq
   2
   3 [![License](https://img.shields.io/github/license/voxpupuli/puppet-rabbitmq.svg)](https://github.com/voxpupuli/puppet-rabbitmq/blob/master/LICENSE)
   4 [![Build Status](https://travis-ci.org/voxpupuli/puppet-rabbitmq.svg?branch=master)](https://travis-ci.org/voxpupuli/puppet-rabbitmq)
   5 [![Code Coverage](https://coveralls.io/repos/github/voxpupuli/puppet-rabbitmq/badge.svg?branch=master)](https://coveralls.io/github/voxpupuli/puppet-rabbitmq)
   6 [![Puppet Forge](https://img.shields.io/puppetforge/v/puppet/rabbitmq.svg)](https://forge.puppetlabs.com/puppet/rabbitmq)
   7 [![Puppet Forge - downloads](https://img.shields.io/puppetforge/dt/puppet/rabbitmq.svg)](https://forge.puppetlabs.com/puppet/rabbitmq)
   8 [![Puppet Forge - endorsement](https://img.shields.io/puppetforge/e/puppet/rabbitmq.svg)](https://forge.puppetlabs.com/puppet/rabbitmq)
   9 [![Puppet Forge - scores](https://img.shields.io/puppetforge/f/puppet/rabbitmq.svg)](https://forge.puppetlabs.com/puppet/rabbitmq)
  10
  11 #### Table of Contents
  12
  13 1. [Overview](#overview)
  14 2. [Module Description - What the module does and why it is useful](#module-description)
  15 3. [Setup - The basics of getting started with rabbitmq](#setup)
  16     * [What rabbitmq affects](#what-rabbitmq-affects)
  17     * [Setup requirements](#setup-requirements)
  18 4. [Usage - Configuration options and additional functionality](#usage)
  19 5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
  20 5. [Limitations - OS compatibility, etc.](#limitations)
  21    * [RedHat module dependencies](#redhat-module-dependecies)
  22 6. [Development - Guide for contributing to the module](#development)
  23
  24 ## Overview
  25
  26 This module manages RabbitMQ (www.rabbitmq.com)
  27
  28 ## Module Description
  29 The rabbitmq module sets up rabbitmq and has a number of providers to manage
  30 everything from vhosts to exchanges after setup.
  31
  32 This module has been tested against 3.5.x and 3.6.x (as well as earlier
  33 versions) and is known to not support all features against versions
  34 prior to 2.7.1.
  35
  36 ## Setup
  37
  38 ### What rabbitmq affects
  39
  40 * rabbitmq repository files.
  41 * rabbitmq package.
  42 * rabbitmq configuration file.
  43 * rabbitmq service.
  44
  45 ## Usage
  46
  47 All options and configuration can be done through interacting with the parameters
  48 on the main rabbitmq class.
  49 These are now documented via [Puppet Strings](https://github.com/puppetlabs/puppet-strings)
  50
  51 For convenience, some examples are duplicated here:
  52
  53 ## rabbitmq class
  54
  55 To begin with the rabbitmq class controls the installation of rabbitmq.  In here
  56 you can control many parameters relating to the package and service, such as
  57 disabling puppet support of the service:
  58
  59 ```puppet
  60 class { 'rabbitmq':
  61   service_manage    => false,
  62   port              => '5672',
  63   delete_guest_user => true,
  64 }
  65 ```
  66
  67 For RabbitMQ versions < 3.6.0 (which don't use Ranch), you will need to
  68 manually set `config_ranch` to `false`.
  69
  70 ### Environment Variables
  71 To use RabbitMQ Environment Variables, use the parameters `environment_variables` e.g.:
  72
  73 ```puppet
  74 class { 'rabbitmq':
  75   port                  => 5672,
  76   environment_variables => {
  77     'NODENAME'    => 'node01',
  78     'SERVICENAME' => 'RabbitMQ'
  79   }
  80 }
  81 ```
  82
  83 ### Variables Configurable in rabbitmq.config
  84 To change RabbitMQ Config Variables in rabbitmq.config, use the parameters `config_variables` e.g.:
  85
  86 ```puppet
  87 class { 'rabbitmq':
  88   port             => 5672,
  89   config_variables => {
  90     'hipe_compile' => true,
  91     'frame_max'    => 131072,
  92     'log_levels'   => "[{connection, info}]"
  93   }
  94 }
  95 ```
  96
  97 To change Erlang Kernel Config Variables in rabbitmq.config, use the parameters
  98 `config_kernel_variables` e.g.:
  99
 100 ```puppet
 101 class { 'rabbitmq':
 102   port                    => 5672,
 103   config_kernel_variables => {
 104     'inet_dist_listen_min' => 9100,
 105     'inet_dist_listen_max' => 9105,
 106   }
 107 }
 108 ```
 109
 110 To change Management Plugin Config Variables in rabbitmq.config, use the parameters
 111 `config_management_variables` e.g.:
 112
 113 ```puppet
 114 class { 'rabbitmq':
 115   config_management_variables => {
 116     'rates_mode' => 'basic',
 117   }
 118 }
 119 ```
 120
 121 ### Additional Variables Configurable in rabbitmq.config
 122 To change Additional Config Variables in rabbitmq.config, use the parameter
 123 `config_additional_variables` e.g.:
 124
 125 ```puppet
 126 class { 'rabbitmq':
 127   config_additional_variables => {
 128     'autocluster' => '[{consul_service, "rabbit"},{cluster_name, "rabbit"}]',
 129     'foo'         => '[{bar, "baz"}]'
 130   }
 131 }
 132 ```
 133 This will result in the following config appended to the config file:
 134 ```
 135 % Additional config
 136   {autocluster, [{consul_service, "rabbit"},{cluster_name, "rabbit"}]},
 137   {foo, [{bar, "baz"}]}
 138 ```
 139 (This is required for the [autocluster plugin](https://github.com/aweber/rabbitmq-autocluster)
 140
 141 ### Clustering
 142 To use RabbitMQ clustering facilities, use the rabbitmq parameters
 143 `config_cluster`, `cluster_nodes`, and `cluster_node_type`, e.g.:
 144
 145 ```puppet
 146 class { 'rabbitmq':
 147   config_cluster           => true,
 148   cluster_nodes            => ['rabbit1', 'rabbit2'],
 149   cluster_node_type        => 'ram',
 150   erlang_cookie            => 'A_SECRET_COOKIE_STRING',
 151   wipe_db_on_cookie_change => true,
 152 }
 153 ```
 154
 155 ### rabbitmq\_user
 156
 157 query all current users: `$ puppet resource rabbitmq_user`
 158
 159 ```puppet
 160 rabbitmq_user { 'dan':
 161   admin    => true,
 162   password => 'bar',
 163 }
 164 ```
 165 Optional parameter tags will set further rabbitmq tags like monitoring, policymaker, etc.
 166 To set the administrator tag use admin-flag.
 167 ```puppet
 168 rabbitmq_user { 'dan':
 169   admin    => true,
 170   password => 'bar',
 171   tags     => ['monitoring', 'tag1'],
 172 }
 173 ```
 174
 175 ### rabbitmq\_vhost
 176
 177 query all current vhosts: `$ puppet resource rabbitmq_vhost`
 178
 179 ```puppet
 180 rabbitmq_vhost { 'myvhost':
 181   ensure => present,
 182 }
 183 ```
 184
 185 ### rabbitmq\_exchange
 186
 187 ```puppet
 188 rabbitmq_exchange { 'myexchange@myvhost':
 189   ensure      => present,
 190   user        => 'dan',
 191   password    => 'bar',
 192   type        => 'topic',
 193   internal    => false,
 194   auto_delete => false,
 195   durable     => true,
 196   arguments   => {
 197     hash-header => 'message-distribution-hash'
 198   }
 199 }
 200 ```
 201
 202 ### rabbitmq\_queue
 203
 204 ```puppet
 205 rabbitmq_queue { 'myqueue@myvhost':
 206   ensure      => present,
 207   user        => 'dan',
 208   password    => 'bar',
 209   durable     => true,
 210   auto_delete => false,
 211   arguments   => {
 212     x-message-ttl          => 123,
 213     x-dead-letter-exchange => 'other'
 214   },
 215 }
 216 ```
 217
 218 ### rabbitmq\_binding
 219
 220 ```puppet
 221 rabbitmq_binding { 'myexchange@myqueue@myvhost':
 222   ensure           => present,
 223   user             => 'dan',
 224   password         => 'bar',
 225   destination_type => 'queue',
 226   routing_key      => '#',
 227   arguments        => {},
 228 }
 229 ```
 230
 231 ```puppet
 232 rabbitmq_binding { 'binding 1':
 233   ensure           => present,
 234   source           => 'myexchange',
 235   destination      => 'myqueue',
 236   vhost            => 'myvhost',
 237   user             => 'dan',
 238   password         => 'bar',
 239   destination_type => 'queue',
 240   routing_key      => 'key1',
 241   arguments        => {},
 242 }
 243
 244 rabbitmq_binding { 'binding 2':
 245   ensure           => present,
 246   source           => 'myexchange',
 247   destination      => 'myqueue',
 248   vhost            => 'myvhost',
 249   user             => 'dan',
 250   password         => 'bar',
 251   destination_type => 'queue',
 252   routing_key      => 'key2',
 253   arguments        => {},
 254 }
 255
 256 ```
 257
 258 ### rabbitmq\_user\_permissions
 259
 260 ```puppet
 261 rabbitmq_user_permissions { 'dan@myvhost':
 262   configure_permission => '.*',
 263   read_permission      => '.*',
 264   write_permission     => '.*',
 265 }
 266 ```
 267
 268 ### rabbitmq\_policy
 269
 270 ```puppet
 271 rabbitmq_policy { 'ha-all@myvhost':
 272   pattern    => '.*',
 273   priority   => 0,
 274   applyto    => 'all',
 275   definition => {
 276     'ha-mode'      => 'all',
 277     'ha-sync-mode' => 'automatic',
 278   },
 279 }
 280 ```
 281
 282 ### rabbitmq\_plugin
 283
 284 query all currently enabled plugins `$ puppet resource rabbitmq_plugin`
 285
 286 ```puppet
 287 rabbitmq_plugin {'rabbitmq_stomp':
 288   ensure => present,
 289 }
 290 ```
 291
 292 ### rabbitmq\_parameter
 293
 294 ```puppet
 295   rabbitmq_parameter { 'documentumShovel@/':
 296     component_name => '',
 297     value          => {
 298         'src-uri'    => 'amqp://',
 299         'src-queue'  => 'my-queue',
 300         'dest-uri'   => 'amqp://remote-server',
 301         'dest-queue' => 'another-queue',
 302     },
 303   }
 304
 305   rabbitmq_parameter { 'documentumFed@/':
 306     component_name => 'federation-upstream',
 307     value          => {
 308         'uri'     => 'amqp://myserver',
 309         'expires' => '360000',
 310     },
 311   }
 312 ```
 313
 314 ## Reference
 315
 316 ## Classes
 317
 318 * rabbitmq: Main class for installation and service management.
 319 * rabbitmq::config: Main class for rabbitmq configuration/management.
 320 * rabbitmq::install: Handles package installation.
 321 * rabbitmq::params: Different configuration data for different systems.
 322 * rabbitmq::service: Handles the rabbitmq service.
 323 * rabbitmq::repo::apt: Handles apt repo for Debian systems.
 324 * rabbitmq::repo::rhel: Handles rpm repo for Redhat systems.
 325
 326 ### Module dependencies
 327
 328 If running CentOS/RHEL, ensure the epel repo, or another repo containing a
 329 suitable Erlang version, is present. On Debian systems, puppetlabs/apt
 330 (>=2.0.0 < 5.0.0) is a soft dependency.
 331
 332 To have a suitable erlang version installed on RedHat and Debian systems,
 333 you have to install another puppet module from http://forge.puppetlabs.com/garethr/erlang with:
 334
 335     puppet module install garethr-erlang
 336
 337 This module handles the packages for erlang.
 338 To use the module, add the following snippet to your site.pp or an appropriate profile class:
 339
 340 For RedHat systems:
 341
 342     include 'erlang'
 343     class { 'erlang': epel_enable => true}
 344
 345 For Debian systems:
 346
 347     include 'erlang'
 348     package { 'erlang-base':
 349       ensure => 'latest',
 350     }
 351
 352 This module also depends on voxpupuli/archive to install rabbitmqadmin.
 353
 354 ## Development
 355
 356 This module is maintained by [Vox Pupuli](https://voxpupuli.org/). Voxpupuli
 357 welcomes new contributions to this module, especially those that include
 358 documentation and rspec tests. We are happy to provide guidance if necessary.
 359
 360 Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for more details.
 361
 362 ### Authors
 363 * Jeff McCune <jeff@puppetlabs.com>
 364 * Dan Bode <dan@puppetlabs.com>
 365 * RPM/RHEL packages by Vincent Janelle <randomfrequency@gmail.com>
 366 * Puppetlabs Module Team
 367 * Voxpupuli Team