Repository files navigation

This is a cookbook for managing RabbitMQ with Chef.

This cookbook targets Chef 14.0 and later.

5.x release series targetsRabbitMQ3.8.x releases.

For any series used, asupported Erlang version must be provisioned.

The cookbook generally targetsthe same Debian-based distribution versions that RabbitMQ core team supports:

• Recent andcommunity supported versions of Ubuntu, e.g. 22.04 and later
• Debian 11 (Bullseye) and 12 (
• RHEL 8+
• CentOS Stream 9
• Fedora 35 or later
• Amazon Linux 2023
• Rocky Linux 9
• Alma Linux 9

Newer Debian, Ubuntu and RHEL/Fedora/CentOS Stream versions should work.

This cookbook depends on theErlang cookbookand assumes that the user can configure it to provision asupported Erlang/OTP version.

Two more recipes are provided by this cookbook:rabbitmq::erlang_package andrabbitmq::esl_erlang_package.The latter is an alias to theerlang::esl recipe in the Erlangcookbook.

The former usesDebian Erlang packages andzero dependency Erlang RPM package produced and published by Team RabbitMQ.Those packages provide the latest patch releases of Erlang/OTP.

Both options are covered below.

To provision RabbitMQ 3.9.x or 3.8.x, you must use version5.8.5 of this cookbook or later.

Before provisioning a 3.9.x or 3.8.x release, please learn abouttheminimum required Erlang/OTP versionand Erlang/OTP version recommendations.

Most distributions provide older versions, so Erlang must be provisioned eitherusingRabbitMQ's zero dependency Erlang RPM,Debian Erlang packages,or fromErlang Solutions

rabbitmq::erlang_package is a recipe that provisions latest Erlang packages from team RabbitMQ.The packages support

• Debian 10 and 11
• Ubuntu 18.04 through 20.04
• RHEL 8
• CentOS Stream 8
• Fedora 32 or later
• Amazon Linux 2022
• Scientific Linux 7

The packages arecannot be installed alongside with other Erlang packages, for example, thosefrom standard Debian repositories or Erlang Solutions.

To make sure that the Erlang cookbook is not used byrabbitmq::default,rabbitmq::cluster,and other recipes, setnode['rabbitmq']['erlang']['enabled'] totrue:

node['rabbitmq']['erlang']['enabled']=true

By defaultrabbitmq::erlang_package will install the latest Erlang version available.To override package version, usenode['rabbitmq']['erlang']['version']:

# Debiannode['rabbitmq']['erlang']['version']='1:24.3.3-1'# RPMnode['rabbitmq']['erlang']['version']='24.3.3'

On Ubuntu and Debian the distribution will be picked from node attributes.

Most of the time there is no need to override other attributes. Below is a list of defaultsused on Ubuntu and Debian:

# RabbitMQ Erlang packagesdeb_distro=value_for_platform('debian'=>{'default'=>'debian'},'ubuntu'=>{'default'=>'ubuntu'})default['rabbitmq']['erlang']['apt']['uri']="https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/#{deb_distro}"default['rabbitmq']['erlang']['apt']['lsb_codename']=node['lsb']['codename']default['rabbitmq']['erlang']['apt']['components']=["main"]default['rabbitmq']['erlang']['apt']['key']='https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key'default['rabbitmq']['erlang']['apt']['install_options']=%w(--fix-missing)

On CentOS Stream 8, base Yum repository URL will be picked based on distribution versions.On Fedora, a suitable CentOS package will be used. Erlang package version is set the same wayas for Debian (see above).

Below are the defaults used by the Yum repository (assuming RHEL or CentOS Stream 8):

# CentOS 8, RHEL 8, Fedoradefault['rabbitmq']['erlang']['yum']['baseurl']='https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/rpm/el/8/$basearch'default['rabbitmq']['erlang']['yum']['gpgkey']='https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key'default['rabbitmq']['erlang']['yum']['gpgcheck']=truedefault['rabbitmq']['erlang']['yum']['repo_gpgcheck']=false

The Erlang cookbook will provisionpackages from Erlang Solutionsifnode['erlang']['install_method'] is set toesl.Note that Erlang Solutions repositories can be behind the latest Erlang/OTP patch releases.

# will install the latest release, please# consult with https://www.rabbitmq.com/which-erlang.html firstnode['erlang']['install_method']="esl"

to provision a specific version, e.g.24.3.3:

node['erlang']['install_method']="esl"# Ubuntu and Debian# note the "1:" package epoch prefixnode['erlang']['esl']['version']="1:24.3.3"

node['erlang']['install_method']="esl"# CentOS, RHEL, Fedoranode['erlang']['esl']['version']="24.3.3-1"

Setnode['rabbitmq']['version'] to specify a version:

node['rabbitmq']['version']="3.9.14"

If you havenode['rabbitmq']['deb_package_url'] ornode['rabbitmq']['rpm_package_url'] overriddenfrom earlier versions, consider omitting those attributes. Otherwise see a section on downloadlocation customization below.

RabbitMQ packages will be downloadedfrom Cloudsmith.

Installsrabbitmq-server via direct download (from Bintray or GitHub, depending on the version) ofthe installation package or using the distribution version. Depending on your distribution,the provided version may be quite old so direct download is the default option.

Set the['rabbitmq']['clustering']['enable'] attribute totrue,['rabbitmq']['clustering']['cluster_disk_nodes']array ofnode@host strings that describe cluster members,and a alphanumeric string for theerlang_cookie.

To enableTLS for client connections, set thessl totrue and set the paths to your cacert, cert and key files.

node['rabbitmq']['ssl']=true# path to the CA bundle filenode['rabbitmq']['ssl_cacert']='/path/to/cacert.pem'# path to the server certificate (pubic key) PEM filenode['rabbitmq']['ssl_cert']='/path/to/cert.pem'# path to the server private key filenode['rabbitmq']['ssl_key']='/path/to/key.pem'

TCP connection listeners may be limited to a specific interfaceusing thenode['rabbitmq']['tcp_listen_interface'] attribute.

ItsTLS connection listener counterpart isnode['rabbitmq']['ssl_listen_interface'].

node['rabbitmq']['deb_package_url'] andnode['rabbitmq']['rpm_package_url'] can be usedto override the package download location. They configure a prefix without a version.Set them to a download location without a version if you want to provision from a customendpoint such as a local mirror.

Thedefault recipe will append a version suffix that matches RabbitMQ tag naming scheme.For3.7.x or later, it is just the version (the value is used as is).

Lastly, a package name will be appended to form a full download URL. They rarely needchanging but can also be overridden using thenode['rabbitmq']['deb_package']andnode['rabbitmq']['rpm_package'] attributes.

A full list of attributes related toTLS in RabbitMQcan be found inattributes/default.rb.

Default values and usage information of important attributes are shown below. More attributes are documented in metadata.rb.

The default username and password areguest/guest, withaccess limited to localhost connections:

['rabbitmq']['default_user']='guest'['rabbitmq']['default_pass']='guest'

It ishighly recommended that a differentdefault user name is used with a reasonably long (say, 30-40 characters)generated password.

By default, the guest usercan only connect from localhost.This prevents remote access for installations that use the well-known default credentials.It ishighly recommended that remote access for the default user is not enabledbut ifsecurity is of absolutely no importance in a certain environment, this can be done:

['rabbitmq']['loopback_users']=[]

Learn more in the RabbitMQAccess Control guide.

It is possible to to load adefinitions (schema) file on node boot.Consult RabbitMQ'sDefinitionsandBackup doc guides to learn more.

To configure definition loading, set the following attribute:

['rabbitmq']['management']['load_definitions'] = true

By default, the node will be configured to load a JSON at/etc/rabbitmq/load_definitions.json;however, you can define another path if you'd prefer using the following attribute:

['rabbitmq']['management']['definitions_file'] = '/path/to/your/definitions.json'

In order to use this functionality, you will need to provision a file referenced by the above attributebefore you execute any recipes in the RabbitMQ cookbook (in other words, before the node starts). For example, this can be doneusing a remote file resource.

Installs theRabbitMQ management plugin.

To enable HTTPS for the management UI and HTTP API, set['rabbitmq']['web_console_ssl'] attribute totrue.The HTTPS port for the management UI can be configured by setting attribute['rabbitmq']['web_console_ssl_port'],whose default value is 15671.

Enables any plugins listed in thenode['rabbitmq']['enabled_plugins'] and disables any listedinnode['rabbitmq']['disabled_plugins'] attributes.

To enable theLDAP plugin, a few attributes have to be usedin combination:

1. Setnode['rabbitmq']['ldap']['enabled'] = true
2. Enableauth_backends:node['rabbitmq']['auth_backends'] = 'rabbit_auth_backend_internal,rabbit_auth_backend_ldap'
3. Enable therabbitmq_auth_backend_ldap plugin
4. Configure LDAP servers and queries via thenode['rabbitmq']['ldap']['conf'] variable

# this is just an examplenode['rabbitmq']['ldap']['conf']={:servers=>["ldap-host1","ldap-host2"],:user_bind_pattern=>"${username}@<domain>",:dn_lookup_attribute=>"sAMAccountName",:dn_lookup_base=>"DC=<CHANGEME>,DC=<CHANGEME>",:port=> <CHANGEME(number)>,:log=> <CHANGEME(boolean)>,:vhost_access_query=>'{constant, true}',:topic_access_query=>'{constant, true}',:resource_access_query=>'{constant, true}',:tag_queries=>"[{administrator, {constant, false}}]"}

Enables anyRabbitMQ users listed in thenode['rabbitmq']['enabled_users'] and disables any listed innode['rabbitmq']['disabled_users'] attributes.You can provide user credentials, the vhosts that they need to have access to and the permissions that should be allocated to each user.

node['rabbitmq']['enabled_users']=[{:name=>'kitten',:password=>'kitten',:tag=>'leader',:rights=>[{:vhost=>'nova',:conf=>'.*',:write=>'.*',:read=>'.*'}]}]

Note that with this approach user credentials will be stored in the attribute file.Using encrypted data bags is therefore highly recommended.

Alternativelydefinitions export and import (see above) can be used.Definition files contain password hashes since clear text values are not stored.

Enables anyvirtual hosts listed in thenode['rabbitmq']['virtualhosts']and disables any listed innode['rabbitmq']['disabled_virtualhosts'] attributes.

Forms acluster RabbitMQ of nodes.

It supports two clustering modes: auto or manual.

• Auto clustering: listscluster members in the RabbitMQ config file. Those are taken from lists the nodesnode['rabbitmq']['clustering']['cluster_nodes'].
• Manual clustering : joins cluter members usingrabbitmqctl join_cluster.

• node['rabbitmq']['clustering']['enable'] : Default decision flag of clustering
• node['rabbitmq']['erlang_cookie'] : Same erlang cookie is required for the cluster
• node['rabbitmq']['clustering']['use_auto_clustering'] : Default is false. (manual clustering is default)
• node['rabbitmq']['clustering']['cluster_name'] : Name of cluster. default value is nil. In case of nil or '' is set forcluster_name, first node name innode['rabbitmq']['clustering']['cluster_nodes'] attribute will be set for manual clustering. for the auto clustering, one of the node name will be set.
• node['rabbitmq']['clustering']['cluster_nodes'] : List of cluster nodes. it required node name and cluster node type. please refer to example in below.

Example

node['rabbitmq']['clustering']['enable']=truenode['rabbitmq']['erlang_cookie']='AnyAlphaNumericStringWillDo'node['rabbitmq']['clustering']['cluster_partition_handling']='pause_minority'node['rabbitmq']['clustering']['use_auto_clustering']=falsenode['rabbitmq']['clustering']['cluster_name']='qa_env'node['rabbitmq']['clustering']['cluster_nodes']=[{:name=>'rabbit@rabbit1'},{:name=>'rabbit@rabbit2'},{:name=>'rabbit@rabbit3'}]

Enables any policies listed in thenode['rabbitmq']['policies'] and disables any listed innode['rabbitmq']['disabled_policies'] attributes.

See examples in attributes file.

Downloads, installs and enables pre-built community plugins binaries.

To specify a plugin, set the attributenode['rabbitmq']['community_plugins']['PLUGIN_NAME'] to'{DOWNLOAD_URL}'.

There are several LWRPs for interacting with RabbitMQ and a few setting up Erlang repositoriesand package.

erlang_apt_repository_on_cloudsmith sets up aDebian package repositoryfrom Cloudsmith.It is a wrapper around the standardapt_repository resource provider.

See alsoRabbitMQ Erlang Compatibility guide.

rabbitmq_erlang_apt_repository_on_cloudsmith'rabbitmq_erlang_repo_on_cloudsmith'dodistributionnode['lsb']['codename']unlessnode['lsb'].nil?action:addend

erlang_apt_repository_on_cloudsmith sets up anRPM package repositoryfrom Bintray.It is a wrapper around the standardapt_repository resource provider.

See alsoRabbitMQ Erlang Compatibility guide.

rabbitmq_erlang_yum_repository_on_cloudsmith'rabbitmq_erlang'do# for RHEL/CentOS 8+, Fedora. See https://www.rabbitmq.com/install-rpm.html.baseurl'https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/rpm/el/8/$basearch'action:addend

Install the package. Here's an example for Debian-based systems:

rabbitmq_erlang_package_from_cloudsmith'rabbitmq_erlang'do# This package version assumes a Debian-based distribution.version'1:24.3.3-1'action:installend

Here's another one for RPM-based ones:

rabbitmq_erlang_package_from_cloudsmith'rabbitmq_erlang'doversion'24.3.3'action:installend

Enables or disables a rabbitmq plugin. Plugins are not supported for releases prior to 2.7.0.

• :enable enables aplugin
• :disable disables aplugin

rabbitmq_plugin"rabbitmq_stomp"doaction:enableend

rabbitmq_plugin"rabbitmq_shovel"doaction:disableend

Sets or clears a RabbitMQpolicy.

• :set sets apolicy
• :clear clears apolicy

rabbitmq_policy"queue-length-limit"dopattern"^limited\\.*"definition({"max-length"=>"3000"})priority1action:setend

Adds and deletesusers:

• :add adds auser with apassword
• :delete deletes auser
• :set_permissions sets thepermissions for auser,vhost is optional
• :clear_permissions clears the permissions for auser
• :set_tags set the tags on a user
• :clear_tags clear any tags on a user
• :change_password set thepassword for auser

rabbitmq_user"guest"doaction:deleteend

rabbitmq_user"nova"dopassword"sekret"action:addend

rabbitmq_user"nova"dovhost"/nova"permissions".* .* .*"action:set_permissionsend

rabbitmq_user"rmq"dovhost["/","/rmq","/nova"]permissions".* .* .*"action:set_permissionsend

rabbitmq_user"joe"dotag"admin,lead"action:set_tagsend

Adds and deletesvirtual hosts.

• :add adds avhost
• :delete deletes avhost

rabbitmq_vhost"/nova"doaction:addend

Forms a cluster and controls cluster name.This is an imperative version ofclassic config peer discovery inmodern RabbitMQ versions.

• :join join in cluster as a manual clustering. node will join in first node of json string data.

• cluster nodes as JSON: all cluster nodes should be listed.

[    {"name" :"rabbit@rabbit1","type" :"disc"    },    {"name" :"rabbit@rabbit2","type":"disc"    },    {"name""rabbit@rabbit3","type" :"disc"    }]

• :set_cluster_name set the cluster name

rabbitmq_cluster'[{"name":"rabbit@rabbit1", "type":"disc"},{"name":"rabbit@rabbit2", "type":"disc"},{"name":"rabbit@rabbit3", "type":"disc"}]'doaction:joinend

rabbitmq_cluster'[{"name":"rabbit@rabbit1","type":"disc"},{"name":"rabbit@rabbit2", ,"type":"disc"},{"name":"rabbit@rabbit3","type":"disc"}]'docluster_name'seoul_tokyo_newyork'action:set_cluster_nameend

rabbitmq_cluster'[{"name":"rabbit@rabbit1","type":"disc"},{"name":"rabbit@rabbit2", ,"type":"disc"},{"name":"rabbit@rabbit3","type":"disc"}]'doaction:change_cluster_node_typeend

This cookbook provides the primitives to remove a node from a cluster via helper functions but do not include these in any recipes. This is something that is potentially very dangerous and different deployments will have different needs and IF you decide you need this it should be implemented in your wrapper with EXTREME caution. There are 2 helper methods for 2 different scenario:

• removing self from cluster. This should likely only be considered for machines on a normal decommission. This is accomplished by using the helper fucntionreset_current_node.
• removing another node from cluster. This should only be done once you are sure the machine is gone and won't come back. This can be accomplished viaremove_remote_node_from_cluster.

For an already running cluster, these actions still require manual intervention:

• changing theshared cluster secret using the:erlang_cookie attribute
• disabling clutering entirely by setting:cluster fromtrue tofalse

• Author:: Benjamin Black
• Author:: Daniel DeLeo
• Author:: Matt Ray
• Author:: Seth Thomas
• Author:: JJ Asghar
• Author:: Team RabbitMQ

Copyright (c) 2009-2018, Chef Software, Inc.Copyright (c) 2018-2021, VMware, Inc. or its affiliates.Licensed under the Apache License, Version 2.0 (the "License");you may not use this file except in compliance with the License.You may obtain a copy of the License at    https://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, softwaredistributed under the License is distributed on an "AS IS" BASIS,WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.See the License for the specific language governing permissions andlimitations under the License.