Skip to content

Latest commit

 

History

History
212 lines (159 loc) · 7.09 KB

GUIDE_ANSIBLE.md

File metadata and controls

212 lines (159 loc) · 7.09 KB
Raw

Ansible Guide

This repo contains collections of Ansible scripts inside the ansible/ directory, so called "Roles", which are responsible for the provisioning of all configured nodes. It automatically sets up the Application Layer and manages updates for Polkadot software releases.

There is a main Ansible Playbook that orchestrates all the roles, it gets executed locally on your machine, then connects to the configured nodes and sets up the required tooling. Firewalls, Polkadot nodes and all its dependencies are installed by issuing a single command. No manual intervention into the remote nodes is required.

Prerequisites

  • Ansible (v2.8+)

    On Debian-based systems this can be installed with sudo apt install ansible from the standard repositories.

  • Running Debian-based nodes

    The nodes require configured SSH access, but don't need any other preparatory work. It's up to you on how many nodes you want to use. This setup assumes the remote users have sudo privileges with the same sudo password. Alternatively, additional configuration is required.

It's recommended to setup SSH pubkey authentication for the nodes and to add the access keys to the SSH agent.

Inventory

All required data is saved in a Ansible inventory, which by default is placed under /etc/ansible/hosts and must only be configured once. Most values from the SAMPLE FILE can be copied. Only a handful of entries must be adjusted.

For each node, the following information must be configured in the Ansible inventory:

  • IP address or URL.
  • SSH user (as ansible_user). It's encouraged NOT to use root.
  • (optional) The telemetry URL (e.g. wss://telemetry.polkadot.io/submit/, where the info can then be seen under https://telemetry.polkadot.io).
  • (optional) The logging filter.

The other default values from the sample inventory can be left as is.

NOTE: This guide assumes that the inventory is placed locally in ansible/inventory.yml.

NOTE: Telemetry information exposes IP address, among other information. For this reason it's highly encouraged to use a private telemetry server and not to expose the validator to a public server.

Setup Validator

Setup the validator node by specifying a [validator-<NUM>] host, including its required variables. <NUM> should start at 0 and increment for each other validator (assuming you have more than one validator).

Example:

[validator-0]
147.75.76.65

[validator-0:vars]
ansible_user=alice
telemetryUrl=wss://telemetry.polkadot.io/submit/
loggingFilter='sync=trace,afg=trace,babe=debug'

[validator-1]
162.12.35.55

[validator-1:vars]
ansible_user=bob
telemetryUrl=wss://telemetry.polkadot.io/submit/
loggingFilter='sync=trace,afg=trace,babe=debug'

Grouping Validators

All nodes to be setup must be grouped under [validator:children].

Example:

[validator:children]
validator-0
validator-1

Specify common variables

Finally, define the common variables for all the nodes.

Important variables which should vary from the sample inventory:

  • project - The name for how each node should be prefixed for the telemetry name.
  • polkadot_binary_url - This is the URL from were Ansible will download the Polkadot binary. Binary releases are available in the official Parity Releases repo or the W3F Releases repo.
  • polkadot_binary_checksum - The SHA256 checksum of the Polkadot binary which Ansible verifies during execution. Must be prefixed with sha256:.
  • chain - The chain to work on, such as kusama or polkadot.
  • polkadot_network_id - The network identifier, such as ksmcc3 (for Kusama) or polkadot.
  • node_exporter_enabled - Enable or disable the setup of Node Exporter. It's up to you whether you want it or not.

The other default values from the sample inventory can be left as is.

Example:

[all:vars]
# The name for how each node should be prefixed for the telemetry name
project=alice-in-wonderland

# Can be left as is.
ansible_ssh_common_args='-o StrictHostKeyChecking=no -o ConnectTimeout=15'
build_dir=$HOME/.config/polkadot-secure-validator/build/w3f/ansible

# Specify which `polkadot` binary to install. Checksum is verified during execution.
polkadot_binary_url='https://github.com/paritytech/polkadot/releases/download/v0.8.2/polkadot'
polkadot_binary_checksum='sha256:349b786476de9188b79817cab48fc6fc030908ac0e8e2a46a1600625b1990758'

# Specify the chain/network.
polkadot_network_id=polkadot
chain=polkadot

# Node exporter settings. Disabled by default.
node_exporter_enabled='false'
node_exporter_user='node_exporter_user'
node_exporter_password='node_exporter_password'
node_exporter_binary_url='https://github.com/prometheus/node_exporter/releases/download/v0.18.1/node_exporter-0.18.1.linux-amd64.tar.gz'
node_exporter_binary_checksum='sha256:b2503fd932f85f4e5baf161268854bf5d22001869b84f00fd2d1f57b51b72424'

# Polkadot service restart settings. Enabled to restart every hour.
polkadot_restart_enabled='true'
polkadot_restart_minute='0'
polkadot_restart_hour='*'
polkadot_restart_day='*'
polkadot_restart_month='*'
polkadot_restart_weekday='*'

Execution

Download the required files.

user@pc:~$ git clone https://github.com/w3f/polkadot-secure-validator.git
user@pc:~$ cd polkadot-secure-validator/ansible

Once the inventory file is configured, simply run the setup script and specify the sudo password for the remote machines.

NOTE: This script assumes that the inventory file is configured in ansible/inventory.yml.

user@pc:~/polkadot-secure-validator/ansible$ chmod +x setup.sh
user@pc:~/polkadot-secure-validator/ansible$ ./setup.sh
Sudo password for remote servers:
>> Pulling upstream changes... [OK]
>> Testing Ansible availability... [OK]
>> Finding validator hosts... [OK]
  hosts (2):
    147.75.76.65
    162.12.35.55
>> Testing connectivity to hosts... [OK]
>> Executing Ansible Playbook...

...

Alternatively, execute the Playbook manually ("become" implies sudo privileges).

user@pc:~/polkadot-secure-validator/ansible$ ansible-playbook -i inventory.yml main.yml --become --ask-become

The setup.sh script handles some extra functionality, such as downloading the newest upstream changes and checking connectivity of remote hosts including privilege escalation. This script/Playbook can be executed over and over again.

Additional Playbooks are provided besides main.yml, but those are outside the scope of this guide.

Updating Polkadot

To update the Polkadot version, simply adjust those two lines in the Ansible inventory:

polkadot_binary_url='...'
polkadot_binary_checksum='sha256:...'

Then just execute setup.sh again.