You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

291 lines
9.0 KiB

7 years ago
7 years ago
  1. Using Ansible
  2. =============
  3. .. figure:: assets/a_plus_t.png
  4. :alt: Ansible plus Tendermint
  5. Ansible plus Tendermint
  6. The playbooks in `our ansible directory <https://github.com/tendermint/tools/tree/master/ansible>`__
  7. run ansible `roles <http://www.ansible.com/>`__ which:
  8. - install and configure basecoin or ethermint
  9. - start/stop basecoin or ethermint and reset their configuration
  10. Prerequisites
  11. -------------
  12. - Ansible 2.0 or higher
  13. - SSH key to the servers
  14. Optional for DigitalOcean droplets:
  15. - DigitalOcean API Token
  16. - python dopy package
  17. For a description on how to get a DigitalOcean API Token, see the explanation
  18. in the `using terraform tutorial <./terraform-digitalocean.html>`__.
  19. Optional for Amazon AWS instances:
  20. - Amazon AWS API access key ID and secret access key.
  21. The cloud inventory scripts come from the ansible team at their
  22. `GitHub <https://github.com/ansible/ansible>`__ page. You can get the
  23. latest version from the ``contrib/inventory`` folder.
  24. Setup
  25. -----
  26. Ansible requires a "command machine" or "local machine" or "orchestrator
  27. machine" to run on. This can be your laptop or any machine that can run
  28. ansible. (It does not have to be part of the cloud network that hosts
  29. your servers.)
  30. Use the official `Ansible installation
  31. guide <http://docs.ansible.com/ansible/intro_installation.html>`__ to
  32. install Ansible. Here are a few examples on basic installation commands:
  33. Ubuntu/Debian:
  34. ::
  35. sudo apt-get install ansible
  36. CentOS/RedHat:
  37. ::
  38. sudo yum install epel-release
  39. sudo yum install ansible
  40. Mac OSX: If you have `Homebrew <https://brew.sh>`__ installed, then it's:
  41. ::
  42. brew install ansible
  43. If not, you can install it using ``pip``:
  44. ::
  45. sudo easy_install pip
  46. sudo pip install ansible
  47. To make life easier, you can start an SSH Agent and load your SSH
  48. key(s). This way ansible will have an uninterrupted way of connecting to
  49. your servers.
  50. ::
  51. ssh-agent > ~/.ssh/ssh.env
  52. source ~/.ssh/ssh.env
  53. ssh-add private.key
  54. Subsequently, as long as the agent is running, you can use
  55. ``source ~/.ssh/ssh.env`` to load the keys to the current session. Note:
  56. On Mac OSX, you can add the ``-K`` option to ssh-add to store the
  57. passphrase in your keychain. The security of this feature is debated but
  58. it is convenient.
  59. Optional cloud dependencies
  60. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  61. If you are using a cloud provider to host your servers, you need the
  62. below dependencies installed on your local machine.
  63. DigitalOcean inventory dependencies:
  64. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  65. Ubuntu/Debian:
  66. ::
  67. sudo apt-get install python-pip
  68. sudo pip install dopy
  69. CentOS/RedHat:
  70. ::
  71. sudo yum install python-pip
  72. sudo pip install dopy
  73. Mac OSX:
  74. ::
  75. sudo pip install dopy
  76. Amazon AWS inventory dependencies:
  77. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  78. Ubuntu/Debian:
  79. ::
  80. sudo apt-get install python-boto
  81. CentOS/RedHat:
  82. ::
  83. sudo yum install python-boto
  84. Mac OSX:
  85. ::
  86. sudo pip install boto
  87. Refreshing the DigitalOcean inventory
  88. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  89. If you just finished creating droplets, the local DigitalOcean inventory
  90. cache is not up-to-date. To refresh it, run:
  91. ::
  92. DO_API_TOKEN="<The API token received from DigitalOcean>"
  93. python -u inventory/digital_ocean.py --refresh-cache 1> /dev/null
  94. Refreshing the Amazon AWS inventory
  95. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  96. If you just finished creating Amazon AWS EC2 instances, the local AWS
  97. inventory cache is not up-to-date. To refresh it, run:
  98. ::
  99. AWS_ACCESS_KEY_ID='<The API access key ID received from Amazon>'
  100. AWS_SECRET_ACCESS_KEY='<The API secret access key received from Amazon>'
  101. python -u inventory/ec2.py --refresh-cache 1> /dev/null
  102. Note: you don't need the access key and secret key set, if you are
  103. running ansible on an Amazon AMI instance with the proper IAM
  104. permissions set.
  105. Running the playbooks
  106. ---------------------
  107. The playbooks are locked down to only run if the environment variable
  108. ``TF_VAR_TESTNET_NAME`` is populated. This is a precaution so you don't
  109. accidentally run the playbook on all your servers.
  110. The variable ``TF_VAR_TESTNET_NAME`` contains the testnet name which
  111. ansible translates into an ansible group. If you used Terraform to
  112. create the servers, it was the testnet name used there.
  113. If the playbook cannot connect to the servers because of public key
  114. denial, your SSH Agent is not set up properly. Alternatively you can add
  115. the SSH key to ansible using the ``--private-key`` option.
  116. If you need to connect to the nodes as root but your local username is
  117. different, use the ansible option ``-u root`` to tell ansible to connect
  118. to the servers and authenticate as the root user.
  119. If you secured your server and you need to ``sudo`` for root access, use
  120. the the ``-b`` or ``--become`` option to tell ansible to sudo to root
  121. after connecting to the server. In the Terraform-DigitalOcean example,
  122. if you created the ec2-user by adding the ``noroot=true`` option (or if
  123. you are simply on Amazon AWS), you need to add the options
  124. ``-u ec2-user -b`` to ansible to tell it to connect as the ec2-user and
  125. then sudo to root to run the playbook.
  126. DigitalOcean
  127. ~~~~~~~~~~~~
  128. ::
  129. DO_API_TOKEN="<The API token received from DigitalOcean>"
  130. TF_VAR_TESTNET_NAME="testnet-servers"
  131. ansible-playbook -i inventory/digital_ocean.py install.yml -e service=basecoin
  132. Amazon AWS
  133. ~~~~~~~~~~
  134. ::
  135. AWS_ACCESS_KEY_ID='<The API access key ID received from Amazon>'
  136. AWS_SECRET_ACCESS_KEY='<The API secret access key received from Amazon>'
  137. TF_VAR_TESTNET_NAME="testnet-servers"
  138. ansible-playbook -i inventory/ec2.py install.yml -e service=basecoin
  139. Installing custom versions
  140. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  141. By default ansible installs the tendermint, basecoin or ethermint binary
  142. versions from the latest release in the repository. If you build your
  143. own version of the binaries, you can tell ansible to install that
  144. instead.
  145. ::
  146. GOPATH="<your go path>"
  147. go get -u github.com/tendermint/basecoin/cmd/basecoin
  148. DO_API_TOKEN="<The API token received from DigitalOcean>"
  149. TF_VAR_TESTNET_NAME="testnet-servers"
  150. ansible-playbook -i inventory/digital_ocean.py install.yml -e service=basecoin -e release_install=false
  151. Alternatively you can change the variable settings in
  152. ``group_vars/all``.
  153. Other commands and roles
  154. ------------------------
  155. There are few extra playbooks to make life easier managing your servers.
  156. - install.yml - Install basecoin or ethermint applications. (Tendermint
  157. gets installed automatically.) Use the ``service`` parameter to
  158. define which application to install. Defaults to ``basecoin``.
  159. - reset.yml - Stop the application, reset the configuration and data,
  160. then start the application again. You need to pass
  161. ``-e service=<servicename>``, like ``-e service=basecoin``. It will
  162. restart the underlying tendermint application too.
  163. - restart.yml - Restart a service on all nodes. You need to pass
  164. ``-e service=<servicename>``, like ``-e service=basecoin``. It will
  165. restart the underlying tendermint application too.
  166. - stop.yml - Stop the application. You need to pass
  167. ``-e service=<servicename>``.
  168. - status.yml - Check the service status and print it. You need to pass
  169. ``-e service=<servicename>``.
  170. - start.yml - Start the application. You need to pass
  171. ``-e service=<servicename>``.
  172. - ubuntu16-patch.yml - Ubuntu 16.04 does not have the minimum required
  173. python package installed to be able to run ansible. If you are using
  174. ubuntu, run this playbook first on the target machines. This will
  175. install the python pacakge that is required for ansible to work
  176. correctly on the remote nodes.
  177. - upgrade.yml - Upgrade the ``service`` on your testnet. It will stop
  178. the service and restart it at the end. It will only work if the
  179. upgraded version is backward compatible with the installed version.
  180. - upgrade-reset.yml - Upgrade the ``service`` on your testnet and reset
  181. the database. It will stop the service and restart it at the end. It
  182. will work for upgrades where the new version is not
  183. backward-compatible with the installed version - however it will
  184. reset the testnet to its default.
  185. The roles are self-sufficient under the ``roles/`` folder.
  186. - install - install the application defined in the ``service``
  187. parameter. It can install release packages and update them with
  188. custom-compiled binaries.
  189. - unsafe\_reset - delete the database for a service, including the
  190. tendermint database.
  191. - config - configure the application defined in ``service``. It also
  192. configures the underlying tendermint service. Check
  193. ``group_vars/all`` for options.
  194. - stop - stop an application. Requires the ``service`` parameter set.
  195. - status - check the status of an application. Requires the ``service``
  196. parameter set.
  197. - start - start an application. Requires the ``service`` parameter set.
  198. Default variables
  199. -----------------
  200. Default variables are documented under ``group_vars/all``. You can the
  201. parameters there to deploy a previously created genesis.json file
  202. (instead of dynamically creating it) or if you want to deploy custom
  203. built binaries instead of deploying a released version.