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 ### Environment Variables
  68 To use RabbitMQ Environment Variables, use the parameters `environment_variables` e.g.:
  69
  70 ```puppet
  71 class { 'rabbitmq':
  72   port                  => 5672,
  73   environment_variables => {
  74     'NODENAME'    => 'node01',
  75     'SERVICENAME' => 'RabbitMQ'
  76   }
  77 }
  78 ```
  79
  80 ### Variables Configurable in rabbitmq.config
  81 To change RabbitMQ Config Variables in rabbitmq.config, use the parameters `config_variables` e.g.:
  82
  83 ```puppet
  84 class { 'rabbitmq':
  85   port             => 5672,
  86   config_variables => {
  87     'hipe_compile' => true,
  88     'frame_max'    => 131072,
  89     'log_levels'   => "[{connection, info}]"
  90   }
  91 }
  92 ```
  93
  94 To change Erlang Kernel Config Variables in rabbitmq.config, use the parameters
  95 `config_kernel_variables` e.g.:
  96
  97 ```puppet
  98 class { 'rabbitmq':
  99   port                    => 5672,
 100   config_kernel_variables => {
 101     'inet_dist_listen_min' => 9100,
 102     'inet_dist_listen_max' => 9105,
 103   }
 104 }
 105 ```
 106
 107 To change Management Plugin Config Variables in rabbitmq.config, use the parameters
 108 `config_management_variables` e.g.:
 109
 110 ```puppet
 111 class { 'rabbitmq':
 112   config_management_variables => {
 113     'rates_mode' => 'basic',
 114   }
 115 }
 116 ```
 117
 118 ### Additional Variables Configurable in rabbitmq.config
 119 To change Additional Config Variables in rabbitmq.config, use the parameter
 120 `config_additional_variables` e.g.:
 121
 122 ```puppet
 123 class { 'rabbitmq':
 124   config_additional_variables => {
 125     'autocluster' => '[{consul_service, "rabbit"},{cluster_name, "rabbit"}]',
 126     'foo'         => '[{bar, "baz"}]'
 127   }
 128 }
 129 ```
 130 This will result in the following config appended to the config file:
 131 ```
 132 % Additional config
 133   {autocluster, [{consul_service, "rabbit"},{cluster_name, "rabbit"}]},
 134   {foo, [{bar, "baz"}]}
 135 ```
 136 (This is required for the [autocluster plugin](https://github.com/aweber/rabbitmq-autocluster)
 137
 138 ### Clustering
 139 To use RabbitMQ clustering facilities, use the rabbitmq parameters
 140 `config_cluster`, `cluster_nodes`, and `cluster_node_type`, e.g.:
 141
 142 ```puppet
 143 class { 'rabbitmq':
 144   config_cluster           => true,
 145   cluster_nodes            => ['rabbit1', 'rabbit2'],
 146   cluster_node_type        => 'ram',
 147   erlang_cookie            => 'A_SECRET_COOKIE_STRING',
 148   wipe_db_on_cookie_change => true,
 149 }
 150 ```
 151
 152 ### rabbitmq\_user
 153
 154 query all current users: `$ puppet resource rabbitmq_user`
 155
 156 ```puppet
 157 rabbitmq_user { 'dan':
 158   admin    => true,
 159   password => 'bar',
 160 }
 161 ```
 162 Optional parameter tags will set further rabbitmq tags like monitoring, policymaker, etc.
 163 To set the administrator tag use admin-flag.
 164 ```puppet
 165 rabbitmq_user { 'dan':
 166   admin    => true,
 167   password => 'bar',
 168   tags     => ['monitoring', 'tag1'],
 169 }
 170 ```
 171
 172 ### rabbitmq\_vhost
 173
 174 query all current vhosts: `$ puppet resource rabbitmq_vhost`
 175
 176 ```puppet
 177 rabbitmq_vhost { 'myvhost':
 178   ensure => present,
 179 }
 180 ```
 181
 182 ### rabbitmq\_exchange
 183
 184 ```puppet
 185 rabbitmq_exchange { 'myexchange@myvhost':
 186   ensure      => present,
 187   user        => 'dan',
 188   password    => 'bar',
 189   type        => 'topic',
 190   internal    => false,
 191   auto_delete => false,
 192   durable     => true,
 193   arguments   => {
 194     hash-header => 'message-distribution-hash'
 195   }
 196 }
 197 ```
 198
 199 ### rabbitmq\_queue
 200
 201 ```puppet
 202 rabbitmq_queue { 'myqueue@myvhost':
 203   ensure      => present,
 204   user        => 'dan',
 205   password    => 'bar',
 206   durable     => true,
 207   auto_delete => false,
 208   arguments   => {
 209     x-message-ttl          => 123,
 210     x-dead-letter-exchange => 'other'
 211   },
 212 }
 213 ```
 214
 215 ### rabbitmq\_binding
 216
 217 ```puppet
 218 rabbitmq_binding { 'myexchange@myqueue@myvhost':
 219   ensure           => present,
 220   user             => 'dan',
 221   password         => 'bar',
 222   destination_type => 'queue',
 223   routing_key      => '#',
 224   arguments        => {},
 225 }
 226 ```
 227
 228 ```puppet
 229 rabbitmq_binding { 'binding 1':
 230   ensure           => present,
 231   source           => 'myexchange',
 232   destination      => 'myqueue',
 233   vhost            => 'myvhost',
 234   user             => 'dan',
 235   password         => 'bar',
 236   destination_type => 'queue',
 237   routing_key      => 'key1',
 238   arguments        => {},
 239 }
 240
 241 rabbitmq_binding { 'binding 2':
 242   ensure           => present,
 243   source           => 'myexchange',
 244   destination      => 'myqueue',
 245   vhost            => 'myvhost',
 246   user             => 'dan',
 247   password         => 'bar',
 248   destination_type => 'queue',
 249   routing_key      => 'key2',
 250   arguments        => {},
 251 }
 252
 253 ```
 254
 255 ### rabbitmq\_user\_permissions
 256
 257 ```puppet
 258 rabbitmq_user_permissions { 'dan@myvhost':
 259   configure_permission => '.*',
 260   read_permission      => '.*',
 261   write_permission     => '.*',
 262 }
 263 ```
 264
 265 ### rabbitmq\_policy
 266
 267 ```puppet
 268 rabbitmq_policy { 'ha-all@myvhost':
 269   pattern    => '.*',
 270   priority   => 0,
 271   applyto    => 'all',
 272   definition => {
 273     'ha-mode'      => 'all',
 274     'ha-sync-mode' => 'automatic',
 275   },
 276 }
 277 ```
 278
 279 ### rabbitmq\_plugin
 280
 281 query all currently enabled plugins `$ puppet resource rabbitmq_plugin`
 282
 283 ```puppet
 284 rabbitmq_plugin {'rabbitmq_stomp':
 285   ensure => present,
 286 }
 287 ```
 288
 289 ### rabbitmq\_parameter
 290
 291 ```puppet
 292   rabbitmq_parameter { 'documentumShovel@/':
 293     component_name => '',
 294     value          => {
 295         'src-uri'    => 'amqp://',
 296         'src-queue'  => 'my-queue',
 297         'dest-uri'   => 'amqp://remote-server',
 298         'dest-queue' => 'another-queue',
 299     },
 300   }
 301
 302   rabbitmq_parameter { 'documentumFed@/':
 303     component_name => 'federation-upstream',
 304     value          => {
 305         'uri'     => 'amqp://myserver',
 306         'expires' => '360000',
 307     },
 308   }
 309 ```
 310
 311 ## Reference
 312
 313 ## Classes
 314
 315 * rabbitmq: Main class for installation and service management.
 316 * rabbitmq::config: Main class for rabbitmq configuration/management.
 317 * rabbitmq::install: Handles package installation.
 318 * rabbitmq::params: Different configuration data for different systems.
 319 * rabbitmq::service: Handles the rabbitmq service.
 320 * rabbitmq::repo::apt: Handles apt repo for Debian systems.
 321 * rabbitmq::repo::rhel: Handles rpm repo for Redhat systems.
 322
 323 ### Module dependencies
 324
 325 If running CentOS/RHEL, ensure the epel repo, or another repo containing a
 326 suitable Erlang version, is present. On Debian systems, puppetlabs/apt
 327 (>=2.0.0 < 5.0.0) is a soft dependency.
 328
 329 To have a suitable erlang version installed on RedHat and Debian systems,
 330 you have to install another puppet module from http://forge.puppetlabs.com/garethr/erlang with:
 331
 332     puppet module install garethr-erlang
 333
 334 This module handles the packages for erlang.
 335 To use the module, add the following snippet to your site.pp or an appropriate profile class:
 336
 337 For RedHat systems:
 338
 339     include 'erlang'
 340     class { 'erlang': epel_enable => true}
 341
 342 For Debian systems:
 343
 344     include 'erlang'
 345     package { 'erlang-base':
 346       ensure => 'latest',
 347     }
 348
 349 This module also depends on voxpupuli/archive to install rabbitmqadmin.
 350
 351 ## Development
 352
 353 This module is maintained by [Vox Pupuli](https://voxpupuli.org/). Voxpupuli
 354 welcomes new contributions to this module, especially those that include
 355 documentation and rspec tests. We are happy to provide guidance if necessary.
 356
 357 Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for more details.
 358
 359 ### Authors
 360 * Jeff McCune <jeff@puppetlabs.com>
 361 * Dan Bode <dan@puppetlabs.com>
 362 * RPM/RHEL packages by Vincent Janelle <randomfrequency@gmail.com>
 363 * Puppetlabs Module Team
 364 * Voxpupuli Team