emqx

A Puppet module that is used for installing and configuring an EMQX MQTT Broker.

For more information, please visit EMQX

Table of Contents

1. Description
2. Setup
   • What emqx affects
   • Setup requirements
   • Beginning with emqx
3. Usage
4. Limitations
5. Development

Description

This Puppet module is used to do a basic installation of the EMQX MQTT Broker.

Setup

What emqx affects

The emqx module configures the following:

• Downloads and installs the emqx software package
• Configures the emqx.conf configuration file
• Manages the emqx service

Setup Requirements

Please refer to the EMQX Installation documenation for minimum requirements for an EMQX MQTT Broker installation.

Note: This module has currently only been tested on Amazon Linux and EL8.

Beginning with emqx

In order to get started with the emqx module with a basic configuration:

include emqx

Usage

Hiera Support

This module supports the use of Hiera data for setting parameters. The following is a list of parameters configurable in Hiera (Please refer to REFERENCE.md for more details):

emqx::install_package_source: 
emqx::install_version: 
emqx::install_platform: 
emqx::install_package_extension: 
emqx::service_ensure: 
emqx::service_enable: true
emqx::manage_config: true
emqx::config_node_name: 
emqx::config_node_cookie: 
emqx::config_node_data_dir: 
emqx::config_node_options: 
emqx::config_cluster_name: 
emqx::config_cluster_discovery_strategy: 
emqx::config_cluster_options: 
emqx::config_dashboard_listeners_ssl:
emqx::config_dashboard_listeners_bind: 
emqx::config_dashboard_listeners_options:
emqx::config_authorization_options:
  deny_action:
  no_match:
  cache:
emqx::config_additional_configs:

Setting the Node cookie configuration

The key emqx::config_node_cookie is a sensitive variable. If overiding this value in a different layer of hiera (e.g. the environment layer), add the following configuration in common.yaml to convert the value to be sensitive.

lookup_options:
  emqx::config_node_cookie:
    convert_to: "Sensitive"

Setting other configuration option paths

Currently the emqx module has direct parameters for setting configurations under the node, cluster, dashboard.listener.http/dashboard.listener.https and authorization configuration paths. However, it is also possible to set configurations for other configuration option paths using the parameter emqx::config_additional_configs as the following yaml hash follows:

Format

emqx::config_additional_configs:
  <configuration_path_x>
    <field_x_1>: <value_x_1>
    <field_x_2>: <value_x_2>
  <configuration_path_y>
    <field_y_1>: <value_y_1>

Example:

emqx::config_additional_configs:
  force_shutdown:
    enable: false
    max_heap_size: "128MB"

For more information regarding the EMQX configuration paths and fields, visit EMQX configuration documentation.

Limitations

• Currently this module is limited to configurations possible in emqx.conf

Development

If you would like to contribute with the development of this module, please feel free to log development changes in the issues register for this project.

Reference

Table of Contents

Classes

Public Classes

• emqx: A basic module for managing emqx

Private Classes

• emqx::config: Manage emqx.conf configuration file
• emqx::install: Manage install of emqx
• emqx::service: Manage emqx service

Classes

emqx

Installs and configures the emqx package and service

Examples

include emqx

Parameters

The following parameters are available in the emqx class:

• install_package_source
• install_version
• install_platform
• install_package_extension
• service_ensure
• service_enable
• manage_config
• config_node_name
• config_node_cookie
• config_node_data_dir
• config_node_options
• config_cluster_name
• config_cluster_discovery_strategy
• config_cluster_options
• config_dashboard_listeners_ssl
• config_dashboard_listeners_bind
• config_dashboard_listeners_options
• config_authorization_options
• config_additional_configs

install_package_source

Data type: String

The location to source the package from.

Default value: 'https://www.emqx.com/en/downloads/broker'

install_version

Data type: String

The version of emqx. Default: '5.0.25'

Default value: '5.0.25'

install_platform

Data type: String

The os platform in order to download the required package.

Default value: 'el8'

install_package_extension

Data type: String

The file extension for the package.

Default value: 'rpm'

service_ensure

Data type: Variant[Enum['running', 'stopped'], Boolean]

The state of the service.

Default value: 'running'

service_enable

Data type: Boolean

Boolean for enabling/disabling the service.

Default value: true

manage_config

Data type: Boolean

Boolean for setting whether to manage emqx.conf.

Default value: true

config_node_name

Data type: String[1]

String for setting the name field for the node config path.

Default value: 'emqx@127.0.0.1'

config_node_cookie

Data type: Sensitive[String[1]]

Sensitive string for setting the cookie field for the node config path.

Default value: Sensitive('emqxsecretcookie')

config_node_data_dir

Data type: String

String for setting the data_dir field for the node config path.

Default value: '/var/lib/emqx'

config_node_options

Data type: Hash

Hash for setting additional fields under the node config path. Note: Do not set name, cooke and data_dir fields here.

Default value: {}

config_cluster_name

Data type: String[1]

String for setting the name field for the cluster config path.

Default value: 'emqxcl'

config_cluster_discovery_strategy

Data type: Enum['manual','static','mcast','dns','etcd','k8s']

Enum String for setting the discovery_strategy field for the cluster config path.

Default value: 'manual'

config_cluster_options

Data type: Hash

Hash for setting additional fields under the cluster config path. Note: Do not set name, cooke and data_dir fields here. Note: Do not set name and discovery_strategy fields here.

Default value: {}

config_dashboard_listeners_ssl

Data type: Boolean

Boolean for setting ssl for the dashboard listener configuration. i.e. Use config path if true dashboard.listeners.https, else dashboard.listeners.http.

Default value: false

config_dashboard_listeners_bind

Data type: Variant[Integer,String[1]]

Integer or String for setting the emqx dashboard bind address as either a port or bind ip:port respectively.

Default value: 18083

config_dashboard_listeners_options

Data type: Hash

Hash for setting additional fields under the dashboard.listeners.http or dashboard.listeners.https config path. Note: Do not set bind and option fields here.

Default value: {}

config_authorization_options

Data type: Hash

Hash for setting additional fields under the authorization config path.

Default value:

{
  deny_action => 'ignore',
  no_match => 'allow',
  cache => '{ enable = true }',
}

config_additional_configs

Data type: Hash

Hash for setting additional config paths and fields. Note: Do not set the following config_paths here: node, cluster, dashboard, authorization.

Default value: {}

Changelog

All notable changes to this project will be documented in this file.

Release v0.2.0

Features

• Update PDK Template to 3.3.0 #7
• Update for Puppet 8 compatibility #8

Bugfixes

Known Issues

Release v0.1.0

Features

• Initial Release - Basic configuration of EMQX MQTT Broker

Bugfixes

Known Issues