Skip to main content

HyperSDK devnet on AWS

In this section, we will learn how to use the ash.avalanche Ansible collection to provision an Avalanche test network on AWS EC2 instances using Terraform, create an HyperSDK Subnet and interact with it.

We will be using the morpheusvm example but this tutorial can be adapted to any other HyperSDK-based VM.

Requirements​

  • Python >=3.9 with venv module installed
  • AWS account and access key (see AWS docs) with correct permissions to manage EC2 instances (e.g.: AmazonEC2FullAccess)
  • Terraform installed (see Install Terraform)
    info

    Terraform is an infrastructure as code tool that lets you build, change, and version infrastructure safely and efficiently

  • For filtering outputs:
note

We recommend installing the Ash CLI to easily get information about your nodes and Subnets. See Ash CLI - Installation.
The tutorials still provide the snippets to query the Avalanche APIs with cURL.

Setup the environment​

  1. Clone the Getting Started repository:

    git clone https://github.com/AshAvalanche/ansible-avalanche-getting-started
    cd ansible-avalanche-collection-getting-started

  2. Setup and activate Python venv:

    bin/setup.sh
    source .venv/bin/activate

  3. Install the ash.avalanche collection:

    ansible-galaxy collection install git+https://github.com/AshAvalanche/ansible-avalanche-collection.git

  4. Initialize the Terraform modules:

    terraform -chdir=terraform/hypersdk-devnet init

Create EC2 instances with Terraform​

  1. Setup AWS keys environment variables:

    export AWS_SECRET_ACCESS_KEY="XXXXXXXXXXXXXXXXXXXXXXXXXX"
    export AWS_ACCESS_KEY_ID="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

  2. Created the resources with Terraform:

    terraform -chdir=terraform/hypersdk-devnet apply
tip

This command will create the resources defined in main.tf including:

  • 5 a t2.medium EC2 instance with 8GiB of storage
  • An associated key pair
  • A security group configured to allow SSH (port 22) and default AVAX ports (9650 for HTTP and 9651 for staking) as well as all outbound traffic.

If you want more instances, storage or different instance types, you can modify the variables.tf file accordingly.

Bootstrap the devnet​

note

This section uses the hypersdk-devnet inventory which is pre-configured as a local Avalanche network (see avalanchego_network_id: local in avalanche_nodes.yml).

We will use the ash.avalanche.bootstrap_local_network playbook to bootstrap the devnet. This playbook starts a first validator (validator01) and then bootstraps additional nodes (validator02-05) from the first node, thus creating a local network.

  1. Bootstrap the Avalanche nodes:

    ansible-playbook ash.avalanche.bootstrap_local_network -i inventories/hypersdk-devnet

It's done! We now have a ready-to-use 5-nodes Avalanche devnet.

note

Ansible will connect to the EC2 instances defined in the inventories/hypersdk-devnet/hosts file that was generated by Terraform. If you want to use a custom inventory (i.e. you created VMs without Terraform or want to use a different cloud provider), you can create a new hosts file manually using this format:

Ansible hosts file

File content:

 validator01 ansible_host=3.95.172.85 ansible_user=ubuntu ansible_ssh_private_key_file=./files/ansible_key.pem
 validator02 ansible_host=52.73.132.144 ansible_user=ubuntu ansible_ssh_private_key_file=./files/ansible_key.pem
 validator03 ansible_host=3.80.125.149 ansible_user=ubuntu ansible_ssh_private_key_file=./files/ansible_key.pem
 validator04 ansible_host=34.235.117.99 ansible_user=ubuntu ansible_ssh_private_key_file=./files/ansible_key.pem
 validator05 ansible_host=54.196.41.121 ansible_user=ubuntu ansible_ssh_private_key_file=./files/ansible_key.pem

 [avalanche_nodes]
 validator0[1:5]

 [avalanche_nodes:children]
 bootstrap_nodes
 subnet_txs_host
 subnet_validators
 api_node

 [bootstrap_nodes]
 validator01

 [api_node]
 validator01

 [subnet_txs_host]
 validator01

 [subnet_validators]
 validator0[1:5]

  1. Check the status of the network using the Ash CLI:

    Command
    ash avalanche node is-bootstrapped -n 54.227.38.150 C
    Output
    Chain 'C' on node '54.227.38.150:9650': Bootstrapped ✓
tip

Replace the IP address in the command above with one of your nodes. See the inventories/hypersdk-devnet/hosts to get the IPs of the EC2 instances created by Terraform.

Create the Subnet​

Run the ash.avalanche.create_subnet playbook to create the Subnet, blockchains and add validators:

ansible-playbook ash.avalanche.create_subnet -i inventories/hypersdk-devnet

At the end of the Subnet creation, information about the new Subnet is displayed:

ok: [validator01] =>
  msg: |-
    The Subnet has been created with its blockchains, and the validators added.
    Make sure to add the Subnet ID to the `avalanchego_track_subnets` list of each validator.
    Subnet ID = 29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL
