Orchestrating Connectware with Ansible

How to orchestrate Connectware deployments and services using Ansible, including setup, playbook creation, and lifecycle management.

This guide shows you how to use Ansible to set up and manage a local Connectware instance. You will learn how to deploy Connectware, install services, and manage the instance lifecycle using infrastructure as code.

Prerequisites

Before starting, ensure you have the following installed on your system:

• Ansible (latest version)

• Docker

• Docker Compose

• A valid Connectware license key

This guide assumes you are familiar with:

• Connectware and its service concept

• Docker fundamentals

• Ansible basics (ansible.com - Getting started with Ansible)

What is the Connectware Ansible Collection?

Ansible is an open-source infrastructure automation tool that enables infrastructure as code. Cybus provides a specialized Ansible Collection with custom modules designed to manage every aspect of Connectware deployments.

The collection provides the following modules to help you manage Connectware resources:

Module	Purpose
instance	Manages Connectware instances
service	Manages Connectware services
role	Manages Connectware roles
user	Manages Connectware users
agent	Manages agent instances

Step 1 - Installing the Ansible Collection

• Install the Connectware Ansible Collection from Ansible Galaxy:

ansible-galaxy collection install cybus.connectware

Verifying the Installation

ansible-galaxy collection list

Updating an Existing Installation

ansible-galaxy collection install cybus.connectware --force

Step 2 - Creating Your First Playbook

Setting Up the Project

1. Create a new project directory:

mkdir connectware-ansible-demo
cd connectware-ansible-demo

1. Create a playbook file named playbook.yaml:

---
- name: Connectware Deployment
  hosts: localhost

  tasks:
    - name: Deploy Connectware instance
      cybus.connectware.instance:
        license: 'YOUR_LICENSE_KEY_HERE'
        install_path: ./

Important: Replace YOUR_LICENSE_KEY_HERE with your actual Connectware license key.

Understanding the Playbook Structure

• Play: "Connectware Deployment" runs on localhost

• Task: "Deploy Connectware instance" uses the cybus.connectware.instance module

• Parameters:

  • license: Your Connectware license (required)

  • install_path: Directory for deployment files (current directory)

Exploring Module Options

• View all available parameters for the instance module:

ansible-doc cybus.connectware.instance

Step 3 - Deploying Connectware

Running this playbook will install and start Connectware on your local system, making it accessible via https://localhost.

• Execute the following playbook to deploy Connectware:

ansible-playbook playbook.yaml

Expected Output

After running the playbook, you should see output like this:

[WARNING]: No inventory was parsed, only implicit localhost is available
[WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all'

PLAY [Connectware Deployment] ***************************************************************************

TASK [Gathering Facts] ***************************************************************************
ok: [localhost]

TASK [Deploy Connectware] ***************************************************************************
changed: [localhost]

PLAY RECAP ***************************************************************************
localhost: ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Notice that the state of the Deploy Connectware task is marked as changed. This indicates that Connectware is now running and is reachable at https://localhost.

In addition to the log output, you should now find two new files next to playbook.yaml. One is the Docker Compose file managing the Connectware containers, and the other contains additional configuration.

Result

• Connectware is now running and accessible at: https://localhost

• Two new files were created:

  • docker-compose.yml: Container orchestration file

  • A configuration file with additional settings

Verifying Idempotency

• Run the playbook again to verify that no changes occur:

ansible-playbook playbook.yaml

Notice the task shows ok instead of changed, confirming the desired state is maintained.

Step 4 - Deploying a Service

Creating a Service Definition

• Create a file named example-service.yml with a basic service configuration:

---
description: Example Service demonstrating MQTT connection

metadata:
  name: example_service

resources:
  mqttConnection:
    type: Cybus::Connection
    properties:
      protocol: Mqtt
      connection:
        host: !ref Cybus::MqttHost
        port: !ref Cybus::MqttPort
        scheme: mqtt
        username: !ref Cybus::MqttUser
        password: !ref Cybus::MqttPassword

This service creates a connection to the internal Connectware MQTT broker.

Updating the Playbook

• Add a service installation task to your playbook.yaml:

---
- name: Connectware Deployment
  hosts: localhost

  tasks:
    - name: Deploy Connectware instance
      cybus.connectware.instance:
        license: 'YOUR_LICENSE_KEY_HERE'
        install_path: ./

    - name: Install example service
      cybus.connectware.service:
        id: example_service
        commissioning_file: ./example-service.yml

Service Module Parameters

These parameters let you uniquely identify your service and provide the service commissioning file, ensuring Connectware can correctly install and configure it.

• id: Unique identifier for the service (required)

• commissioning_file: Path to the service definition file (required)

Learn more about the service module:

ansible-doc cybus.connectware.service

Deploying the Service

• Run the updated playbook:

ansible-playbook playbook.yaml

The output should show the service installation as changed. Verify the service is installed by visiting the Connectware UI at: https://localhost/admin/#/services.

Step 5 - Managing Instance Lifecycle

Stopping Connectware

• To stop the Connectware instance, add a task with the stopped state:

- name: Stop Connectware instance
  cybus.connectware.instance:
    state: stopped
    license: 'YOUR_LICENSE_KEY_HERE'
    install_path: ./

After running this playbook, Connectware will be stopped and no longer accessible.

Available States

The instance module supports different states:

• started (default): Ensures Connectware is running

• stopped: Ensures Connectware is stopped

• absent: Removes the Connectware installation