AxonOps Ansible Collection

Built and maintained by AxonOps

AxonOps can be used either via our SaaS service or you can install it locally in your environment.

This collection provides Ansible roles and playbooks to deploy AxonOps components. The examples below show how you can install the AxonOps server with OpenSearch or Elasticsearch® and Cassandra® to store metrics and configurations, and how you can install the AxonOps agent to connect to your Apache Cassandra cluster.

For on-premises deployments, OpenSearch is the preferred search backend. The opensearch role is included in this collection and provides a complete, production-ready OpenSearch deployment with automatic TLS certificate generation, multi-node cluster support, and Security plugin configuration. Elasticsearch remains supported for existing deployments.

Ansible is an open-source IT automation platform that enables organizations to automate various IT processes, including provisioning, configuration management, application deployment, and orchestration. It operates as an agentless system, using remote connections via SSH or Windows Remote Management to execute tasks. Ansible is widely used for its simplicity and flexibility, allowing users to define infrastructure as code. For more information about Ansible, visit the Ansible project documentation.

Although this example project has been implemented using Ansible, it is possible to achieve similar results using alternative tools like Chef or Puppet, offering flexibility for those who prefer different automation solutions.

Before you start

⚠️ BREAKING CHANGE NOTICE IMPORTANT: Between releases v0.2.x and v0.3.x, the default Apache Cassandra installation method has changed.

• Previous default: cassandra_install_format: pkg
• New default: cassandra_install_format: tar

The tar method is strongly recommended as it simplifies upgrades and downgrades compared to package-based installations.

🔧 If you are upgrading from a previous version of this role, please review your configuration and explicitly set the cassandra_install_format to match your environment.

Role Documentation

This collection provides the following Ansible roles. Click on each role for detailed documentation, configuration options, and examples:

AxonOps Components

• agent - Install and configure AxonOps Agent for Cassandra monitoring
• server - Install and configure AxonOps Server (self-hosted deployments)
• dash - Install and configure AxonOps Dashboard web interface
• configurations - Configure alerts, integrations, and monitoring settings
• cqlai - Install CQL AI, the AI-powered CQL shell for Apache Cassandra

Kubernetes / Operator

• operator - Install the AxonOps Kubernetes operator and deploy AxonOpsPlatform custom resources
• k8ssandra - Deploy Cassandra 5.x on Kubernetes using the K8ssandra operator with AxonOps images
• strimzi - Deploy Apache Kafka on Kubernetes using the Strimzi operator with AxonOps images

Infrastructure Components

• cassandra - Install and configure Apache Cassandra (3.11, 4.x, 5.x)
• kafka - Install and configure Apache Kafka in KRaft mode (no ZooKeeper)
• opensearch - Install and configure OpenSearch for AxonOps (preferred for on-premises)
• elastic - Install and configure Elasticsearch for AxonOps
• java - Install Java (OpenJDK or Azul Zulu)

Security

• pki_agent - Automated PKI certificate management using OpenBao Agent

Utilities

• preflight - Run pre-installation system checks

For a complete guide including deployment patterns and quick references, see the Role Documentation Index.

Playbooks

Installing the collection

From Ansible Galaxy (recommended)

The collection is published on Ansible Galaxy. Install it with:

ansible-galaxy collection install axonops.axonops

To install a specific version:

ansible-galaxy collection install axonops.axonops:==0.5.1

To declare it as a dependency, add it to your requirements.yml:

collections:
  - name: axonops.axonops

Then install with:

ansible-galaxy collection install -r requirements.yml

From GitHub

Download the latest release from GitHub. Then use ansible-galaxy to install the tarball into a directory configured in COLLECTIONS_PATHS.

ansible-galaxy collection install <downloaded_tar>

You may also use this short script to download and install the latest version:

LATEST=$(curl -s https://api.github.com/repos/axonops/axonops-ansible-collection/releases/latest | jq -r '.assets[0].browser_download_url')
ansible-galaxy collection install $LATEST

Inventory

Before you can start using these playbooks you'll need to add your nodes to the inventory. You can find an example in the ./examples directory. There are two sections:

• axon-server: list here the IP address or hostname of the server where you would like to install AxonOps
• cassandra: these are the Apache Cassandra nodes where the agent will be installed

Examples

axon-agent.yml

This playbook deploys the AxonOps Agent to Cassandra nodes. If you do not need to install Apache Cassandra, set the switch install_cassandra to false.

If you have a local mirror repositories of the AxonOps, Elastic and Cassandra packages adjust the *_redhat_repository URLs.

- name: Deploy AxonOps Agent
  hosts: cassandra
  become: true
  vars:
    axon_java_agent: "axon-cassandra4.1-agent"
    customer_name: example
    java_pkg: java-11-openjdk-headless
    # Set to false if you already have Apache Cassandra running
    install_cassandra: true

  roles:
    - role: axonops.axonops.cassandra
      tags: cassandra
      when: install_cassandra
      vars:
        cassandra_dc: "example"

    - role: axonops.axonops.agent
      tags: agent, axonops-agent
      vars:
        axon_agent_server_host: "{{ groups['axon-server'] | first }}"
        cassandra_dc: "DC1"
        cassandra_seeds: "{{ groups['cassandra'] | map('extract', hostvars, ['ansible_default_ipv4', 'address']) | list | first }}"

axon-server.yml (note - you do not need to use this if connecting to the SaaS)

This playbook deploys the AxonOps Server. It installs a local Apache Cassandra server for metrics storage and a search backend (OpenSearch or Elasticsearch) for the AxonOps configuration.

OpenSearch is recommended for on-premises deployments. For more information see roles/opensearch/README.md. For Elasticsearch, see roles/elastic/README.md.

Note: For AxonOps server version >= 2.0.4, the search backend configuration uses a search_db.hosts array format. The axon_server_searchdb_hosts variable accepts a list of URLs and works with both OpenSearch and Elasticsearch endpoints.

With OpenSearch (recommended for on-premises)

- name: Deploy AxonOps Server with OpenSearch
  hosts: axon-server
  become: true
  vars:
    # OpenSearch
    opensearch_cluster_name: axonops
    opensearch_cluster_type: single-node
    opensearch_admin_password: "{{ vault_opensearch_admin_password }}"
    opensearch_domain_name: example.com

    # AxonOps Server
    axon_server_license_key: "{{ vault_axonops_license_key }}"
    axon_server_cql_hosts:
      - localhost:9042
    axon_server_searchdb_hosts:
      - "https://127.0.0.1:9200"
    axon_server_searchdb_username: admin
    axon_server_searchdb_password: "{{ vault_opensearch_admin_password }}"
    axon_server_searchdb_tls_skip_verify: true
    axon_dash_listen_address: 0.0.0.0

  roles:
    - role: axonops.axonops.cassandra
      tags: cassandra
    - role: axonops.axonops.opensearch
      tags: opensearch
    - role: axonops.axonops.server
      tags: server, axonops-server
    - role: axonops.axonops.dash
      tags: dash, axonops-dashboard

With Elasticsearch (legacy / existing deployments)

- name: Deploy AxonOps Server with Elasticsearch
  hosts: axon-server
  become: true
  vars:
    install_cassandra: true
    install_elastic: true
    java_pkg: java-17-openjdk-headless
    axon_server_cql_hosts:
      - localhost:9042
    axon_server_searchdb_hosts:
      - http://127.0.0.1:9200
    axon_dash_listen_address: 0.0.0.0
    axon_agent_redhat_repository: "https://packages.axonops.com/yum"
    es_redhat_repository_url: https://artifacts.elastic.co/packages/7.x/yum

  roles:
    - role: axonops.axonops.cassandra
      tags: cassandra
      when: install_cassandra is defined and install_cassandra
    - role: axonops.axonops.elastic
      tags: elastic
      when: install_elastic is defined and install_elastic
    - role: axonops.axonops.server
      tags: server, axonops-server
    - role: axonops.axonops.dash
      tags: dash, axonops-dashboard

---

This project may contain trademarks or logos for projects, products, or services. Any use of third-party trademarks or logos are subject to those third-party's policies. AxonOps is a registered trademark of AxonOps Limited. Apache, Apache Cassandra, Cassandra, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Elasticsearch is a trademark of Elasticsearch B.V., registered in the U.S. and in other countries. Docker is a trademark or registered trademark of Docker, Inc. in the United States and/or other countries.