Cello Ansible
研发日记 Mason · 31浏览 · 2018-02-20

Cello Ansible agent how-to

Cello Ansible agent is a set of Ansible playbooks which allows developers and Fabric network operators to stand up a Hyperledger Fabric network very quickly in a set of virtual or physical servers in cloud or lab.

The following is the list of the general steps you can follow to use the Ansible agent to stand up your own fabric network:

  1. Setup Ansible controller
  2. Create configuration files
  3. Provision the servers
  4. Initialize the servers
  5. Setup fabric network
  6. Verify fabric network

This document also provides the following sections to help you use the Cello Ansible agent:

Cloud configuration file details
Fabric configuration file details
Running an Ansible playbook
Use ssh-agent to help Ansible
Convenient configurations and commands
Use the existing servers
Security rule references

Set up the Ansible controller

You need an Ansible controller to run Ansible playbooks. An Ansible controller can be any machine (Virtualbox VM, your laptop, AWS instance, etc) that has Ansible or greater installed on it.

  1. Install Ansible
  2. Generate a ssh key pair
  3. Clone Ansible agent code
  4. Install Ansible cloud module

Install Ansible

Please follow the offical Ansible installation instructions from the Ansible web site to install Ansible. If you want to start quickly and already have a clean Ubuntu 16.04 system, here are the commands to install Ansible:

    sudo apt-get update
    sudo apt-get install python-pip -y
    sudo pip install 'ansible>='

Once it is installed, you should run following command to check its version:

    ansible --version

The results should show something at or above It is entirely possible that you may have to install additional software that Ansible depends on in some older versions of operating systems.

Generate a ssh key pair

Ansible relies heavily on ssh to work with virtual or physical servers. To establish an ssh connection to the servers, you will need an ssh key pair. You may choose to use your own preexisting pair, but it is highly recommended to create a new one for test purposes. Here are the steps to generate a key pair:

    mkdir -p ~/.ssh && cd ~/.ssh && ssh-keygen -t rsa -f fd -P ""

This will create a ssh key pair without a passphrase in your ~/.ssh directory. The name of the private and public key files will be fd and fd.pub, respectively. In the default Ansible agent playbook configuration files, the ssh key is assumed to exist at that location with those names. If you use different names, then you will need to change the configuration to match your own ssh key pair filenames.

When you run the playbook against a cloud such as OpenStack or AWS, the ssh public key you generated above will be automatically injected into the servers during the Provision the servers step. If your servers were not provisioned by the Cello Ansible agent, you will have to manually inject/copy the public key onto each machine. For each machine, you will also need to place the ssh public key in the file named ~/.ssh/authorized_keys in the user account which you will use to log into the server.

Once you have the ssh keys, start up the ssh agent on the Ansible controller, using the following command:

    eval $(ssh-agent -s) && ssh-add ~/.ssh/fd

Clone Ansible agent code

The Ansible agent is part of the Hyperledger Cello project. To run its playbooks, you will need to clone the Cello repo.

   cd ~
   git clone --depth=1 https://gerrit.hyperledger.org/r/cello

This command will clone the repo into a folder named cello. The Ansible agent is at the following directory:


from this point on, you should stay in that directory for all command executions. This directory is also referred to root agent directory. For convenience, you can execute the following command to help you get back to this directory easily:

   export AAROOT=~/cello/src/agent/ansible
   cd $AAROOT

Install Ansible cloud module

When you run the playbook against a cloud such as OpenStack or AWS, Ansible requires that specific libraries be installed on the controller to access these clouds. These libraries are normally called Ansible cloud modules. When you work with a specific cloud, you will need only to install the cloud modules for that cloud. Here are the steps to install Ansible modules for AWS, Azure and OpenStack respectively:

    sudo pip3 install boto boto3

    sudo pip3 install azure

    sudo pip3 install shade

These modules are used during the Provision the servers step. If you are not running the Ansible agent against a cloud provider, you do not need any of these modules.

Create configuration files

