ravendb.ravendb.healthcheck module – Perform RavenDB node and cluster health checks

Note

This module is part of the ravendb.ravendb collection (version 1.0.4).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install ravendb.ravendb.

To use it in a playbook, specify: ravendb.ravendb.healthcheck.

New in ravendb.ravendb 1.0.0

Synopsis

  • Runs one or more health checks against a RavenDB node.

  • node_alive verifies /setup/alive returns success.

  • cluster_connectivity verifies the node can ping cluster peers.

  • db_groups_available verifies each database group has at least one usable member in the cluster (no exclusion).

  • db_groups_available_excluding_target verifies each database group has at least one usable member while excluding the node identified by url.

  • Supports secured connections using client certificates and optional CA verification.

Parameters

Parameter

Comments

ca_cert_path

string

Path to a CA bundle used to validate the server certificate.

certificate_path

string

Path to a client certificate for secured clusters.

checks

list / elements=string

List of health checks to run.

Choices:

  • "node_alive" ← (default)

  • "cluster_connectivity" ← (default)

  • "db_groups_available"

  • "db_groups_available_excluding_target"

Default: ["node_alive", "cluster_connectivity"]

db_retry_interval_seconds

integer

Interval in seconds between attempts for db_groups_available and db_groups_available_excluding_target.

Default: 10

max_time_to_wait

integer

Max time window in seconds for each selected check before timing out.

Default: 1200

on_db_timeout

string

Behavior when db_groups_available times out.

fail fails the task; continue returns success with timeout noted in results.

Choices:

  • "fail" ← (default)

  • "continue"

retry_interval_seconds

integer

Interval in seconds between attempts for node_alive and cluster_connectivity.

Default: 5

url

string / required

Base URL of the RavenDB node to check, e.g. http://node-a:8080 or https://node-a:443.

validate_certificate

boolean

Verify the server TLS certificate when using HTTPS.

Automatically disabled for IP hosts when running node_alive or cluster_connectivity.

Choices:

  • false

  • true ← (default)

See Also

See also

RavenDB documentation

Official RavenDB documentation

Examples

- name: Default checks (node_alive + cluster_connectivity)
  ravendb.ravendb.healthcheck:
    url: "http://{{ inventory_hostname }}:8080"

- name: HTTPS with client cert + CA bundle
  ravendb.ravendb.healthcheck:
    url: "https://node-a.example.com:443"
    certificate_path: "/etc/ravendb/admin.client.pem"
    ca_cert_path: "/etc/ssl/private/ca.pem"
    validate_certificate: true
    checks: ["node_alive", "cluster_connectivity"]

- name: Add database-group availability (exclude current), continue on timeout
  ravendb.ravendb.healthcheck:
    url: "https://node-b.example.com:443"
    certificate_path: "/etc/ravendb/admin.client.pem"
    ca_cert_path: "/etc/ssl/private/ca.pem"
    checks: ["node_alive", "cluster_connectivity", "db_groups_available_excluding_target"]
    max_time_to_wait: 900
    db_retry_interval_seconds: 15
    on_db_timeout: continue

- name: Cluster-wide database-group availability (no exclusion)
  ravendb.ravendb.healthcheck:
    url: "https://node-c.example.com:443"
    certificate_path: "/etc/ravendb/admin.client.pem"
    ca_cert_path: "/etc/ssl/private/ca.pem"
    checks: ["db_groups_available"]
    max_time_to_wait: 1200
    db_retry_interval_seconds: 10
    on_db_timeout: fail

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

changed

boolean

Always false; health checks are read-only.

Returned: always

Sample: false

msg

string

Summary string of executed checks and outcomes.

Returned: always

Sample: "node_alive OK (attempts:1); cluster_connectivity OK (attempts:1)"

results

dictionary

Per-check structured results including attempts, error (if any), and detail.

Returned: success

Sample: {"cluster_connectivity": {"attempts": 1, "detail": {"peers": 3}, "error": null, "ok": true}, "db_groups_available_excluding_target": {"attempts": 60, "detail": {"failing": {"db1": "no usable member with LastStatus==Ok (or only excluded tag)"}}, "error": "timeout", "ok": false}, "node_alive": {"attempts": 1, "detail": {"status": 200}, "error": null, "ok": true}}

warnings

list / elements=string

Optional warnings (e.g., cert validation auto-disabled for IP hosts).

Returned: sometimes

Sample: ["validate_certificate automatically disabled for IP host (NodeAlive/ClusterConnectivity)."]

Authors

  • Omer Ratsaby (@thegoldenplatypus)