Quickstart for Solace PubSub+ Ansible Collection

Installation & Dependencies

requires_ansible: ">=2.10,<=2.13"

Prerequisites:

• install python >=3.8

• install docker

Download the python dependencies: requirements:

requests>=2.25.0
xmltodict>=0.12.0
docker-compose

Install:

# upgrade to latest pip3
$ python3 -m pip install --upgrade pip
$ pip install -r requirements.txt
$ pip install ansible

Note

Installing a specific version of ansible:

pip install "ansible>=2.10.3,<2.11", # for latest ansible_core 2.10
pip install "ansible>=4.10.0,<5.0.0", # for latest ansible_core 2.11
pip install "ansible>=5.1.0,<6.0.0" # for latest ansible core 2.12

Install the Solace PubSub+ Ansible Collection:

$ ansible-galaxy collection install solace.pubsub_plus

Playbooks

We need to run two playbooks:

• service.playbook.yml: creates a local broker service running in docker and generates the broker inventory file

• configure.playbook.yml: configures the broker service we have just created

service.playbook.yml:

-
  name: Quickstart Service Playbook
  hosts: localhost
  gather_facts: true
  any_errors_fatal: true
  tasks:
  - name: "Broker service up"
    include_role:
      name: solace.pubsub_plus.solace_broker_service
    vars:
      docker_compose_settings:
        project_name: quickstart_broker_service_single_node
        state: present

  - name: "Save inventory"
    block:
      - file:
          path: "{{ WORKING_DIR }}"
          state: directory
      - copy:
          content: "{{ solace_broker_service_result.broker_service.inventory | to_nice_yaml(indent=2) }}"
          dest: "{{ WORKING_DIR }}/broker.inventory.yml"
    delegate_to: localhost

configure.playbook.yml:

-
  name: Quickstart Configure Playbook
  hosts: all
  gather_facts: no
  any_errors_fatal: true
  collections:
    - solace.pubsub_plus
  module_defaults:
    solace.pubsub_plus.solace_queue:
      host: "{{ sempv2_host }}"
      port: "{{ sempv2_port }}"
      secure_connection: "{{ sempv2_is_secure_connection }}"
      username: "{{ sempv2_username }}"
      password: "{{ sempv2_password }}"
      timeout: "{{ sempv2_timeout }}"
      msg_vpn: "{{ vpn }}"
    solace.pubsub_plus.solace_queue_subscription:
      host: "{{ sempv2_host }}"
      port: "{{ sempv2_port }}"
      secure_connection: "{{ sempv2_is_secure_connection }}"
      username: "{{ sempv2_username }}"
      password: "{{ sempv2_password }}"
      timeout: "{{ sempv2_timeout }}"
      msg_vpn: "{{ vpn }}"
  tasks:

    - name: create queue
      solace_queue:
        name: quickstart_queue

    - name: add subscription
      solace_queue_subscription:
        queue: quickstart_queue
        name: "quickstart/topic"

    # create user message
    - set_fact:
        broker_url: "{{ 'https' if sempv2_is_secure_connection else 'http' }}://{{ sempv2_host }}:{{ sempv2_port }}"
    - name: message
      debug:
        msg:
          - "open private browser window: {{ broker_url }}"
          - "login: {{ sempv2_username }} / {{ sempv2_password }}"
          - "vpn: default"
          - "Queues: quickstart_queue"
          - "Subscriptions: quickstart/topic"

Run

When we run the first playbook, the role solace.pubsub_plus.solace_broker_service will download the latest Solace PubSub+ Standard Edition broker and start it on the local machine using Docker. It will also create the inventory file for newly created service in the $WORKING_DIR. The second playbook will then configure two simple objects: a queue and a subscription to the queue.

Run the playbooks using run.sh:

#!/usr/bin/env bash

scriptDir=$(cd $(dirname "$0") && pwd);

# set the python interpreter
  export ANSIBLE_PYTHON_INTERPRETER=$(python3 -c "import sys; print(sys.executable)")

# set verbosity
  export ANSIBLE_VERBOSITY=3

# set the working dir
  WORKING_DIR="$scriptDir/tmp"

# create broker service
  ansible-playbook "$scriptDir/service.playbook.yml" --extra-vars "WORKING_DIR=$WORKING_DIR"
  code=$?; if [[ $code != 0 ]]; then echo ">>> XT_ERROR - $code"; exit 1; fi

# configure broker service
  # enable logging
    export ANSIBLE_SOLACE_ENABLE_LOGGING=True
    export ANSIBLE_SOLACE_LOG_PATH="$WORKING_DIR/ansible-solace.log"
  ansible-playbook -i "$WORKING_DIR/broker.inventory.yml" "$scriptDir/configure.playbook.yml"
  code=$?; if [[ $code != 0 ]]; then echo ">>> XT_ERROR - $code"; exit 1; fi

Open a new private window in your browser and log into the Broker’s admin console at http://localhost:8080 with credentials admin/admin.

Navigate to Queues to see the queue created.

In the $WORKING_DIR you will find two files:

• ansible-solace.log - the log file of all SEMP requests / responses to/from the broker service

• broker.inventory.yml - the generated inventory for the created broker service

Using an Existing Broker / Service

To use an existing standalone broker or Solace Cloud Service, you must provide the inventory file to the playbook configure.playbook.yml.

For a discussion on Ansible Solace Inventory Files, see Best Practices for Ansible-Solace Inventory Files.