Full Lifecycle Automation of RavenDB with Ansible

2. Connect multiple nodes into a working cluster

The RavenDB Ansible Collection isn’t just about provisioning isolated nodes – it also provides modules to help you automate cluster formation.

Up to this point, we’ve deployed three RavenDB nodes. Each is fully installed and running, but they operate independently. In many scenarios, that’s all you need—a set of standalone database nodes.

But in production environments, you’ll often want to form a cluster, where nodes work together, replicate data, and maintain consensus.

Let’s write another playbook:

 

  #  cluster.yaml
  ---
  - name: Form Cluster
    hosts: localhost
    gather_facts: no

    tasks:
      - name: Node B is Watcher
        ravendb.ravendb.node:
          node:
            tag: B
            type: "Watcher"
            url: "http://192.168.100.12:8080"
            leader_url: "http://192.168.100.11:8080"

      - name: Node C is Member
        ravendb.ravendb.node:
          node:
            tag: C
            url: "http://192.168.100.13:8080"
            leader_url: "http://192.168.100.11:8080"

RavenDB nodes must be explicitly joined into a cluster. This is not done at the OS level, but through the RavenDB HTTP API, which is why this task targets localhost (i.e., the Ansible control node) instead of the remote nodes. We’re instructing RavenDB directly to connect the nodes into a cluster.

In this example, we’ll pick node 192.168.100.11 as the cluster leader and join the other two as a Watcher and Member, respectively.

 

In this setup:

• Node A (192.168.100.11) is the cluster leader.
• Node B joins as a Watcher (read-only replica).
• Node C joins as a full Member (with voting rights).

Execute the playbook from your control node:

$ ansible-playbook -i ./inventory ./add_node.yaml

This will send the appropriate HTTP requests to the leader node, instructing it to form a cluster with the additional nodes.

You can confirm that the cluster was formed correctly by querying the topology:

  $ curl "http://192.168.100.11:8080"/cluster/topology | jq -c '.Topology.AllNodes'

  {
   "A":"http://192.168.100.11:8080",
   "B":"http://192.168.100.12:8080",
   "C":"http://192.168.100.13:8080"
  }

And just like that, your RavenDB cluster is up and running, precisely as defined in the playbook.

If you prefer to inspect the cluster topology visually, simply open RavenDB Studio on any of the nodes and navigate to Manage Server > Cluster. The full cluster layout, including node tags and roles, will be displayed there:

3. Manage database, indexes, and configuration with repeatable playbooks

So far, we’ve seen the power of using Ansible to spin up RavenDB nodes and even connect them into a working cluster – all with clean, declarative playbooks. But real-world usage doesn’t stop at provisioning. Once your servers are up, the day-to-day work begins: creating databases, writing indexes, updating configurations, and so on.

The good news? The RavenDB Ansible Collection has modules exactly for that.

These modules are designed to interact with RavenDB’s API to perform operational tasks – the kind you’d typically do through the Studio or manual scripts, but now in a fully automated, version-controlled, and repeatable way. Whether you’re managing a single environment or dozens of deployments, these modules bring consistency to how you handle core operations

So, to keep things simple and easy to follow, we’ll focus on just one node. Don’t worry, this isn’t a limitation. You can definitely apply the same playbook across many nodes if needed. But for demonstration purposes, one is enough.

Let’s update our inventory to include just the node we’ll operate on:

# inventory
[ravendb_nodes]
192.168.100.11 ansible_user=ubuntu ansible_password=ubuntu
ansible_become_password=ubuntu node_tag=A

We’re assuming this node was already provisioned in Section 1 using the setup_ravendb.yml playbook and is currently up and running.

Creating and Managing Databases

Now let’s perform one of the most common tasks – creating a new database. Here’s the playbook:

  ---
  - name: Create Database
    hosts: ravendb_nodes
    gather_facts: no

    roles:
      - ravendb.ravendb.ravendb_python_client_prerequisites

    tasks:
      - name: Ensure RavenDB database is present
        ravendb.ravendb.database:
          url: "http://{{ ansible_host }}:8080"
          database_name: "my_database"
          replication_factor: 1
          state: present

Let’s take a quick look at the variables used in the database creation task:

• url: This is the base URL of the RavenDB node you’re targeting. In our case, we’re dynamically using {{ ansible_host }} to pull the IP from the inventory, followed by port 8080, which is the default HTTP endpoint.
• database_name: The name of the database you want to create. Here, we’re naming it my_database.
• replication_factor: This defines how many nodes will hold replicas of the database. Since we’re working with a single node for demonstration, we set it to 1.
• state: Just like in other Ansible modules, this controls the desired state. Use present to create or ensure the database exists, and absent to delete it.

📦 Why the ravendb_python_client_prerequisites Role?

This role sets up the required Python environment for using RavenDB modules. It creates a dedicated virtual environment, installs the RavenDB Python client and its dependencies, and configures Ansible to use the virtualenv’s Python interpreter. This approach keeps dependencies isolated and ensures consistent behavior across different systems, especially useful in clean environments or CI pipelines. You just need to include the role once per playbook before using any RavenDB modules.


