• Prerequisites
• Deploying
  • Deploying a Rama Cluster and Modules
• Cluster Configuration and Debugging
  • AMI requirements
  • systemd and journalctl
  • file system layout
• rama.tfvars variables
  • username
  • vpc_security_group_ids
  • rama_source_path
  • license_source_path
  • zookeeper_url
  • conductor_ami_id
  • supervisor_ami_id
  • zookeeper_ami_id
  • conductor_instance_type
  • supervisor_instance_type
  • zookeeper_instance_type
  • supervisor_num_nodes
  • zookeeper_num_nodes
  • supervisor_volume_size_gb
  • use_private_ip
  • private_ssh_key

Prerequisites

Terraform must be installed.

If you haven't already, create a new EC2 key pair in your AWS Console. It should automatically download a new .pem file. Add the downloaded .pem file to your your private key identities with ssh-add path/to/file.pem.

Create a file ~/.rama/auth.tfvars with the following content:

key_name = <name of the key you have configured as a key pair for EC2>

~/.rama must be added to your PATH.

For AWS authentication, we recommend setting up aws-vault.

This deploy requires a full Rama release which currently requires being part of the private beta.

Deploying

Deploying a Rama Cluster and Modules

To deploy a rama cluster:

1. Make sure you have your zip file of Rama and license downloaded.
2. Create rama.tfvars at the root of your project to set Terraform variables. These govern e.g. the number of supervisors to deploy. See rama.tfvars.example. There are several variables that are required to set.
3. Run bin/rama-cluster.sh deploy <cluster-name> [opt-args]. opt-args are passed to terraform apply. For example, if you wanted to just deploy zookeeper servers, you would run bin/rama-cluster.sh deploy my-cluster -target=aws_instance.zookeeper.

To run modules, use rama-<cluster-name> deploy .... rama-<cluster-name> is a symlink to a rama script that is configured to point to the launched cluster.

To destroy a cluster run bin/rama-cluster.sh destroy <cluster-name>.

Cluster Configuration and Debugging

AMI requirements

Zookeeper and Rama require Java to be present on the system to run. Rama supports LTS versions of Java - 8, 11, 17 and 21. One of these needs to be installed on the AMI.

unzip and curl must also be present on the AMI.

systemd and journalctl

All deployed processes (zookeeper, conductor rama, supervisor rama) are managed using systemd. systemd is used to start the processes and restart them if they exit. Some useful snippets include (substitute conductor or supervisor for zookeeper):

sudo systemctl status zookeeper.service # check if service is running
sudo systemctl start zookeeper.service
sudo systemctl stop zookeeper.service

systemd uses journald for logging. Our processes configure their own logging, but logs related to starting and stopping will be captured by journald. To read logs:

journalctl -u zookeeper.service    # view all logs
journalctl -u zookeeper.service -f # follow logs

An application's systemd config file is located at

/etc/systemd/system/zookeeper.service

file system layout

Each cluster node has one main application process; zookeeper nodes run zookeeper, conductor nodes run a rama conductor, supervisor nodes run a rama supervisor.

The relevant directories to look at are the $HOME directory, as well as /data/rama.

rama.tfvars variables

region

• type: string
• required: true

The AWS region to deploy the cluster to.

username

• type: string
• required: true

The login username to use for the nodes. Needed to know how to SSH into them and know where the home directory is located.

vpc_security_group_ids

• type: list(string)
• required: true

The security groups that the nodes are members of.

rama_source_path

• type: string
• required: true

An absolute path pointing to the location on the local disk of your rama.zip.

license_source_path

• type: string
• required: true

An absolute path pointing to the location on the local disk of your Rama license file.

zookeeper_url

• type: string
• required: true

The URL to download a zookeeper tar ball from to install on the zookeeper node(s).

conductor_ami_id

• type: string
• required: true

The AMI ID that the conductor node should use.

supervisor_ami_id

• type: string
• required: true

The AMI ID that the supervisor node(s) should use.

zookeeper_ami_id

• type: string
• required: true

The AMI ID that the zookeeper node(s) should use.

conductor_instance_type

• type: string
• required: true

The AWS instance type that the conductor node should use.

Ex. m6g.medium

supervisor_instance_type

• type: string
• required: true

The AWS instance type that the supervisor node(s) should use.

zookeeper_instance_type

• type: string
• required: true

The AWS instance type that the zookeeper node(s) should use.

supervisor_num_nodes

• type: number
• required: true

The number of supervisor nodes you want to use.

zookeeper_num_nodes

• type: number
• required: false
• default: 1

The number of zookeeper nodes you want to use.

Note: Zookpeeer recommends setting this to an odd number

supervisor_volume_size_gb

• type: number
• required: false
• default: 100

The size of the supervisors' disks on the nodes.

use_private_ip

• type: bool
• required: false
• default: false

Whether to use the global public IDs, or private internal IPs.

Ex. if your security group is configured to only allow connection through a VPN, you should set this to true so that you're not coming from outside the network.

private_ssh_key

• type: string
• required: false
• default: null