What’s new? Production-Ready Improvements to the RavenDB Ansible Collection

Some time ago, we released the RavenDB collection for Ansible. We created it to help you automate repetitive tasks, like setting up the same database over and over or populating many databases with the same indexes. It was a good starting point for basic collection, but that was that, a starting point.

Now, over the past few months, after the initial release, we have released several updates and improvements. In this article, we want to introduce those changes and walk you through new options. Let’s review a new dose of playbooks and identify new things we can automate.

Healthcheck

Sometimes you need to be sure the node you want to affect is up and healthy. To do that, we use the health check described here. This is a great tool for a pre-upgrade check. This can be done easily using the new healthcheck module. A task that we can use for that is, for example:

  - name: Per-node gates pre upgrade
    delegate_to: localhost
    ravendb.ravendb.healthcheck:
      url: "http://{{ ansible_hostname }}:8080"
      checks: ['node_alive', 'cluster_connectivity']
      max_time_to_wait: 60
      retry_interval_seconds: 3

It can be used before and after the upgrade in that way.

  - name: rolling Update to 6.2
    hosts: all
    gather_facts: true
    serial: 1
    tasks:
      - name: Per-node gates pre (node-cluster-and-db-online-ok)
        delegate_to: localhost
        ravendb.ravendb.healthcheck:
          url: "http://{{ ansible_hostname }}:8080"
          checks: ['node_alive', 'cluster_connectivity', 'db_groups_available_excluding_target']
          max_time_to_wait: 60
          retry_interval_seconds: 3

      - name: Upgrade node to 6.2
        include_role:
          name: ravendb.ravendb_node
        vars:
          ravendb_state: present
          ravendb_version_minor: 6.2
          ravendb_settings_preset: default

      - name: Per-node gates post upgrade
        delegate_to: localhost
        ravendb.ravendb.healthcheck:
          url: "http://{{ ansible_hostname }}:8080"
          checks: ['node_alive', 'cluster_connectivity', 'db_groups_available_excluding_target']
          max_time_to_wait: 60
          retry_interval_seconds: 3
          db_retry_interval_seconds: 5
        register: gate_result

This script basically:

• Processes one node at a time
  
• Before upgrading a node, it runs health checks that ensure:
  • The node is alive
    
  • It can communicate with the cluster
    
  • Database groups are healthy
    
• If the node passes all checks, upgrade that node to 6.2
  
• After upgrade health checks.
  

Connection string

If your systems rely on connections with different services like Snowflake or OpenAI’s GPT, you can speed things up by adding a connection string. You can read about connection strings here. For this purpose, we created a whole set of tasks in the connection string playbook. For example, you can add a connection string for GPT-o4 like this:

  - name: OpenAI AI CS (create)
    ravendb.ravendb.connection_string:
      url: "http://192.168.100.15:8080"
      database_name: "my_database"
      name: "ai_openai"
      cs_type: "AI"
      properties:
        identifier: "prod-openai"
        model_type: "CHAT"
        openai_settings:
          api_key: "sk-XXXX"
          endpoint: "https://api.openai.com/v1/"
          model: "gpt-4"
      state: present

You just need to fill in the required fields like “api_key”, url, or database name, and it is ready to be connected to an ongoing task. A handy connection string playbook that you can quickly copy and customize is available on GitHub here.

Updated

Database Encryption

RavenDB supports database encryption; you can read about it here. The problem was when we wanted to automate the creation of such a database. You don’t want to turn on encryption manually when you already have databases created automatically. To do that, we can look at this task:

  - name: Create encrypted DB with key generation
    ravendb.ravendb.database:
      url: "https://a.ravendbansible.development.run:443"
      certificate_path: "/home/user/setup_package/admin.client.combined.pem"
      database_name: "my_encrypted_db"
      replication_factor: 3
      encrypted: true
      generate_encryption_key: true
      encryption_key_output_path: "/home/user/my_encrypted_db.key"
      state: present

The new part is actually small, as it is only:

  encrypted: true
  generate_encryption_key: true
  encryption_key_output_path: "/home/user/my_encrypted_db.key"