The Ansible agent relies on two configuration files to work and stand up your fabric network. One is the cloud configuration file, the other is the fabric configuration file.

The cloud configuration file is used when running against a cloud such as AWS, Azure or OpenStack to create virtual machines, create security rules for networking, inject ssh keys, and eventually delete the virtual machines when you decide to destroy everything you created. Ansible agent provides the following sample cloud configuration files:


You should create a copy of one of the above cloud configuration example files and modify it as needed with your cloud credentials, etc.

The fabric configuration file is used to define how the Hyperledger Fabric network will be created. This file will let you specify what release of Fabric you want to use, what organizations to create, how many peers or orderers will be in an organization, how many kafka and zookeeper nodes you'd like to have and how you want to lay out your Fabric network on the servers you have. Ansible agent provides the following sample fabric configuration files:


You should create a copy of one of the above fabric configuration example files and modify it as needed with your desired Fabric topology, if needed.

Together, the fabric and cloud configuration files ultimately control what your Fabric network will look like. You should make your own copies, then make changes to those copies based on your own needs and credentials to run the Ansible playbook to produce your Fabric network. Your copies of these configuration files should be in the same directory as the example files, or Ansible will be unable to find them.

The following examples will assume you have created your own cloud configuration file copy named mycloud.yml and your own fabric configuration file copy named myfabric.yml from their respective sample files. Since both types of sample files are relatively large, have a good understanding of what each field means in both files is absolutely critical. Please refer to the following two sections for details on each field in the two types of files.

Cloud configuration file details
Fabric configuration file details

Provision the servers

This initial step provisions a set of virtual servers from cloud in a cloud provider.

    ansible-playbook -e "mode=apply env=mycloud cloud_type=os" provcluster.yml

The above command will provision (prov is short for provision) a cluster of virtual machines using an OpenStack cloud, with the environment and configuration defined in the vars/mycloud.yml file. The value apply for the parameter mode tells the playbook to create the resources. The value os for the parameter cloud_type indicates that we are running this playbook against an OpenStack cloud. The value mycloud for the parameter env indicates the cloud config file vars/mycloud.yml should be used. The possible values for mode are apply and destroy, the possible values for cloud_type are os, aws and azure at present.

This step produces a set of servers in your cloud and an Ansible host file named runhosts in this directory on your Ansible controller:


If you are working with servers already exist, you will need to follow the section Use the existing servers to continue setting up your fabric network.

To remove everything this step created, run the following command:

    ansible-playbook -e "mode=destroy env=mycloud cloud_type=os" provcluster.yml

Initialize the servers

This step will install all necessary software packages, setup an overlay network, and configure DNS services and registrator services on the machines created in previous step:

    ansible-playbook -i run/runhosts -e "mode=apply env=mycloud env_type=flanneld" initcluster.yml

The parameter env is same as in previous step. The parameter env_type indicates what communication environment you would like to setup. The possible values for this parameter are flanneld and k8s. Value flanneld is used to setup a docker swarm like environment. Value k8s is to set up a Kuberenetes environment.

To remove everything this step created, run the following command:

    ansible-playbook -i run/runhosts -e "mode=destroy env=mycloud env_type=flanneld" initcluster.yml

Set up the Fabric network

This step will build (or download from a Docker repository) the various required Fabric binaries and docker images, create certificates, and eventually run various fabric components such as peer, orderer, kafka, zookeeper, fabric ca, etc on the environment produced by the previous steps:

    ansible-playbook -i run/runhosts -e "mode=apply env=myfabric deploy_type=compose" setupfabric.yml

The env value in the command indicates which Fabric network configuration to use. The meaning of this parameter is a bit different compared to the previous commands. The parameter deploy_type determines if docker compose will be used to deploy, or Kubernetes will be used to deploy. This should corrlate to the env_type parameter given in the Initialize the servers step.

To remove everything this step created, run the following command:

    ansible-playbook -i run/runhosts -e "mode=destroy env=myfabric deploy_type=compose" setupfabric.yml

