Hyperledger Fabric-X Ansible Collection

Hyperledger Fabric-X is an open source project that builds on top of Hyperledger Fabric and tailored specifically for digital assets use-cases. Fabric-X builds on the core principles of Hyperledger Fabric (sovereign, horizontally scalable smart contract execution and a modular, agile architecture) making it well-suited to meet the governance and compliance needs of regulated digital assets.

This repository contains the hyperledger.fabricx Ansible collection, which can be used to deploy an Hyperledger Fabric-X network and distribute the components over multiple nodes.

Table of Contents

• Installation
  • Option 1: Install from Ansible Galaxy
  • Option 2: Install cloning the repository under ANSIBLE_COLLECTIONS_PATHS (for development)
  • Option 3: Install from source
• Usage
• Prerequisites
  • Setup the control node
  • Setup the remote nodes
• Run a sample Fabric-X network
  • 1. Generate the artifacts
  • 2. Start the network
  • 3. Teardown the network
  • Run with Podman/Docker on MacOS
• Supported commands
  • Restrict commands to a group of hosts
• Contributing
• License

Installation

Option 1: Install from Ansible Galaxy

To install the latest published version of the hyperledger.fabricx collection from Ansible Galaxy, run:

ansible-galaxy collection install hyperledger.fabricx

Then install the collection's dependencies:

ansible-galaxy collection install -r ~/.ansible/collections/ansible_collections/hyperledger/fabricx/requirements.yml

Option 2: Install cloning the repository under ANSIBLE_COLLECTIONS_PATHS (for development)

To install the hyperledger.fabricx collection on your control node, run:

git clone https://github.com/LF-Decentralized-Trust-labs/fabric-x-ansible-collection.git ~/.ansible/collections/ansible_collections/hyperledger/fabricx
cd ~/.ansible/collections/ansible_collections/hyperledger/fabricx
make install-deps

NOTE: This is the recommended way if you plan to develop and change the scripts, since it allows to test directly the modified scripts avoiding to reinstall the collection at every change.

WARNING: Do not run make install with this setup — the collection is already live from the cloned directory. Running it would overwrite your checkout with a built artifact. Use make install-deps to install dependencies only. The Makefile will also guard against this and abort if it detects the risk.

Option 3: Install from source

If you don't know where the COLLECTIONS_PATHS is located, or you don't plan to develop/change the Ansible scripts within the collection, you can install from source using the commands:

git clone https://github.com/LF-Decentralized-Trust-labs/fabric-x-ansible-collection.git
cd fabric-x-ansible-collection
make install

Usage

The collection provides a set of Ansible roles that can be used to deploy an Hyperledger Fabric-X network in a distributed manner. Each role is devoted to a specific component.

Each role comes with tasks and each task performs a specific operation, like starting or stopping a component. The collection comes with a set of predefined playbooks that show how to use such roles. If you adapt your inventory to work with these playbooks, you can even directly use them without having to write your own playbooks.

For example, the playbook playbooks/orderer/start.yaml shows how to use the hyperledger.fabricx.orderer role to start a Fabric-X Orderer node:

- name: Start Fabric-X Orderer components
  ansible.builtin.include_role:
    name: hyperledger.fabricx.orderer
    tasks_from: start

For more information, please look at the Roles documentation.

Prerequisites

Setup the control node

To run such Ansible collection, you need to have the following prerequisites installed on your control node:

• python;
• podman or docker;
• go.

After having cloned this repository, run:

make install-deps

Setup the remote nodes

The collection comes with a playbook that can be used to automatically setup all the remote nodes at once. From your control node, run:

make install-remote-node-deps

IMPORTANT: the playbook install all the needed packages requiring the sudo permission. Make sure to have a passwordless sudo user in order to let the playbook succeed.

Run a sample Fabric-X network

This repository comes with some Ansible inventories and playbooks examples that could be used to start a sample Fabric-X network on your local machine. Please look at the examples README to understand better which network you can run with each inventory and how to enhance them for your use case.

By default, the fabric-x.yaml inventory is used:

To run it on your local machine, follow the steps hereafter indicated.

1. Generate the artifacts

The first step consists in generating the artifacts needed by the nodes to run, which means:

• generate the crypto material through the cryptogen CLI;
• generate the genesis block through armageddon and configtxgen CLIs;
• build/install the Fabric-X component binaries on the control node or directly on remote nodes, depending on the bin_build_on_control_node variable (see more the Roles documentation);
• distribute the above-mentioned artifacts on the remote nodes.

To achieve this, run:

make setup

2. Start the network

Once the artifacts have been correctly generated and distributed, you can run them with:

make start

This command bootstraps all the components that have been indicated within the reference inventory. Once the command completes, a Fabric-X network should be running on your machine with a load of 1000 TPS (which can be incremented or decremented, see Supported Commands).

You can access Grafana dashboards (user=admin, password=adminPWD) to see how the Fabric-X network is handling the transactions processing.

3. Teardown the network

To shut the network down, run:

make teardown

The command proceeds by stopping all the running instances and also cleaning any artifact that has been generated on disk by such instances.

Run with Podman/Docker on MacOS

If you run the sample inventory on macOS, you can run in connectivity issues between containers. Indeed, on macOS Docker runs using a Linux VM, which points to a different localhost from the host (aka macOS) one.

To overcome this problem, containers need to point to host.docker.internal in order to correctly resolve the other containers. Thus, run the following command in your shell:

# add this to .bashrc or any other file sourced by your shell
export LOCAL_ANSIBLE_HOST="host.docker.internal"

Moreover, since now all configuration files will point to host.docker.internal, add it as an alternative resolution name for your macOS localhost (in order to let the binaries resolve also host.docker.internal) by modifying /etc/hosts:

sudo echo "127.0.0.1 host.docker.internal" >> /etc/hosts

Supported commands

All the high-level commands are defined within the Makefile. To get the list of all the possible commands, run:

make help

Here there is a list of the most used commands:

Command	Usage
install	Build and install the hyperledger.fabricx collection locally.
install-deps	Wrapper for install-venv + install-python-deps + install-ansible-deps.
install-venv	Install a venv environment.
install-python-deps	Install Python dependencies on the control node.
install-ansible-deps	Install the Ansible collections required by this repository.
install-remote-node-deps	Install the needed dependencies on the remote hosts.
lint	Run ansible-lint checks.
check-license-header	Verify license headers on all files.
check-trailing-spaces	Check for trailing spaces in .j2 files.
login-cr	Log a container engine within a container registry.
setup	Wrapper for binaries + artifacts + configs.
artifacts	Wrapper for generate-crypto + genesis-block.
generate-crypto	Generate the crypto material on the controller node.
genesis-block	Build the genesis block for the network.
binaries	Build/install binaries on controller or remote nodes for the targeted hosts.
clean	Clean all the artifacts and binaries built on the controller node.
clean-cache	Clean the Ansible cache.
configs	Create/Ship the configs to the remote nodes.
start	Start the targeted hosts.
stop	Stop the targeted hosts without deleting the data.
teardown	Teardown the targeted hosts (stop and delete data).
update	Update the targeted hosts (stop + binaries + start).
restart	Restart the targeted hosts (stop + start).
hard-restart	Hard restart the targeted hosts (teardown + start).
wipe	Wipe out the config artifacts and the binaries from the remote hosts.
hard-wipe	Wipe the deploy folder from the remote hosts.
targets	Generate Makefile targets for all inventory hosts.
run-command	Run a generic command on the targeted hosts.
ping	Check that the component ports are open.
get-metrics	Get the metrics from the targeted components.
fetch-crypto	Fetch the crypto material from the targeted hosts.
fetch-logs	Fetch the logs from the targeted hosts.
limit-rate	Set the TPS rate on the load generators.

Restrict commands to a group of hosts

By default all the Makefile commands target all the hosts which are defined within the reference inventory. However, the playbooks have been tailored in such a way that the actions can be restricted to a sub-group (or even a single host) through the target_hosts Ansible variable, which is reflected as the TARGET_HOSTS variable in the Makefile.

The Makefile comes with a set of predefined host groups that can be used to easily restrict commands:

Group	Target
fabric_cas	The Fabric CA servers
fabric_x	The Fabric-X network nodes (orderers+committer).
fabric_x_orderers	All the Fabric-X orderers.
fabric_x_committer	The Fabric-X committer components.
load_generators	All the load_generators.
monitoring	All the monitoring instances.

For example, running:

make fabric_x_orderers start

restricts the command to the host group fabric_x_orderers defined within the inventory.

All these groups are reflected in the sample inventory. If you plan to use the playbooks provided with the collection, we recommend to keep the names identical in order to leverage all the playbooks capabilities.

Contributing

Contributions to this project are welcomed and encouraged.

If you'd like to help improve this project, please follow these steps:

1. Fork the repository;

2. Create a new branch for your feature or bugfix:

git checkout -b your-feature-name

License

This project is licensed under the Apache License 2.0.
You are free to use, modify, and distribute this software in accordance with the terms of the license.

For more details, please refer to the LICENSE file included in this repository.