info

This playbook calls

  1. The ash.avalanche.subnet role to create the Subnet, the blockchains and add the validators from the subnet_validators_list variable
  2. The ash.avalanche.node.add-validator playbook to add the validators from the subnet_validators group

Track the Subnet with the validators​

The ash.avalanche.subnet role does not handle Subnet tracking on validator nodes. The list of tracked Subnets is handled by the avalanchego_track_subnets variable in the ash.avalanche.node role.

To track the Subnet on our nodes:

  1. Add the Subnet ID to the avalanchego_track_subnets variable. For this tutorial, this variable is in avalanche_nodes.yml:

    inventories/hypersdk-devnet/group_vars/avalanche_nodes.yml
    avalanchego_track_subnets:
      - 29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL

  2. Run the ash.avalanche.provision_nodes to apply the new configuration and restart the :

    ansible-playbook ash.avalanche.provision_nodes -i inventories/hypersdk-devnet
caution

Make sure than the avalanchego_subnets_configs and avalanchego_chains_configs variables are configured with the proper Subnet and chain IDs (see bellow to get the chain ID) in the avalanche_nodes.yml file.

Check the Subnet validators​

After 2 minutes, we can check the validators list of the Subnet:

note

If not already done, configure the Ash CLI for local Avalanche network by following Configure the Ash CLI for your network.

Command
ash avalanche subnet info 29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL
Output
Subnet '29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL':
  Type: Permissioned
  Control keys: ["P-local18jma8ppw3nhx5r4ap8clazz0dps7rv5u00z96u"]
  Threshold:    1
  Blockchains list (1):
  - AshLocalEVM:
    ID:      26iZJxV79s2vvTJQM2NebfW7tDqyzCr2SfzgyVXtoURQh5VFoM
    VM ID:   srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy
    VM type: SubnetEVM
  Validators list (5):
  - NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg
  - NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ
  - NodeID-NFBbbJ4qCmNaCzeW7sxErhvWqvEQMnYcN
  - NodeID-GWPcbFJZFfZreETSoWjPimr846mXEKCtu
  - NodeID-P7oB2McjBGgW2NXXWVYjV8JEDFoW9xDE5
tip

You will need to SSH to the node to run the command above using the Ash CLI. See the inventories/hypersdk-devnet/hosts file generated by Terraform to get the IP address. You can get then connect to the node with ssh -i files/ansible_key.pem ubuntu@<node-ip>.

Configure morpheus-cli​

tip

Check out the official hypersk/morpheusvm repository for more details on the morpheus-cli installation process and usage.

  1. Import the default key:

    Command
    ./build/morpheus-cli key import ed25519 demo.pk
    Output
    database: .morpheus-cli
    imported address: morpheus1qrzvk4zlwj9zsacqgtufx7zvapd3quufqpxk5rsdd4633m4wz2fdjk97rwu%

  2. Import the chain:

    Command
    ./build/morpheus-cli chain import
    Output
    ✔ chainID: 26iZJxV79s2vvTJQM2NebfW7tDqyzCr2SfzgyVXtoURQh5VFoM
    uri: http://54.226.148.124:9650/ext/bc/26iZJxV79s2vvTJQM2NebfW7tDqyzCr2SfzgyVXtoURQh5VFoM

  3. Check balance of the key:

    Command
    ./build/morpheus-cli key balance
    Output
    database: .morpheus-cli
    address: morpheus1qrzvk4zlwj9zsacqgtufx7zvapd3quufqpxk5rsdd4633m4wz2fdjk97rwu
    chainID: 26iZJxV79s2vvTJQM2NebfW7tDqyzCr2SfzgyVXtoURQh5VFoM
    uri: http://54.226.148.124:9650/ext/bc/26iZJxV79s2vvTJQM2NebfW7tDqyzCr2SfzgyVXtoURQh5VFoM
    balance: 10000000000.000000000 RED

Customization​

Use a custom HyperSDK VM​

This tutorial uses the morpheusvm example for simplicity but it can be adapted to any other HyperSDK-based VM. To use a different HyperSDK VM, you can modify the inventories/hypersdk-devnet/group_vars/avalanche_nodes.yml file. You will need to update the avalanchego_vms_list and avalanchego_vms_install variables. See the Blockchain VM Management tutorial for more information.

Configure the chain genesis​

The ash.avalanche.create_subnet playbook uses the subnet_blockchains_list variable to configure the chain genesis. You can customize the chain genesis by modifying this variable in the inventories/hypersdk-devnet/group_vars/subnet_txs_host.yml file.

Configure the Subnet and chain​

You can customize the Subnet and chain configuration by modifying the avalanchego_subnets_configs and avalanchego_chains_configs variables in the inventories/hypersdk-devnet/group_vars/avalanche_nodes.yml file. See the ash.avalanche.node reference for more information.