Skip to content

Latest commit

 

History

History

ansible

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
indy_node
indy_node
 
 
README.md
README.md
 
 

README.md

English version below

Ansible

Déploiement de nœuds indy grâce au Playbooks Ansible

Comment tester le playbook

ansible-playbook --private-key ~/.ssh/<key>.pem -i indy_node/tests/inventory.yml --extra-vars "host=lab_nodes" indy_node/deploy.yml

Le fichier d'inventaire attendu (généré à partir de la sortie Terraform) ressemble à ceci :

lab_nodes :
  hôtes :
    <host_address_from_terraform> :
      eth0_ip : <eth0_ip_address_from_terraform>
      eth1_ip : <eth1_ip_address_from_terraform>

Vous pouvez utiliser Ansible dans un docker

$ docker run -it -v //c/Users/Wade.BARNES-DESIGNS/.ssh/:/root/.ssh -v //c/Candy/ansible/:/root/ansible ansible

Fonctionnant sur AWS

  • Mettez à jour remote_user de devops vers ubuntu dans tous les fichiers qui le définissent.
  • Basculez cloud de azure à aws dans indy_node/roles/indy_node/defaults/main.yml.

Ansible Playbooks for Indy Node deployment

QuickStart

The following steps assume:

  • You have already followed these instructions and are hosting the code inside the development container.
  • You are somewhat familiar with Ansible.
  • You have already provisioned your Nodes using the Terraform scripts.

  1. Export the ansible inventory from your Terraform project.

    • From your Terraform project run (for example): 
      vscode ➜ /workspaces/Candy/terraform/aws $ terraform output -raw ansible_inventory > ../../ansible/aws-inventory.yml
    • This will output an inventory file that will look something like this. The number of hosts listed in the file will depend on the number of nodes you have provisioned. 
      nodes:
  hosts:
    20.104.111.61:
    20.104.254.144:

  2. Import (copy) the SSH private key to use during your Ansible sessions.

    • Copy the key into the ./ansible directory.
    • Always make sure your key has a passphrase.
    • Permanently delete the key from the directory when you are done.
    • When committing code, always ensure you do not accidentally commit your key to the repo. There are entries in the .gitignore file to help prevent these situations, however depending the naming conventions you use for your key they might not work for your particular file.

  3. Load your SSH private key into the terminal session.

    • From the ./ansible directory run the following commands: 
      ssh-agent bash
ssh-add ./<private-ssh-key-filename-here>
    • Enter your passphrase when prompted.

  4. Run the playbook. Ensure you include the correct ssh username for your environment(s) with the --user parameter; validatornode for azure environments and ubuntu for aws environments.

    • For example: 
      ansible-playbook --user ubuntu -i aws-inventory.yml --extra-vars "cloud=aws network_name=candy-test indy_node_channel=rc indy_node_pkg=indy-node indy_node_pkg_version=1.13.2~rc3 indy_plenum_pkg_version=1.13.1~rc2" indy_node/deploy.yml
    • To have better control over the groups of tasks that get run: 
      ansible-playbook --user ubuntu -i aws-inventory.yml --extra-vars "cloud=aws network_name=candy-test indy_node_channel=rc indy_node_pkg=indy-node indy_node_pkg_version=1.13.2~rc3 indy_plenum_pkg_version=1.13.1~rc2 network_configuration=true install_packages=true mount_data_volume=true indy_node_configuration=false" indy_node/deploy.yml
    • When establishing the initial ssh connection to the servers you can disable all task groups: 
      ansible-playbook --user ubuntu -i aws-inventory.yml --extra-vars "cloud=aws network_name=candy-test indy_node_channel=rc indy_node_pkg=indy-node indy_node_pkg_version=1.13.2~rc3 indy_plenum_pkg_version=1.13.1~rc2 network_configuration=false install_packages=false mount_data_volume=false indy_node_configuration=false" indy_node/deploy.yml

  5. Generate Genesis files using tools in von-network , for example:

    ./manage generategenesisfiles "./tmp/CANdy Dev Genesis File Node info - Trustees.csv" "./tmp/CANdy Dev Genesis File Node info - Stewards.csv"

  6. Once you've initialized your node(s) and have generated the domain_transactions_genesis and pool_transactions_genesis files, you can copy them along side the ansible inventory files and run the configuration again. The files will be copied to the servers and the indy-node servce will be enabled and started.

Playbook behaviour

The playbook will setup and configure indy-node on a newly provisioned Ubuntu 16.04 or 20.04 VM hosted in either AWS or Azure.

You MUST specify the correct ssh username for your environment via --user when running the playbook.

The cloud provider is defined by setting the cloud variable in --extra-vars when running the playbook. From there the playbook will auto-detect the OS version and configure the networking accordingly.

Following network configuration the packages are installed and configured. The playbook is capable of configuring the node(s) as a genesis node, or as a new node connecting to an existing network. Node initialization occurs only once, subsequent runs of the script will detect the existing configuration and skip over any steps that have already been completed to ensure the node's configuration is not inadvertently modified.

Node Initialization:

Node initialization depends on a few things:

  • Network name - You MUST supply a network name via the network_name variable. The name should be consistent across all nodes within the same network. The network name defines the name of the directory on the node where all of the files, keys, and data will be stored.
  • Node Alias - The node alias is a human readable name for the node. The configuration tasks read the hostname from the node and use the value as the node alias.
  • Network configuration - Specifically the IP addresses of the client and node NICs. The IP addresses are gathered automatically by the network configuration tasks.

Genesis Node:

  • A node that will be used during the formation of a new network.
  • If you do not supply values for the *_transactions_genesis_url variables, the script will configure the node as a genesis node.
  • The node will be left in a state where it is ready to have an initial set of genesis files added before the indy-node service is started for the first time; it will be initialized, no genesis files will exist, and the indy-node service will be stopped and disabled.

New Node - connecting to an existing network:

  • A node that will be added to an existing network.
  • If you supply values for the *_transactions_genesis_url variables, the script will configure the node to connect to the existing network defined by the genesis files.
  • The node will be left in a running state; the genesis files will be downloaded, and the indy-node service will be enabled and started.

There are several playbook variables that can be used to control the behaviour of the scripts. Refer to the Playbook options section below for details.

Archive / Restore

The archive and restore playbooks allow you to archive and restore the network data volumes on one or more of your nodes. The playbooks automatically stop and start the indy-node service if it is running and leave it in the state it was found once complete.

You should explicitly define network_name when running the scripts to ensure it is clear which network is being archived or restored.

⚠️ Ensure you generate a recent archive before performing a restore operation as the files on the node will be completely replaced with the content from the specified archive set during a restore operation.

Archive files are named using the following format: <node-name>_<network-name>.gz

Archive

Generates an archive containing the content of a given network contained on a node's data volume, which typically includes the genesis files, keys, and ledger data for the given network.

The archive is generated remotely on the node and then downloaded locally before finally being removed from the node.

Example use:

ansible-playbook --user ubuntu -i beta-aws-inventory.yml --extra-vars "network_name=candy-beta" indy_node/archive.yml

Restore

Restores the content of an archive containing the content of a given network to a node's data volume.

Place the archive files to be restored in the root folder (e.g. ./ansible) where the scripts will be run.

The archive is uploaded to the node before being extracted and finally removed from the node.

The existing network data on the node is completely replaced by the content of the archive. In order words, the existing network data on the node is deleted before the uploaded archive is extracted.

⚠️ Ensure you have a recent archive before performing a restore operation as the files on the node will be completely replaced with the content from the specified archive set during a restore operation.

Example use:

ansible-playbook --user ubuntu -i beta-aws-inventory.yml --extra-vars "network_name=candy-beta" indy_node/restore.yml

Playbook options

The following variables can be used to control various settings and behaviours of the playbook. The variables listed as required have defaults, however it is best to review these key variables and set them explicitly based on your environment.

cloud - required (default=azure)

  • Defines the cloud provider hosting the node(s).
  • Supported values are asure and aws.

network_name - required (default=candy-dev)

  • Defines the name of the network to configure for the node(s).

indy_node_channel - required (default=rc)

  • Defines the name of the package channel to use when installing packages.
  • Supported values depend on the indy node package repositories.

indy_node_pkg - required (default=indy-node)

  • Defines the name of the indy-node package to install.
  • Options include indy-node (for generic indy-node installations), sovrin (for sovrin installations).

indy_node_pkg_version - required (default=1.13.2~rc3)

  • Defines the version of indy-node to be installed.
  • Note:
    • indy-node and sovrin versions <=1.12.x only support Ubuntu 16.04.
    • indy-node and sovrin versions >=1.13.x only support Ubuntu 20.04.

indy_plenum_pkg_version - optional (default=indy_node_pkg_version)

  • Defines the version of indy-plenum to be installed.
  • You only need to define this when the version of indy-plenum to be installed is different than the version of indy-node.

domain_transactions_genesis_url - optional (default=null)

  • Defines the URL endpoint for downloading the domain_transactions_genesis needed to connect the node(s) to an existing network.

pool_transactions_genesis_url - optional (default=null)

  • Defines the URL endpoint for downloading the pool_transactions_genesis_url needed to connect the node(s) to an existing network.

node_seed - optional (default=null)

  • The seed to be used for the node initialization. If not defined the node will be initialized with a random seed. This is useful if you are moving a node to another hosting environment and want to ensure the same keys are generated for the new instance.

node_port - optional (default=9701)

  • Defines the port on which the node(s) will communicate with other nodes.

client_port - optional (default=9702)

  • Defines the port on which the node(s) will communicate with clients.

network_configuration - optional (default=true)

  • Boolean value indicating whether or not the network configuration tasks should be run.

install_packages - optional (default=true)

  • Boolean value indicating whether or not the package installation tasks should be run.

mount_data_volume - optional (default=true)

  • Boolean value indicating whether or not to configure and mount the node's data volume.

indy_node_configuration - optional (default=true)

  • Boolean value indicating whether or not the node configuration tasks should be run.
  • The node configuration tasks depend on the network configuration tasks. If the node configuration tasks are selected the network configuration tasks will also be run.

start_indy_node - optional (default=true)

  • Boolean value indicating whether or not to enable and start the indy-node service.

ToDo:

  • Automate the collection of the information needed to fill out the Steward Genesis spreadsheet.