Now, let’s run our playbook:

ansible-playbook -i ./inventory create_db.yaml

That’s it, the database is now created on the node.

Want to check it?

curl http://192.168.100.11:8080/databases

Want to Preview First? Use Check Mode

Sometimes you want to verify what would happen, without actually making changes. That’s where Ansible’s check_mode comes in handy:

    tasks:
      - name: Ensure RavenDB database is present (check mode)
        ravendb.ravendb.database:
          url: "http://{{ ansible_host }}:8080"
          database_name: "my_database"
          replication_factor: 1
          state: present
        check_mode: yes

Running the playbook like this lets you test your logic without creating anything on the server.

 

Deleting a Database

Need to remove a database instead? Just switch the state:

  - name: Ensure RavenDB database is absent
    ravendb.ravendb.database:
      url: "http://{{ ansible_host }}:8080"
      database_name: "my_database"
      state: absent

Cleanly, consistently, and repeatably. And we’re just getting started.

Creating and Managing Indexes

Once your database is up, one of the first things you’ll likely want to do is define indexes – whether to speed up queries, support projections, or enable map-reduce logic across your data. And just like with databases, you can manage indexes in RavenDB entirely through Ansible.

Let’s walk through the most common use cases.

Creating an Index

Here’s a basic playbook task to create a map-reduce index:

  - name: Ensure RavenDB Index is present
    ravendb.ravendb.index:
      url: "http://{{ ansible_host }}:8080"
      database_name: "my_database"
      index_name: "UsersByName"
      index_definition: 
        map: 
          - "from c in docs.Users select new { c.name, count = 5 }"
        reduce: >
          from result in results
          group result by result.name 
          into g 
          select new 
          { 
            name = g.Key, 
            count = g.Sum(x => x.count) 
          }
      state: present

This creates (or ensures the presence of) an index named UsersByName on the my_database database. It uses a simple map-reduce definition over the Users collection.

💡 If you rerun the playbook with the same index name but a different definition, RavenDB will automatically update the existing index.

Multi-Map Indexes

RavenDB supports multi-map indexes, indexes that consolidate data from multiple collections. Here’s an example that combines data from Users and Orders:

  - name: Ensure RavenDB Index is present
    ravendb.ravendb.index:
      url: "http://{{ ansible_host }}:8080"
      database_name: "my_database"
      index_name: "UsersAndOrdersByName"
      index_definition:
        map:
          - "from c in docs.Users select new { Name = c.name, UserCount = 1, OrderCount = 0, TotalCount = 1 }"
          - "from o in docs.Orders select new { Name = o.customer, UserCount = 0, OrderCount = 1, TotalCount = 1 }"
        reduce: >
          from result in results
          group result by result.Name
          into g
          select new 
          { 
            Name = g.Key, 
            UserCount = g.Sum(x => x.UserCount),
            OrderCount = g.Sum(x => x.OrderCount),
            TotalCount = g.Sum(x => x.TotalCount)
          }
      state: present

Deleting an Index

Deleting an index is as straightforward as setting its state to absent:

  - name: Ensure RavenDB index is absent
    ravendb.ravendb.index:
      url: "http://{{ ansible_host }}:8080"
      index_name: "UsersByName"
      database_name: "my_database"
      state: absent

This ensures the index is removed from the specified database if it exists.

Controlling Index Modes (Enable, Disable, and More)

You can also control the mode of an index: whether it’s actively indexing, paused, disabled, or otherwise. Here are examples for enabling and disabling an index:

  - name: Ensure RavenDB Index is enabled
    ravendb.ravendb.index:
      url: "http://{{ ansible_host }}:8080"
      database_name: "my_database"
      index_name: "Orders/ByCompany"
      mode: enabled

  - name: Ensure RavenDB Index is disabled
    ravendb.ravendb.index:
      url: "http://{{ ansible_host }}:8080"
      database_name: "my_database"
      index_name: "Orders/ByCompany"
      mode: disabled

These allow you to toggle indexing behavior without deleting the index.

In addition to enabled and disabled, RavenDB supports several other modes like pause, resume, and reset. These are useful when tuning performance, managing load, or responding to operational issues, and they’re fully supported by the module via the mode parameter.

Conclusion

The RavenDB Ansible Collection brings powerful, repeatable automation to every stage of your database lifecycle – from provisioning nodes and forming clusters to managing databases, indexes, and configuration. Whether you’re deploying a fresh environment or maintaining existing infrastructure, this collection helps you enforce consistency, reduce manual effort, and scale operations with confidence.

To explore further, visit our official Ansible Galaxy page to install the collection.

Comprehensive documentation is available to guide you through usage and setup, including details on all available modules and their arguments.

And if you’re looking for ready-to-run examples, check out the growing library of example playbooks on GitHub.

Happy automating! 🛠️⚡