Another Way to Use Ansible to Automate the Configuration of Solace PubSub+ Event Broker

Managing and configuring a number of Solace PubSub+ event brokers – or even a single one – in a consistent and repeatable manner is a crucial requirement for production deployments.

Though the PubSub+ Event Broker itself supports a number of configuration options such as a REST API, you still need to implement logic to manage a configuration, apply configurations consistently, and re-apply configurations in a safe manner. In addition, removing a configuration is just as important during the development lifecycle of your project. This is where tools such as Ansible come in useful.

For a few recent engagements we were looking into how we can address this and came across a number of open source projects set up by Solace colleagues and end-user, such as this one: Automating Solace configuration management using SEMP and Ansible. The most promising project we found was Mark Street’s ansible-solace. As he describes in his blog, the project was developed for in-house production use, so it was sufficiently battle hardened. The project defines a framework for creating Ansible tasks for the Solace PubSub+ SEMP API and in its initial version supported all the most important resources on the broker. We required additional resources for our projects such as Bridges, DMR Cluster configuration, and REST Delivery Points (RDP). Fortunately, adding tasks was pretty simple due to the foundation that Mark Street et al had built.

What’s the current state of ansible-solace?

It supports a majority of Message VPN and broker-level resources that are manageable via REST/SEMPv2.

Message VPN Level:

• Message VPN
• ACL Profile
• Client Username
• Client Profile
• Queue and Queue Subscriptions
• Topic Endpoint
• Bridge
• Rest Delivery Point

Broker Level:

• Certificate Authority
• DMR Bridge and Link

Note: Some of these resources are not available in Solace PubSub+ Event Broker: Cloud – such as Client Profile and the broker-level resources, so these respective tasks only work for self-managed deployments.

Getting Started with Ansible-Solace

The quickest way to get started is to head over to the ansible-solace-samples GitHub repository.

Sample projects using ansible-solaceby solace-iot-teamFollow the instructions in the README, clone it, and run the sample projects.Open on GitHub

If you want to look at the code, the development repository lives here: https://github.com/solace-iot-team/ansible-solace-modules.

Using the Ansible Tasks

All tasks have common parameters describing which broker to connect to via SEMPv2 Administrator API. The defaults are set to work against a local broker with the standard admin username and password – e.g. deployed in docker following one of Solace’s Docker Install Guides.

These are the connection parameters:
username: "{{ username }}"
password: "{{ password }}"
host: "{{ host }}"
port: "{{ port }}"
secure_connection: "{{ secure_connection }}"
timeout: 30

Username and password are of the management user, e.g. admin on a locally installed broker. Port is the management port – 8080 by default for plain connections or 943 for HTTPS in Solace PubSub+ Event Broker: Cloud. The secure connection parameter can be set to “True” to switch to the HTTPS protocol.

As usual, in Ansible you can use variables or facts to set these dynamically as required.

Here’s a basic example to create a VPN:

- name: Playbook to add a vpn named 'foo'
  hosts: localhost
  tasks:
  - name: Add 'foo' VPN
    solace_vpn:
      name: foo
      state: present # default state
      settings:
        enabled: true
        dmrEnabled: false
        eventTransactionCountThreshold:
          clearPercent: 66
          setPercent: 98

It is pretty straightforward, but there are a few things to note:

• You can request the state of the resource – present or absent. The ansible tasks will choose the right SEMPv2 method (POST, PATCH, DELETE) accordingly.
• We have omitted the connection parameters for better legibility.
• The settings dictionary can pass in additional arguments to the POST/PATCH call.

The last point is important as all tasks have the settings argument and you can pass in any parameters that the underlying REST resource supports. It is helpful to have the SEMPv2 developer documentation ready when writing your playbooks.

Looking at the create Message VPN resource operation, we discover the settings in the example above and we can also find the other parameters we could set such as those enabling MQTT Connectivity for example.

If we wanted to update the message VPN created by the playbook above to enable plain text MQTT, the playbook looks like this:

- 
name: Playbook to configure plain text MQTT on a vpn named 'foo'
hosts: localhost
tasks:
  - name: Add 'foo' VPN
    solace_vpn:
      name: foo
      state: present 
      settings:
        serviceMqttPlainTextEnabled: true
        serviceMqttPlainTextListenPort: 1883

This playbook will preserve the state of the message VPN in all other aspects.

What if we wanted to delete the message VPN? The playbook looks like this:

- 
name: Playbook to delete a vpn named 'foo'
hosts: localhost
tasks:
  - name: Add 'foo' VPN
    solace_vpn:
      name: foo
      state: absent

Finally, let’s see how we can connect to a remote broker via HTTPS with a non-default password to create a Message VPN:

- 
  name: Playbook to add a vpn named 'foo'
  hosts: localhost
  tasks:
  - name: Add 'foo' VPN
    solace_vpn:
      password: "secret!"
      host: remote-broker.com
      port: 943
      secure_connection: true
      name: foo
      state: present # default state
      settings:
        enabled: true
        dmrEnabled: false
        eventTransactionCountThreshold:
          clearPercent: 66
          setPercent: 98

How to contribute?

If you find anything that’s missing or could be improved, we value all contributions. You can start by forking our repository and we will be happy to incorporate your pull requests. As stated above, there’s a base class that makes it really easy to add additional modules. The easiest way is to clone an existing module and adjust it as needed. Here’s a detailed guide on module development.