Verify the Fabric network

If all previous steps run without any errors, you can run the following playbook to verify the running status of each container:

    ansible-playbook -i run/runhosts -e "mode=verify env=bc1st" verify.yml

The env value in the command should match the value used in Setup the fabric network The command should access all the servers and display the container status for each container in your fabric network. If these containers do not exit/crash, then you know you have successfully deployed your own fabric network.

Useful tips for running the Ansible agent

Cloud configuration file details

The cloud configuration file is used by Ansible agent to work with a specific cloud. It is very important to make every field in the file accurate according to your own cloud. Most of the information in this file should be provided by your cloud provider. If you are not 100% sure what value a field should have, it would be a good idea to use the corresponding value in the sample cloud configuration file. The following section describes what each field means. Please use vars/os.yml as a reference and see example values for these fields:

auth: Authorization fields for a cloud
auth_url: url for cloud Authorization
username: User name to log in to the cloud account
password: Password for the user of the cloud account
project_name: Name of the project of your cloud, specific to OpenStack
domain: The domain of the project, specific to OpenStack
cluster: This section defines how virtual machines should be created
target_os: The operating system we are targeting, it has to be `ubuntu`
    at present
image_name: Cloud image name to be used to create virtual machines
region_name: Region name for VMs to reside in, leave blank if unsure
ssh_user: The user id to be used to access the virtual machines via ssh
availability_zone: The availability zone, leave blank to use default
validate_certs: When access cloud, should the certs to be validated?
    Set to false if your cloud use self signed certificate
private_net_name: The private network name from your cloud account on
    which your VMs should be created
flavor_name: Flavor name to create your virtual machine
public_key_file: The public ssh key file used to connect to servers,
    use absolute path
private_key_file: The private ssh key file, use absolute path,
    public_key_file and this key file should make a pair
node_ip: Use public ip or private ip to access each server, only possible
    value are `public_ip` and `private_ip`
assign_public_ip: Should each VM be allocated public IP address or not, true
    or false, default is true
container_network: This section defines overlay network, you should not
    change this unless you absolutely know what you are doing
Network: Overlay network address space, should be always in cidr notion,
    such as
SubnetLen: The bit length for subnets, it should be 24 normally, do not
    change it unless you absolutely know what you are doing
SubnetMin: minimum subnet
SubnetMax: maximum subnet
Backend: backend for flanneld setup
Type: the type for flanneld setup
Port: the port to use
service_ip_range: when use k8s, this defines service ip range
dns_service_ip: dns service ip address for k8s
node_ips: a list of public IP addresses if you like the VMs to be accessible
    and using preallocated IP addresses
name_prefix: VM name prefix when create new VMs, this combines with
    stack_size to make VM names. These names will be used in fabric
    configuration For example,if your prefix is fabric, and stack
    size is 3, then you will have 3 VMs named fabric001, fabric002,
    fabric003, these names will be referred as server logic names
domain: domain name to use when create fabric network nodes.
stack_size: how many VMs to be created
etcdnodes: which nodes you like the etcd to be set up on. only needed
    for k8s, should be a list of logic name like fabric001, fabric002,
builders: which VM to be used to build fabric binaries. should be only one
    machine, use logic name like fabric001, fabric002, etc.
flannel_repo: The url point to the flanneld tar gz file
etcd_repo: The url point to the etcd tar gz file
k8s_repo: The url point to the k8s binary root directory
go_repo: The url point to the go lang tar gz file
volume_size: when create VMs the size of the volume
block_device_name: block device name when create volume on OpenStack cloud
    fabric network, to verify that, you can run the following command to see
0 人收藏 0 人喜欢

1 次打赏,共 1


科技 数码


行业资讯 http://www.thinksns.com/ · 11浏览 · 2018-03-15


行业资讯 http://www.thinksns.com/ · 102浏览 · 2018-03-09


产品交流 原创 · 24浏览 · 2018-03-01
0 人评论
可输入 255