Automated Install

Overview

When running the installation, you will run the installation script on a Controller Machine. This is simply the machine you choose to run the installation process on (your laptop, the primary server, etc.). This script will SSH from the Controller Machine into the Target Servers to install them as HYPR nodes.

Prerequisites

• Python 3 must be installed on the machine you are running the install from

• You must have elevated user access for the duration of the install, preferably root access
  If you can't use root, you may use an alternate account which has privileges to:

  -- Create directories
  -- Create users & groups
  -- Install yum pkgs
  -- Modify ulimits
  -- Install systemd services

• List of servers to install HYPR on

• SSH access to the target servers, preferably via SSH key

Install steps

Get the following packages from HYPR:

Untar the installer

tar -xvf ServerInstaller-ansible-<version>.tar.gz

This will create the ansiblePlaybook directory containing automation.

Copy the ServerInstaller-.tar.gz pkg to the ansiblePlaybook directory.

[root@localhost ansiblePlaybook]# ls -la
total 271016
drwxrwxr-x. 5  997  994       193 Jan 26 00:06 .
drwxr-xr-x. 3  997  994       146 Jan 26 00:06 ..
-rwxrwxr-x. 1  997  994      1546 Jan 25 20:02 commons.sh
-rw-rw-r--. 1  997  994     13740 Jan 25 20:02 hyprservers.yml
-rwxrwxr-x. 1  997  994      5149 Jan 25 20:02 install.sh
drwxrwxr-x. 2  997  994        75 Jan 25 20:02 inventory
drwxrwxr-x. 7  997  994       112 Jan 25 20:02 libs
drwxrwxr-x. 2  997  994        67 Jan 25 20:02 nginx
-rw-r--r--. 1  997  994 277482693 Jan 26 00:06 ServerInstaller-6.9.0-20210125.200346-34.tar.gz <---
-rwxrwxr-x. 1  997  994      1231 Jan 25 20:02 start.sh
-rwxrwxr-x. 1  997  994      1248 Jan 25 20:02 stop.sh

Upgrading?

If you are upgrading, you should have an existing .install.enc file on the master HYPR server.
This file has the metadata about the install and is supposed to remain constant through upgrades.

Copy this file from the master node to the local Ansible . Place it as a sibling of the <ServerInstaller-xxx.tar.gz> file.

Ansible will copy this file back out to the upgraded servers, keeping it consistent with the previous install.

Specify the Servers

The configuration mainly consists of:

• Specifying the servers
• Setting env variables (same env variables as the ones in env.sh of the core install package)

The combination of servers and env variables is referred to as inventory. You can maintain multiple inventory files, corresponding to the different environments you have.

Copy and modify one of the sample inventory files.

Accessing Ansible defined data in the inventory file

Ansible, exposes serveral pieces of data about the servers its installing on. This data can also be accessed in the inventory file.

Upon install, the env variables in the inventory files are copied to <install dir>\envOverrides.sh - on each node. These env vars are then available to the HYPR process.

Example:

all:
  children:
    hyprservices:
      hosts:
        master:
				...
      
      vars:
        env_overrides:
          # Read inventory_hostname from Ansible
          # HOST_NAME will be defined in the envOverrides.sh file on the target server
          # This can then be access as a regular bash var
          HOST_NAME: "{{ inventory_hostname }}"
          HOST_FQDN: "{{ ansible_fqdn }}"
          TOTAL_MEMORY: "{{ ansible_memtotal_mb }}"
          CC_ADDITIONAL_STARTUP_PARAMS: "-DMyParam=$HOST_NAME"

Full Ansible vars list here: https://docs.ansible.com/ansible/latest/user_guide/playbooks_vars_facts.html

Cusomizing Nginx config file

The default HYPR template is included in <playbook dir>/nginx/nginx.1161.conf.sh
You may modify this template directly. The modified template will be distributed to the target servers

Note: Once Nginx is installed and you wish to change the template, you will need to manually delete the <install dir>/nginx/nginx-1.16.1 dir on the target server. The nginx config will then be repopulated with the latest template

Run the install

Start with ./install.sh -help

For example, to run a single node install (-s) with all components (-a) specifying an encryption key (-e) and you inventory file (-i), run the following command

./install.sh -s -a -e -i inventory/nyc_prod_single_sample.yml

Once successfully run, the HYPR services and corresponding systemd are installed. Log files are stored in the ansiblePlaybook/logs directory.

Post install

Run ./start.sh

This will start the systemd services which were set up in the install step.

Common errors

ERROR! Invalid callback for stdout specified: yaml

Edit the .install.sh file. Comment out this line export ANSIBLE_STDOUT_CALLBACK=yaml

This setting gives us formatted error msgs but can be safely disabled