It might seem insignificant at first glance, but this is a key to creating an encrypted database. As you can see, while using this, we need to select a path for the encryption key. The location of this key should be as safe as possible, as it’s unrecoverable. If you already have an encryption key, you can reduce it to:

  encrypted: true
  encryption_key: "/home/user/my_key.key"

This will require you to enter the already-generated encryption key.

Database settings

If you are creating databases with precise settings, you must have been annoyed by having to select the same options repeatedly. Thankfully, now we can automate this. A simple task we can use now is. For example:

  - name: Apply database settings on create/update
    ravendb.ravendb.database:
      url: "http://192.168.100.15:8080"
      database_name: "my_database"
      replication_factor: 1
      state: present
      database_settings:
        Indexing.MapBatchSize: "128"

The relevant part:

  database_settings:
    Indexing.MapBatchSize: "128"

Of course, you can put more options there. To learn more about the available settings, visit this page.

Deploy Database on specific nodes

Sometimes, when setting up a database, some nodes might need to be omitted. For those situations, this task exists.

  - name: Create DB on specific nodes (A, C)
    ravendb.ravendb.database:
      url: "http://192.168.100.15:8080"
      database_name: "db_a_c"
      replication_factor: 2
      topology_members:
        - "A"
        - "C"
      state: present

This code will create a database “db_a_c” on nodes A and C. Remember to customize it for your needs. You can also easily add check mode by just adding this line at the end. Check mode lets you run tasks without making any changes. You will receive a report showing what changes would have been made. For example, you can test the deployment of a new database without actually deploying it.

  - name: Create DB on specific nodes (A, C)
    ravendb.ravendb.database:
      url: "http://192.168.100.15:8080"
      database_name: "db_a_c"
      replication_factor: 2
      topology_members:
        - "A"
        - "C"
      state: present  
    check_mode: yes

Join Node to Secured Cluster

When the collection was released, joining nodes was possible only if your cluster was unsecured. Now it doesn’t matter, you can add nodes to secured clusters like it’s nothing. A task that achieves that looks like this:

  - name: Join Node B as Watcher (secured)
    ravendb.ravendb.node:
      tag: B
      type: "Watcher"
      url: "https://b.ravendbansible.development.run"
      leader_url: "https://a.ravendbansible.development.run"
      certificate_path: /home/user/admin.client.combined.pem

The important line here is “certificate_path: /home/user/admin.client.combined.pem” because it grants your task permission to use the certificate to interact with your cluster.

Index configuration

After automating index creation, you might need to change their settings. With this task, you can easily check indexes on multiple nodes, and if they don’t have the same settings as you provide in the script, they will be changed.

  - name: Reconcile per-index configuration (idempotent)
    ravendb.ravendb.index:
      url: "http://{{ ansible_host }}:8080"
      database_name: "my_database"
      index_name: "UsersByName"
      index_configuration:
        Indexing.MapBatchSize: "128"

All that is needed is “index_configuration:” followed by the corresponding setting you can find here.

Index Deployment Mode

If you are upgrading your system by adding multiple nodes and new indexes, you probably don’t want to overwhelm it by indexing everything at once. Thankfully, you don’t need to keep adding indexes manually. Using deployment modes for indexes, you can specify whether your nodes should process the index all at once (parallel) or one by one (rolling). When creating an index, you can use this task:

  - name: Ensure RavenDB Index is present (rolling deployment)
    ravendb.ravendb.index:
      url: "http://192.168.100.15: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 }"
        deployment_mode: rolling
      state: present

Or if your whole server or database is already in rolling mode, change “rolling” to “parallel” and make this specific index work on all nodes at the same time.

Summary

New options and playbooks in RavenDB’s Ansible Collection will help you automate monotonous tasks and focus on essential stuff. If you want to learn about RavenDB Ansible Galaxy Collection, check the previous article on this page.

Interested in RavenDB? Grab the developer license dedicated for testing under this link here, or get a free cloud database here. Any questions about this feature, or just want to hang out and talk with the RavenDB team? Join our Discord Community Server – invitation link is here.