ansible-cassandra: A Shell repository from jschaul

ansible-cassandra

Ansible role to install an Apache Cassandra cluster supervised with systemd. Includes the following:

Some OS tuning options such as installing jemalloc, setting max_map_count and tcp_keepalive, disabling swap.
Bootstraps nodes using the IPs of the servers in the cassandra_seed (configurable) inventory group.
Weekly scheduled repairs via cron jobs that are non-overlapping (see cassandra_repair_slots).
- requires setting cassandra_keyspaces (default [] will have no effect)
Incremental and full backup scripts as well as a restore script. (NOTE: needs better testing)
- requires access to S3, optional, disabled by default
prometheus-style metrics using jmx-exporter

Status: beta, see TODOs

Ansible Requirements
Role Variables
Dependencies
Platforms
Example Playbook
License
A note on openjdk vs oracle:
Development setup
Credits
TODO

Ansible Requirements

ansible >= 2.4
no additional requirements

Role Variables

Give your cluster a better name:

# set cassandra_cluster_name before running the playbook for the first time; never change it afterwards
cassandra_cluster_name: default

You should override the keyspaces to match keyspaces on which you wish to run weekly repairs:

cassandra_keyspaces: []

You may wish to override the following defaults for backups:

# backups
cassandra_backup_enabled: false # recommended to enable this
cassandra_backup_s3_bucket: # set a name here and ensure access rights to an S3 bucket
cassandra_env: dev # used in naming backups in case you have more than one environment (e.g. production, staging, ...)

For a list of all variables, see defaults/main.yml.

Dependencies

The following should be installed before installing this role:

java (openJDK or Oracle, see A note on openjdk vs oracle:)
ntp

For the above dependencies, you can use the same roles as in molecule/default/requirements.yml - but you don't have to.

Platforms

Currently tested with ubuntu 16.04 only

Example Playbook

Assuming an inventory with 5 nodes where you wish to install cassandra on, two of them seed nodes:

# hosts.ini
[all]
host01 ansible_host=<some IP>
host02 ansible_host=<some IP>
host03 ansible_host=<some IP>
host04 ansible_host=<some IP>
host05 ansible_host=<some IP>

[cassandra]
host01
host02
host03
host04
host05

# cassandra_seed group will be used to configure seed bootstrapping
# recommended is 2 seed nodes per datacenter
[cassandra_seed]
host01
host02

Then the following should work and start your cluster:

# playbook.yml

- hosts: cassandra
  vars:
    # set cluster_name before running the playbook for the first time; never change it afterwards
    cassandra_cluster_name: my_cluster
    cassandra_keyspaces:
      - my_keyspace1
  roles:
    # ensure to install java ntp first, e.g. by running these roles (see Dependencies section):
    # - ansible-ntp
    # - ansible-java
    - ansible-cassandra

If you don't wish to configure cassandra seed nodes via a cassandra_seed_groupname (default: cassandra_seed) inventory group, you can configure them statically:

  vars:
    cassandra_seed_resolution: static
    cassandra_seeds:
      - 1.2.3.4
      - ...

License

AGPL. See LICENSE

A note on openjdk vs oracle:

As of November 2018, the cassandra homepage lists both openJDK and Oracle Java as supported (and offers their download links).

But when using openJDK, cassandra itself logs:

WARN: OpenJDK is not recommended. Please upgrade to the newest Oracle Java release

In the official upgrade-to-DSE docs one can find:

Important: Although Oracle JRE/JDK 8 is supported, DataStax does more extensive testing on OpenJDK 8 starting with DSE 6.0.3. This change is due to the end of public updates for Oracle JRE/JDK 8.)

It seems OpenJDK is the more future-proof thing to use.

Development setup

Install molecule. E.g. ensure you have docker installed, then, using a virtualenv, pip install molecule ansible docker.

molecule converge to run the playbook against docker containers
molecule lint and molecule syntax to improve yaml.
molecule test to destroy + converge + converge again for idempotence + destroy
make to run molecule converge on each file save.
troubleshooting: this issue has been observed with molecule, ansible 2.7 and docker. Workaround was to downgrade to ansible 2.5.

Credits

This role has been inspired by

internal role used at Wire initially targeting older OSes and older cassandra versions.
this cassandra role and its dependent roles (insufficient for our needs)

TODO

write ansible check at the end of playbook checking cassandra port is open
WARN: JMX is not enabled to receive remote connections. Please see cassandra-env.sh for more info.
test backups and restore
document usage of prometheus .prom files and node-exporter
check out if instead of cron jobs a repair alternative could be https://github.com/thelastpickle/cassandra-reaper

jschaul/ansible-cassandra