terraform-polkadot-aws-node

This module sets up a single node for the Polkadot blockchain and it's associated parachains on AWS. It uses Ansible to configure the node depending on its node_purpose which can be one of,

• validator - Requires manual unsealing
• library - Archive node running on a configurable set of parachains
• source of truth - Same a library but with an agent to push copies of the chain to S3 for autoscaling fast scale and sync operations

The module is intended to be flexible in its configuration parameters allowing users specify networks and securtiy groups while also providing sane defaults for one click deployments. Users then have the option of attaching their own DNS record or with additional configuration, joining to a consul cluster and monitoring with prometheus.

Requirements

• Terraform v.14+ tested
• Ansible 2.9 - pip install ansible
• SSH Keys - ssh-keygen -b 4096 (Only public required)

Ansible Modules

Name	Version
polkadot_base
polkadot_library
polkadot_truth
polkadot_validator
cloud_helper

Usage

Steps for running terraform:

1. Install the above requirements

2. Get AWS API keys into environment variables

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY

3. Create SSH keys and make note of the path (public_key_path variable) or copy the key material.

ssh-keygen -b 4096 -f $HOME/.ssh/<your key name>
cat $HOME/.ssh/<your key name>.pub # this is the `public_key` variable
# $HOME/.ssh/<your key name> # This is the `private_key_path`

4. Use this module in your own terraform or modify one of the examples directory. Possible configurations are:

Defaults

Minimal defaults example for polkadot. To run other parachains reference the other example.

module "default" {
  source           = "github.com/geometry-labs/terraform-polkadot-aws-node"
  name             = "default-${random_pet.this.id}"
  public_key       = var.public_key
  private_key_path = var.private_key_path
  node_purpose     = "library"
}

Deploys in default vpc and creates security group. For public deployments

External Network with Parachains

To run additional parachains, complete the below map for network_settings to map ports to the associated chain. Ports will then be exposed over the load balancer.

locals {
  network_settings = {
    polkadot = {
      name                = "polkadot"
      shortname           = "polkadot"
      api_health          = "5000"
      polkadot_prometheus = "9610"
      json_rpc            = "9933"
      json_envoy          = "21000"
      ws_rpc              = "9944"
      ws_envoy            = "21001"
    }
    kusama = {
      name                = "kusama"
      shortname           = "ksmcc3"
      api_health          = "5001"
      polkadot_prometheus = "9611"
      json_rpc            = "9934"
      json_envoy          = "21002"
      ws_rpc              = "9945"
      ws_envoy            = "21003"
    }
  }
}

module "default" {
  source           = "github.com/geometry-labs/terraform-polkadot-aws-node.git?ref=v0.1.0"
  name             = "default-${random_pet.this.id}"
  public_key       = var.public_key
  private_key_path = var.private_key_path
  node_purpose     = "library"
  network_settings = local.network_settings
}

Known issues

No issue is creating limit on this module.

Requirements

Name	Version
terraform	>= 0.13

Providers

Name	Version
aws	n/a

Modules

Name	Source	Version
ansible	github.com/insight-infrastructure/terraform-aws-ansible-playbook.git?ref=v0.15.0
user_data	github.com/insight-infrastructure/terraform-polkadot-user-data.git?ref=master

Resources

Name
aws_ami
aws_eip
aws_eip_association
aws_iam_instance_profile
aws_iam_policy
aws_iam_policy_document
aws_iam_role
aws_iam_role_policy_attachment
aws_instance
aws_key_pair
aws_kms_alias
aws_kms_key
aws_region
aws_s3_bucket
aws_s3_bucket_acl
aws_s3_bucket_server_side_encryption_configuration
aws_security_group
aws_security_group_rule
aws_subnet
aws_subnet_ids
aws_vpc

Inputs

Name	Description	Type	Default	Required
additional_security_group_ports	Additional ports to add to security group.	list(string)	[ "22" ]	no
base_path	Alternate base path for Polkadot client	string	""	no
cluster_name	Name of the kubernetes cluster (if used)	string	""	no
consul_acl_datacenter	Authoritative Consul ACL datacenter	string	""	no
consul_acl_enable	Bool to enable Consul ACLs	bool	false	no
consul_acl_token	Consul ACL token	string	""	no
consul_auto_encrypt_enabled	Bool to enable Consul auto-encrypt	bool	false	no
consul_connect_enabled	Bool to enable Consul Connect	bool	false	no
consul_enabled	Bool to enable Consul	bool	false	no
consul_gossip_key	Consul gossip encryption key	string	""	no
consul_security_group	ID of security group to containing Consul	string	null	no
consul_tls_ca_filename	Filename for Consul TLS CA certificate	string	"ca.crt"	no
consul_tls_source_dir	Path to directory containing Consul TLS certs	string	null	no
consul_version	Consul version number to install	string	"1.9.4"	no
create	Boolean to make module or not	bool	true	no
create_ansible	Boolean to make module or not	bool	true	no
create_security_group	Bool to create SG	bool	true	no
default_telemetry_enabled	Bool to enable telemetry submission to telemetry.polkadot.io	bool	false	no
enable_kms	n/a	bool	false	no
hardening_enabled	Runs a series of linux hardening playbooks - ansible-collection-hardening	bool	false	no
health_check_enabled	Bool to enable client health check agent	bool	false	no
health_check_port	Port number for the health check	string	"5500"	no
iam_instance_profile	IAM instance profile name, overrides source of truth IAM.	string	""	no
instance_count	Iteration number for this instance	string	"0"	no
instance_type	Instance type	string	"t3a.small"	no
key_name	The name of the preexisting key to be used instead of the local public_key_path	string	""	no
logging_filter	String for polkadot logging filter	string	"sync=trace,afg=trace,babe=debug"	no
monitoring	Boolean for cloudwatch	bool	false	no
mount_volumes	Bool to enable non-root volume mounting	bool	false	no
name	The name of the deployment	string	"polkadot-api"	no
network_name	The network name, ie kusama / polkadot	string	"polkadot"	no
network_settings	Map of network settings to apply. Use either this or set individual variables.	map(object({ name = string shortname = string api_health = string polkadot_prometheus = string json_rpc = string json_envoy = string ws_rpc = string ws_envoy = string }))	null	no
network_stub	The stub name of the Polkadot chain (polkadot = polkadot, kusama = ksmcc3)	string	"ksmcc3"	no
node_exporter_enabled	Bool to enable node exporter	bool	false	no
node_exporter_hash	SHA256 hash of Node Exporter binary	string	"b2503fd932f85f4e5baf161268854bf5d22001869b84f00fd2d1f57b51b72424"	no
node_exporter_password	Password for node exporter	string	"node_exporter_password"	no
node_exporter_url	URL to Node Exporter binary	string	"https://github.com/prometheus/node_exporter/releases/download/v0.18.1/node_exporter-0.18.1.linux-amd64.tar.gz"	no
node_exporter_user	User for node exporter	string	"node_exporter_user"	no
node_purpose	What type of node are you deploying? (validator/library/truth)	string	"library"	no
polkadot_additional_common_flags	Optional common flags for Polkadot client	string	""	no
polkadot_additional_validator_flags	Optional validator flags for Polkadot client	string	""	no
polkadot_client_hash	SHA256 hash of Polkadot client binary	string	"cc3bb44e3edc482111fc04b1426b7e2428e8c4b65cf1423c9d892ba97b6f7915"	no
polkadot_client_url	URL to Polkadot client binary	string	"https://github.com/paritytech/polkadot/releases/download/v0.9.16/polkadot"	no
polkadot_prometheus_port	Port number for the Prometheus Metrics exporter built into the Polkadot client	string	"9610"	no
polkadot_restart_day	Client cron restart day	string	""	no
polkadot_restart_enabled	Bool to enable client restart cron job	bool	false	no
polkadot_restart_hour	Client cron restart hour	string	""	no
polkadot_restart_minute	Client cron restart minute	string	""	no
polkadot_restart_month	Client cron restart month	string	""	no
polkadot_restart_weekday	Client cron restart weekday	string	""	no
private_key_path	Path to private key	string	n/a	yes
project	Name of the project for node name	string	"project"	no
prometheus_enabled	Bool to use when Prometheus is enabled	bool	false	no
public_key	The public ssh key. key_name takes precidence	string	""	no
root_volume_size	Root volume size	string	0	no
rpc_api_port	Port number for the JSON RPC API	string	"9933"	no
rpc_envoy_port	Port number for the JSON RPC Envoy proxy	string	"21000"	no
security_group_cidr_blocks	If create_security_group enabled, incoming cidr blocks.	list(string)	[ "0.0.0.0/0" ]	no
security_group_ids	The ids of the security group to run in	list(string)	[]	no
skip_health_check	Bool to skip client health check when agent installed	bool	true	no
source_of_truth_enabled	Bool to enable SoT sync (for use with library nodes)	bool	false	no
ssh_user	Username for SSH	string	"ubuntu"	no
storage_driver_type	Type of EBS storage the instance is using (nitro/standard)	string	"standard"	no
subnet_id	The id of the subnet.	string	""	no
sync_bucket_name	S3 bucket name for SoT sync	string	null	no
tags	Tags to associate with resources.	map(string)	{}	no
telemetry_url	WSS URL for telemetry	string	""	no
vpc_id	The VPC ID to run inside.	string	""	no
wss_api_port	Port number for the Websockets API	string	"9944"	no
wss_envoy_port	Port number for the Websockets Envoy proxy	string	"21001"	no

Outputs

Name	Description
instance_id	n/a
kms_key_arn	n/a
private_ip	n/a
public_ip	n/a
security_group_id	n/a
subnet_id	n/a
sync_bucket_arn	n/a
sync_bucket_domain_name	n/a
sync_bucket_name	n/a
this_security_group_id	n/a
this_security_group_ids	n/a
user_data	n/a
vpc_id	n/a

Authors

Module managed by robc-io

Credits

• Anton Babenko

License

Apache 2 Licensed. See LICENSE for full details.