From f2dae2a2d877620fc958b9b4976872301d1e1fd9 Mon Sep 17 00:00:00 2001 From: Greg Szabo Date: Fri, 13 Apr 2018 21:03:25 -0400 Subject: [PATCH] Moved to networks folder, introduced cloud server scripts using terraform and ansible (sentry nodes) --- Makefile | 22 +- {docker-compose => networks/local}/Makefile | 0 {docker-compose => networks/local}/README.rst | 0 .../local}/localnode/Dockerfile | 0 .../local}/localnode/wrapper.sh | 0 networks/remote/ansible/.gitignore | 1 + networks/remote/ansible/README.rst | 291 ++++++++ networks/remote/ansible/ansible.cfg | 4 + networks/remote/ansible/assets/a_plus_t.png | Bin 0 -> 13830 bytes networks/remote/ansible/install.yml | 11 + networks/remote/ansible/inventory/COPYING | 675 ++++++++++++++++++ .../ansible/inventory/digital_ocean.ini | 34 + .../remote/ansible/inventory/digital_ocean.py | 471 ++++++++++++ networks/remote/ansible/reconfig.yml | 16 + networks/remote/ansible/reset.yml | 14 + networks/remote/ansible/restart.yml | 12 + .../ansible/roles/config/tasks/main.yml | 15 + .../ansible/roles/install/handlers/main.yml | 5 + .../ansible/roles/install/tasks/main.yml | 15 + .../install/templates/systemd.service.j2 | 17 + .../remote/ansible/roles/start/tasks/main.yml | 5 + .../ansible/roles/status/tasks/main.yml | 10 + .../remote/ansible/roles/stop/tasks/main.yml | 5 + .../ansible/roles/unsafe_reset/tasks/main.yml | 3 + networks/remote/ansible/start.yml | 11 + networks/remote/ansible/status.yml | 11 + networks/remote/ansible/stop.yml | 11 + networks/remote/terraform/.gitignore | 4 + networks/remote/terraform/README.rst | 33 + networks/remote/terraform/cluster/main.tf | 28 + networks/remote/terraform/cluster/outputs.tf | 15 + .../remote/terraform/cluster/variables.tf | 25 + networks/remote/terraform/main.tf | 37 + 33 files changed, 1799 insertions(+), 2 deletions(-) rename {docker-compose => networks/local}/Makefile (100%) rename {docker-compose => networks/local}/README.rst (100%) rename {docker-compose => networks/local}/localnode/Dockerfile (100%) rename {docker-compose => networks/local}/localnode/wrapper.sh (100%) create mode 100644 networks/remote/ansible/.gitignore create mode 100644 networks/remote/ansible/README.rst create mode 100644 networks/remote/ansible/ansible.cfg create mode 100644 networks/remote/ansible/assets/a_plus_t.png create mode 100644 networks/remote/ansible/install.yml create mode 100644 networks/remote/ansible/inventory/COPYING create mode 100644 networks/remote/ansible/inventory/digital_ocean.ini create mode 100755 networks/remote/ansible/inventory/digital_ocean.py create mode 100644 networks/remote/ansible/reconfig.yml create mode 100644 networks/remote/ansible/reset.yml create mode 100644 networks/remote/ansible/restart.yml create mode 100644 networks/remote/ansible/roles/config/tasks/main.yml create mode 100644 networks/remote/ansible/roles/install/handlers/main.yml create mode 100644 networks/remote/ansible/roles/install/tasks/main.yml create mode 100644 networks/remote/ansible/roles/install/templates/systemd.service.j2 create mode 100644 networks/remote/ansible/roles/start/tasks/main.yml create mode 100644 networks/remote/ansible/roles/status/tasks/main.yml create mode 100644 networks/remote/ansible/roles/stop/tasks/main.yml create mode 100644 networks/remote/ansible/roles/unsafe_reset/tasks/main.yml create mode 100644 networks/remote/ansible/start.yml create mode 100644 networks/remote/ansible/status.yml create mode 100644 networks/remote/ansible/stop.yml create mode 100644 networks/remote/terraform/.gitignore create mode 100644 networks/remote/terraform/README.rst create mode 100644 networks/remote/terraform/cluster/main.tf create mode 100644 networks/remote/terraform/cluster/outputs.tf create mode 100644 networks/remote/terraform/cluster/variables.tf create mode 100644 networks/remote/terraform/main.tf diff --git a/Makefile b/Makefile index da94627d..5e5b9675 100644 --- a/Makefile +++ b/Makefile @@ -187,14 +187,32 @@ build-linux: # Run a 4-node testnet locally docker-start: - @echo "Wait until 'Attaching to node0, node1, node2, node3' message appears" - @if ! [ -f build/node0/config/genesis.json ]; then docker run --rm -v `pwd`/build:/tendermint:Z tendermint/localnode testnet --v 4 --o . --populate-persistent-peers --starting-ip-address 192.167.10.2 ; fi + @if ! [ -f build/node0/config/genesis.json ]; then docker run --rm -v $(CURDIR)/build:/tendermint:Z tendermint/localnode testnet --v 4 --o . --populate-persistent-peers --starting-ip-address 192.167.10.2 ; fi docker-compose up # Stop testnet docker-stop: docker-compose down +########################################################### +### Remote full-nodes (sentry) using terraform and ansible + +# Server management +server-setup: + @if ! [ -f $(HOME)/.ssh/id_rsa.pub ]; then ssh-keygen ; fi + cd networks/remote/terraform && terraform init && terraform apply -var DO_API_TOKEN="$(DO_API_TOKEN)" -var SSH_KEY_FILE="$(HOME)/.ssh/id_rsa.pub" +# @if ! [ -f $(CURDIR)/build/node0/config/genesis.json ]; then docker run --rm -v $(CURDIR)/build:/tendermint:Z tendermint/localnode testnet --n 4 --o . ; fi + build/tendermint testnet --n 4 --o build/ + cd networks/remote/ansible && ansible-playbook -i inventory/digital_ocean.py -l remotenet --ssh-common-args '-o StrictHostKeyChecking=False' install.yml + $(MAKE) server-config + +server-destroy: + cd networks/remote/terraform && terraform destroy + +# Configuration management +server-config: + cd networks/remote/ansible && ansible-playbook -i inventory/digital_ocean.py -l remotenet reconfig.yml -e BINARY=$(CURDIR)/build/tendermint -e CONFIGDIR=$(CURDIR)/build + # To avoid unintended conflicts with file names, always add to .PHONY # unless there is a reason not to. # https://www.gnu.org/software/make/manual/html_node/Phony-Targets.html diff --git a/docker-compose/Makefile b/networks/local/Makefile similarity index 100% rename from docker-compose/Makefile rename to networks/local/Makefile diff --git a/docker-compose/README.rst b/networks/local/README.rst similarity index 100% rename from docker-compose/README.rst rename to networks/local/README.rst diff --git a/docker-compose/localnode/Dockerfile b/networks/local/localnode/Dockerfile similarity index 100% rename from docker-compose/localnode/Dockerfile rename to networks/local/localnode/Dockerfile diff --git a/docker-compose/localnode/wrapper.sh b/networks/local/localnode/wrapper.sh similarity index 100% rename from docker-compose/localnode/wrapper.sh rename to networks/local/localnode/wrapper.sh diff --git a/networks/remote/ansible/.gitignore b/networks/remote/ansible/.gitignore new file mode 100644 index 00000000..a8b42eb6 --- /dev/null +++ b/networks/remote/ansible/.gitignore @@ -0,0 +1 @@ +*.retry diff --git a/networks/remote/ansible/README.rst b/networks/remote/ansible/README.rst new file mode 100644 index 00000000..5c416c01 --- /dev/null +++ b/networks/remote/ansible/README.rst @@ -0,0 +1,291 @@ +Using Ansible +============= + +.. figure:: assets/a_plus_t.png + :alt: Ansible plus Tendermint + + Ansible plus Tendermint + +The playbooks in `our ansible directory `__ +run ansible `roles `__ which: + +- install and configure basecoind or ethermint +- start/stop basecoind or ethermint and reset their configuration + +Prerequisites +------------- + +- Ansible 2.0 or higher +- SSH key to the servers + +Optional for DigitalOcean droplets: + +- DigitalOcean API Token +- python dopy package + +For a description on how to get a DigitalOcean API Token, see the explanation +in the `using terraform tutorial <./terraform-digitalocean.html>`__. + +Optional for Amazon AWS instances: + +- Amazon AWS API access key ID and secret access key. + +The cloud inventory scripts come from the ansible team at their +`GitHub `__ page. You can get the +latest version from the ``contrib/inventory`` folder. + +Setup +----- + +Ansible requires a "command machine" or "local machine" or "orchestrator +machine" to run on. This can be your laptop or any machine that can run +ansible. (It does not have to be part of the cloud network that hosts +your servers.) + +Use the official `Ansible installation +guide `__ to +install Ansible. Here are a few examples on basic installation commands: + +Ubuntu/Debian: + +:: + + sudo apt-get install ansible + +CentOS/RedHat: + +:: + + sudo yum install epel-release + sudo yum install ansible + +Mac OSX: If you have `Homebrew `__ installed, then it's: + +:: + + brew install ansible + +If not, you can install it using ``pip``: + +:: + + sudo easy_install pip + sudo pip install ansible + +To make life easier, you can start an SSH Agent and load your SSH +key(s). This way ansible will have an uninterrupted way of connecting to +your servers. + +:: + + ssh-agent > ~/.ssh/ssh.env + source ~/.ssh/ssh.env + + ssh-add private.key + +Subsequently, as long as the agent is running, you can use +``source ~/.ssh/ssh.env`` to load the keys to the current session. Note: +On Mac OSX, you can add the ``-K`` option to ssh-add to store the +passphrase in your keychain. The security of this feature is debated but +it is convenient. + +Optional cloud dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are using a cloud provider to host your servers, you need the +below dependencies installed on your local machine. + +DigitalOcean inventory dependencies: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Ubuntu/Debian: + +:: + + sudo apt-get install python-pip + sudo pip install dopy + +CentOS/RedHat: + +:: + + sudo yum install python-pip + sudo pip install dopy + +Mac OSX: + +:: + + sudo pip install dopy + +Amazon AWS inventory dependencies: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Ubuntu/Debian: + +:: + + sudo apt-get install python-boto + +CentOS/RedHat: + +:: + + sudo yum install python-boto + +Mac OSX: + +:: + + sudo pip install boto + +Refreshing the DigitalOcean inventory +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you just finished creating droplets, the local DigitalOcean inventory +cache is not up-to-date. To refresh it, run: + +:: + + DO_API_TOKEN="" + python -u inventory/digital_ocean.py --refresh-cache 1> /dev/null + +Refreshing the Amazon AWS inventory +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you just finished creating Amazon AWS EC2 instances, the local AWS +inventory cache is not up-to-date. To refresh it, run: + +:: + + AWS_ACCESS_KEY_ID='' + AWS_SECRET_ACCESS_KEY='' + python -u inventory/ec2.py --refresh-cache 1> /dev/null + +Note: you don't need the access key and secret key set, if you are +running ansible on an Amazon AMI instance with the proper IAM +permissions set. + +Running the playbooks +--------------------- + +The playbooks are locked down to only run if the environment variable +``TF_VAR_TESTNET_NAME`` is populated. This is a precaution so you don't +accidentally run the playbook on all your servers. + +The variable ``TF_VAR_TESTNET_NAME`` contains the testnet name which +ansible translates into an ansible group. If you used Terraform to +create the servers, it was the testnet name used there. + +If the playbook cannot connect to the servers because of public key +denial, your SSH Agent is not set up properly. Alternatively you can add +the SSH key to ansible using the ``--private-key`` option. + +If you need to connect to the nodes as root but your local username is +different, use the ansible option ``-u root`` to tell ansible to connect +to the servers and authenticate as the root user. + +If you secured your server and you need to ``sudo`` for root access, use +the the ``-b`` or ``--become`` option to tell ansible to sudo to root +after connecting to the server. In the Terraform-DigitalOcean example, +if you created the ec2-user by adding the ``noroot=true`` option (or if +you are simply on Amazon AWS), you need to add the options +``-u ec2-user -b`` to ansible to tell it to connect as the ec2-user and +then sudo to root to run the playbook. + +DigitalOcean +~~~~~~~~~~~~ + +:: + + DO_API_TOKEN="" + TF_VAR_TESTNET_NAME="testnet-servers" + ansible-playbook -i inventory/digital_ocean.py install.yml -e service=basecoind + +Amazon AWS +~~~~~~~~~~ + +:: + + AWS_ACCESS_KEY_ID='' + AWS_SECRET_ACCESS_KEY='' + TF_VAR_TESTNET_NAME="testnet-servers" + ansible-playbook -i inventory/ec2.py install.yml -e service=basecoind + +Installing custom versions +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default ansible installs the tendermint, basecoind or ethermint binary +versions from the latest release in the repository. If you build your +own version of the binaries, you can tell ansible to install that +instead. + +:: + + GOPATH="" + go get -u github.com/tendermint/basecoin/cmd/basecoind + + DO_API_TOKEN="" + TF_VAR_TESTNET_NAME="testnet-servers" + ansible-playbook -i inventory/digital_ocean.py install.yml -e service=basecoind -e release_install=false + +Alternatively you can change the variable settings in +``group_vars/all``. + +Other commands and roles +------------------------ + +There are few extra playbooks to make life easier managing your servers. + +- install.yml - Install basecoind or ethermint applications. (Tendermint + gets installed automatically.) Use the ``service`` parameter to + define which application to install. Defaults to ``basecoind``. +- reset.yml - Stop the application, reset the configuration and data, + then start the application again. You need to pass + ``-e service=``, like ``-e service=basecoind``. It will + restart the underlying tendermint application too. +- restart.yml - Restart a service on all nodes. You need to pass + ``-e service=``, like ``-e service=basecoind``. It will + restart the underlying tendermint application too. +- stop.yml - Stop the application. You need to pass + ``-e service=``. +- status.yml - Check the service status and print it. You need to pass + ``-e service=``. +- start.yml - Start the application. You need to pass + ``-e service=``. +- ubuntu16-patch.yml - Ubuntu 16.04 does not have the minimum required + python package installed to be able to run ansible. If you are using + ubuntu, run this playbook first on the target machines. This will + install the python pacakge that is required for ansible to work + correctly on the remote nodes. +- upgrade.yml - Upgrade the ``service`` on your testnet. It will stop + the service and restart it at the end. It will only work if the + upgraded version is backward compatible with the installed version. +- upgrade-reset.yml - Upgrade the ``service`` on your testnet and reset + the database. It will stop the service and restart it at the end. It + will work for upgrades where the new version is not + backward-compatible with the installed version - however it will + reset the testnet to its default. + +The roles are self-sufficient under the ``roles/`` folder. + +- install - install the application defined in the ``service`` + parameter. It can install release packages and update them with + custom-compiled binaries. +- unsafe\_reset - delete the database for a service, including the + tendermint database. +- config - configure the application defined in ``service``. It also + configures the underlying tendermint service. Check + ``group_vars/all`` for options. +- stop - stop an application. Requires the ``service`` parameter set. +- status - check the status of an application. Requires the ``service`` + parameter set. +- start - start an application. Requires the ``service`` parameter set. + +Default variables +----------------- + +Default variables are documented under ``group_vars/all``. You can the +parameters there to deploy a previously created genesis.json file +(instead of dynamically creating it) or if you want to deploy custom +built binaries instead of deploying a released version. diff --git a/networks/remote/ansible/ansible.cfg b/networks/remote/ansible/ansible.cfg new file mode 100644 index 00000000..045c1ea6 --- /dev/null +++ b/networks/remote/ansible/ansible.cfg @@ -0,0 +1,4 @@ +[defaults] +retry_files_enabled = False +host_key_checking = False + diff --git a/networks/remote/ansible/assets/a_plus_t.png b/networks/remote/ansible/assets/a_plus_t.png new file mode 100644 index 0000000000000000000000000000000000000000..8f5bc5e950cb4ee31a0983f004f780aeb398c6ea GIT binary patch literal 13830 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 + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The GNU General Public License is a free, copyleft license for +software and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of +protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we +have designed this version of the GPL to prohibit the practice for those +products. If such problems arise substantially in other domains, we +stand ready to extend this provision to those domains in future versions +of the GPL, as needed to protect the freedom of users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public License. + + "Copyright" also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of an +exact copy. The resulting work is called a "modified version" of the +earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work based +on the Program. + + To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + + To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user through +a computer network, with no transfer of a copy, is not conveying. + + An interactive user interface displays "Appropriate Legal Notices" +to the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work +for making modifications to it. "Object code" means any non-source +form of a work. + + A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + + The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +"Major Component", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + + The Corresponding Source need not include anything that users +can regenerate automatically from other parts of the Corresponding +Source. + + The Corresponding Source for a work in source code form is that +same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + + You may make, run and propagate covered works that you do not +convey, without conditions so long as your license otherwise remains +in force. You may convey covered works to others for the sole purpose +of having them make modifications exclusively for you, or provide you +with facilities for running those works, provided that you comply with +the terms of this License in conveying all material for which you do +not control copyright. Those thus making or running the covered works +for you must do so exclusively on your behalf, under your direction +and control, on terms that prohibit them from making any copies of +your copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under +the conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + + When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such circumvention +is effected by exercising rights under this License with respect to +the covered work, and you disclaim any intention to limit operation or +modification of the work as a means of enforcing, against the work's +users, your or third parties' legal rights to forbid circumvention of +technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these conditions: + + a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. + + b) The work must carry prominent notices stating that it is + released under this License and any conditions added under section + 7. This requirement modifies the requirement in section 4 to + "keep intact all notices". + + c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section 7 + additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. + + d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + + A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms +of sections 4 and 5, provided that you also convey the +machine-readable Corresponding Source under the terms of this License, +in one of these ways: + + a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the + Corresponding Source from a network server at no charge. + + c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. + + d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. + + e) Convey the object code using peer-to-peer transmission, provided + you inform other peers where the object code and Corresponding + Source of the work are being offered to the general public at no + charge under subsection 6d. + + A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, family, +or household purposes, or (2) anything designed or sold for incorporation +into a dwelling. In determining whether a product is a consumer product, +doubtful cases shall be resolved in favor of coverage. For a particular +product received by a particular user, "normally used" refers to a +typical or common use of that class of product, regardless of the status +of the particular user or of the way in which the particular user +actually uses, or expects or is expected to use, the product. A product +is a consumer product regardless of whether the product has substantial +commercial, industrial or non-consumer uses, unless such uses represent +the only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to install +and execute modified versions of a covered work in that User Product from +a modified version of its Corresponding Source. The information must +suffice to ensure that the continued functioning of the modified object +code is in no case prevented or interfered with solely because +modification has been made. + + If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + + The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or updates +for a work that has been modified or installed by the recipient, or for +the User Product in which it has been modified or installed. Access to a +network may be denied when the modification itself materially and +adversely affects the operation of the network or violates the rules and +protocols for communication across the network. + + Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + + When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders of +that material) supplement the terms of this License with terms: + + a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or + + b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or + + c) Prohibiting misrepresentation of the origin of that material, or + requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or + + d) Limiting the use for publicity purposes of names of licensors or + authors of the material; or + + e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions of + it) with contractual assumptions of liability to the recipient, for + any liability that these contractual assumptions directly impose on + those licensors and authors. + + All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; +the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + + However, if you cease all violation of this License, then your +license from a particular copyright holder is reinstated (a) +provisionally, unless and until the copyright holder explicitly and +finally terminates your license, and (b) permanently, if the copyright +holder fails to notify you of the violation by some reasonable means +prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + + Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or +run a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + + An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + + You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's "contributor version". + + A contributor's "essential patent claims" are all patent claims +owned or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, "control" includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + + Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + + In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + + If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + + A patent license is "discriminatory" if it does not include within +the scope of its coverage, prohibits the exercise of, or is +conditioned on the non-exercise of one or more of the rights that are +specifically granted under this License. You may not convey a covered +work if you are a party to an arrangement with a third party that is +in the business of distributing software, under which you make payment +to the third party based on the extent of your activity of conveying +the work, and under which the third party grants, to any of the +parties who would receive the covered work from you, a discriminatory +patent license (a) in connection with copies of the covered work +conveyed by you (or copies made from those copies), or (b) primarily +for and in connection with specific products or compilations that +contain the covered work, unless you entered into that arrangement, +or that patent license was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you may +not convey it at all. For example, if you agree to terms that obligate you +to collect a royalty for further conveying from those to whom you convey +the Program, the only way you could satisfy both those terms and this +License would be to refrain entirely from conveying the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new versions of +the GNU General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + + Each version is given a distinguishing version number. If the +Program specifies that a certain numbered version of the GNU General +Public License "or any later version" applies to it, you have the +option of following the terms and conditions either of that numbered +version or of any later version published by the Free Software +Foundation. If the Program does not specify a version number of the +GNU General Public License, you may choose any version ever published +by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future +versions of the GNU General Public License can be used, that proxy's +public statement of acceptance of a version permanently authorizes you +to choose that version for the Program. + + Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY +OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM +IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF +ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE +USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF +DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF +SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +Also add information on how to contact you by electronic and paper mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, your program's commands +might be different; for a GUI interface, you would use an "about box". + + You should also get your employer (if you work as a programmer) or school, +if any, to sign a "copyright disclaimer" for the program, if necessary. +For more information on this, and how to apply and follow the GNU GPL, see +. + + The GNU General Public License does not permit incorporating your program +into proprietary programs. If your program is a subroutine library, you +may consider it more useful to permit linking proprietary applications with +the library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. But first, please read +. + diff --git a/networks/remote/ansible/inventory/digital_ocean.ini b/networks/remote/ansible/inventory/digital_ocean.ini new file mode 100644 index 00000000..b809554b --- /dev/null +++ b/networks/remote/ansible/inventory/digital_ocean.ini @@ -0,0 +1,34 @@ +# Ansible DigitalOcean external inventory script settings +# + +[digital_ocean] + +# The module needs your DigitalOcean API Token. +# It may also be specified on the command line via --api-token +# or via the environment variables DO_API_TOKEN or DO_API_KEY +# +#api_token = 123456abcdefg + + +# API calls to DigitalOcean may be slow. For this reason, we cache the results +# of an API call. Set this to the path you want cache files to be written to. +# One file will be written to this directory: +# - ansible-digital_ocean.cache +# +cache_path = /tmp + + +# The number of seconds a cache file is considered valid. After this many +# seconds, a new API call will be made, and the cache file will be updated. +# +cache_max_age = 300 + +# Use the private network IP address instead of the public when available. +# +use_private_network = False + +# Pass variables to every group, e.g.: +# +# group_variables = { 'ansible_user': 'root' } +# +group_variables = {} diff --git a/networks/remote/ansible/inventory/digital_ocean.py b/networks/remote/ansible/inventory/digital_ocean.py new file mode 100755 index 00000000..24ba6437 --- /dev/null +++ b/networks/remote/ansible/inventory/digital_ocean.py @@ -0,0 +1,471 @@ +#!/usr/bin/env python + +''' +DigitalOcean external inventory script +====================================== + +Generates Ansible inventory of DigitalOcean Droplets. + +In addition to the --list and --host options used by Ansible, there are options +for generating JSON of other DigitalOcean data. This is useful when creating +droplets. For example, --regions will return all the DigitalOcean Regions. +This information can also be easily found in the cache file, whose default +location is /tmp/ansible-digital_ocean.cache). + +The --pretty (-p) option pretty-prints the output for better human readability. + +---- +Although the cache stores all the information received from DigitalOcean, +the cache is not used for current droplet information (in --list, --host, +--all, and --droplets). This is so that accurate droplet information is always +found. You can force this script to use the cache with --force-cache. + +---- +Configuration is read from `digital_ocean.ini`, then from environment variables, +then and command-line arguments. + +Most notably, the DigitalOcean API Token must be specified. It can be specified +in the INI file or with the following environment variables: + export DO_API_TOKEN='abc123' or + export DO_API_KEY='abc123' + +Alternatively, it can be passed on the command-line with --api-token. + +If you specify DigitalOcean credentials in the INI file, a handy way to +get them into your environment (e.g., to use the digital_ocean module) +is to use the output of the --env option with export: + export $(digital_ocean.py --env) + +---- +The following groups are generated from --list: + - ID (droplet ID) + - NAME (droplet NAME) + - image_ID + - image_NAME + - distro_NAME (distribution NAME from image) + - region_NAME + - size_NAME + - status_STATUS + +For each host, the following variables are registered: + - do_backup_ids + - do_created_at + - do_disk + - do_features - list + - do_id + - do_image - object + - do_ip_address + - do_private_ip_address + - do_kernel - object + - do_locked + - do_memory + - do_name + - do_networks - object + - do_next_backup_window + - do_region - object + - do_size - object + - do_size_slug + - do_snapshot_ids - list + - do_status + - do_tags + - do_vcpus + - do_volume_ids + +----- +``` +usage: digital_ocean.py [-h] [--list] [--host HOST] [--all] + [--droplets] [--regions] [--images] [--sizes] + [--ssh-keys] [--domains] [--pretty] + [--cache-path CACHE_PATH] + [--cache-max_age CACHE_MAX_AGE] + [--force-cache] + [--refresh-cache] + [--api-token API_TOKEN] + +Produce an Ansible Inventory file based on DigitalOcean credentials + +optional arguments: + -h, --help show this help message and exit + --list List all active Droplets as Ansible inventory + (default: True) + --host HOST Get all Ansible inventory variables about a specific + Droplet + --all List all DigitalOcean information as JSON + --droplets List Droplets as JSON + --regions List Regions as JSON + --images List Images as JSON + --sizes List Sizes as JSON + --ssh-keys List SSH keys as JSON + --domains List Domains as JSON + --pretty, -p Pretty-print results + --cache-path CACHE_PATH + Path to the cache files (default: .) + --cache-max_age CACHE_MAX_AGE + Maximum age of the cached items (default: 0) + --force-cache Only use data from the cache + --refresh-cache Force refresh of cache by making API requests to + DigitalOcean (default: False - use cache files) + --api-token API_TOKEN, -a API_TOKEN + DigitalOcean API Token +``` + +''' + +# (c) 2013, Evan Wies +# +# Inspired by the EC2 inventory plugin: +# https://github.com/ansible/ansible/blob/devel/contrib/inventory/ec2.py +# +# This file is part of Ansible, +# +# Ansible is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# Ansible is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with Ansible. If not, see . + +###################################################################### + +import os +import sys +import re +import argparse +from time import time +import ConfigParser +import ast + +try: + import json +except ImportError: + import simplejson as json + +try: + from dopy.manager import DoManager +except ImportError as e: + sys.exit("failed=True msg='`dopy` library required for this script'") + + +class DigitalOceanInventory(object): + + ########################################################################### + # Main execution path + ########################################################################### + + def __init__(self): + ''' Main execution path ''' + + # DigitalOceanInventory data + self.data = {} # All DigitalOcean data + self.inventory = {} # Ansible Inventory + + # Define defaults + self.cache_path = '.' + self.cache_max_age = 0 + self.use_private_network = False + self.group_variables = {} + + # Read settings, environment variables, and CLI arguments + self.read_settings() + self.read_environment() + self.read_cli_args() + + # Verify credentials were set + if not hasattr(self, 'api_token'): + sys.stderr.write('''Could not find values for DigitalOcean api_token. +They must be specified via either ini file, command line argument (--api-token), +or environment variables (DO_API_TOKEN)\n''') + sys.exit(-1) + + # env command, show DigitalOcean credentials + if self.args.env: + print("DO_API_TOKEN=%s" % self.api_token) + sys.exit(0) + + # Manage cache + self.cache_filename = self.cache_path + "/ansible-digital_ocean.cache" + self.cache_refreshed = False + + if self.is_cache_valid(): + self.load_from_cache() + if len(self.data) == 0: + if self.args.force_cache: + sys.stderr.write('''Cache is empty and --force-cache was specified\n''') + sys.exit(-1) + + self.manager = DoManager(None, self.api_token, api_version=2) + + # Pick the json_data to print based on the CLI command + if self.args.droplets: + self.load_from_digital_ocean('droplets') + json_data = {'droplets': self.data['droplets']} + elif self.args.regions: + self.load_from_digital_ocean('regions') + json_data = {'regions': self.data['regions']} + elif self.args.images: + self.load_from_digital_ocean('images') + json_data = {'images': self.data['images']} + elif self.args.sizes: + self.load_from_digital_ocean('sizes') + json_data = {'sizes': self.data['sizes']} + elif self.args.ssh_keys: + self.load_from_digital_ocean('ssh_keys') + json_data = {'ssh_keys': self.data['ssh_keys']} + elif self.args.domains: + self.load_from_digital_ocean('domains') + json_data = {'domains': self.data['domains']} + elif self.args.all: + self.load_from_digital_ocean() + json_data = self.data + elif self.args.host: + json_data = self.load_droplet_variables_for_host() + else: # '--list' this is last to make it default + self.load_from_digital_ocean('droplets') + self.build_inventory() + json_data = self.inventory + + if self.cache_refreshed: + self.write_to_cache() + + if self.args.pretty: + print(json.dumps(json_data, sort_keys=True, indent=2)) + else: + print(json.dumps(json_data)) + # That's all she wrote... + + ########################################################################### + # Script configuration + ########################################################################### + + def read_settings(self): + ''' Reads the settings from the digital_ocean.ini file ''' + config = ConfigParser.SafeConfigParser() + config.read(os.path.dirname(os.path.realpath(__file__)) + '/digital_ocean.ini') + + # Credentials + if config.has_option('digital_ocean', 'api_token'): + self.api_token = config.get('digital_ocean', 'api_token') + + # Cache related + if config.has_option('digital_ocean', 'cache_path'): + self.cache_path = config.get('digital_ocean', 'cache_path') + if config.has_option('digital_ocean', 'cache_max_age'): + self.cache_max_age = config.getint('digital_ocean', 'cache_max_age') + + # Private IP Address + if config.has_option('digital_ocean', 'use_private_network'): + self.use_private_network = config.getboolean('digital_ocean', 'use_private_network') + + # Group variables + if config.has_option('digital_ocean', 'group_variables'): + self.group_variables = ast.literal_eval(config.get('digital_ocean', 'group_variables')) + + def read_environment(self): + ''' Reads the settings from environment variables ''' + # Setup credentials + if os.getenv("DO_API_TOKEN"): + self.api_token = os.getenv("DO_API_TOKEN") + if os.getenv("DO_API_KEY"): + self.api_token = os.getenv("DO_API_KEY") + + def read_cli_args(self): + ''' Command line argument processing ''' + parser = argparse.ArgumentParser(description='Produce an Ansible Inventory file based on DigitalOcean credentials') + + parser.add_argument('--list', action='store_true', help='List all active Droplets as Ansible inventory (default: True)') + parser.add_argument('--host', action='store', help='Get all Ansible inventory variables about a specific Droplet') + + parser.add_argument('--all', action='store_true', help='List all DigitalOcean information as JSON') + parser.add_argument('--droplets', '-d', action='store_true', help='List Droplets as JSON') + parser.add_argument('--regions', action='store_true', help='List Regions as JSON') + parser.add_argument('--images', action='store_true', help='List Images as JSON') + parser.add_argument('--sizes', action='store_true', help='List Sizes as JSON') + parser.add_argument('--ssh-keys', action='store_true', help='List SSH keys as JSON') + parser.add_argument('--domains', action='store_true', help='List Domains as JSON') + + parser.add_argument('--pretty', '-p', action='store_true', help='Pretty-print results') + + parser.add_argument('--cache-path', action='store', help='Path to the cache files (default: .)') + parser.add_argument('--cache-max_age', action='store', help='Maximum age of the cached items (default: 0)') + parser.add_argument('--force-cache', action='store_true', default=False, help='Only use data from the cache') + parser.add_argument('--refresh-cache', '-r', action='store_true', default=False, + help='Force refresh of cache by making API requests to DigitalOcean (default: False - use cache files)') + + parser.add_argument('--env', '-e', action='store_true', help='Display DO_API_TOKEN') + parser.add_argument('--api-token', '-a', action='store', help='DigitalOcean API Token') + + self.args = parser.parse_args() + + if self.args.api_token: + self.api_token = self.args.api_token + + # Make --list default if none of the other commands are specified + if (not self.args.droplets and not self.args.regions and + not self.args.images and not self.args.sizes and + not self.args.ssh_keys and not self.args.domains and + not self.args.all and not self.args.host): + self.args.list = True + + ########################################################################### + # Data Management + ########################################################################### + + def load_from_digital_ocean(self, resource=None): + '''Get JSON from DigitalOcean API''' + if self.args.force_cache and os.path.isfile(self.cache_filename): + return + # We always get fresh droplets + if self.is_cache_valid() and not (resource == 'droplets' or resource is None): + return + if self.args.refresh_cache: + resource = None + + if resource == 'droplets' or resource is None: + self.data['droplets'] = self.manager.all_active_droplets() + self.cache_refreshed = True + if resource == 'regions' or resource is None: + self.data['regions'] = self.manager.all_regions() + self.cache_refreshed = True + if resource == 'images' or resource is None: + self.data['images'] = self.manager.all_images(filter=None) + self.cache_refreshed = True + if resource == 'sizes' or resource is None: + self.data['sizes'] = self.manager.sizes() + self.cache_refreshed = True + if resource == 'ssh_keys' or resource is None: + self.data['ssh_keys'] = self.manager.all_ssh_keys() + self.cache_refreshed = True + if resource == 'domains' or resource is None: + self.data['domains'] = self.manager.all_domains() + self.cache_refreshed = True + + def build_inventory(self): + '''Build Ansible inventory of droplets''' + self.inventory = { + 'all': { + 'hosts': [], + 'vars': self.group_variables + }, + '_meta': {'hostvars': {}} + } + + # add all droplets by id and name + for droplet in self.data['droplets']: + # when using private_networking, the API reports the private one in "ip_address". + if 'private_networking' in droplet['features'] and not self.use_private_network: + for net in droplet['networks']['v4']: + if net['type'] == 'public': + dest = net['ip_address'] + else: + continue + else: + dest = droplet['ip_address'] + + self.inventory['all']['hosts'].append(dest) + + self.inventory[droplet['id']] = [dest] + self.inventory[droplet['name']] = [dest] + + # groups that are always present + for group in ('region_' + droplet['region']['slug'], + 'image_' + str(droplet['image']['id']), + 'size_' + droplet['size']['slug'], + 'distro_' + self.to_safe(droplet['image']['distribution']), + 'status_' + droplet['status']): + if group not in self.inventory: + self.inventory[group] = {'hosts': [], 'vars': {}} + self.inventory[group]['hosts'].append(dest) + + # groups that are not always present + for group in (droplet['image']['slug'], + droplet['image']['name']): + if group: + image = 'image_' + self.to_safe(group) + if image not in self.inventory: + self.inventory[image] = {'hosts': [], 'vars': {}} + self.inventory[image]['hosts'].append(dest) + + if droplet['tags']: + for tag in droplet['tags']: + if tag not in self.inventory: + self.inventory[tag] = {'hosts': [], 'vars': {}} + self.inventory[tag]['hosts'].append(dest) + + # hostvars + info = self.do_namespace(droplet) + self.inventory['_meta']['hostvars'][dest] = info + + def load_droplet_variables_for_host(self): + '''Generate a JSON response to a --host call''' + host = int(self.args.host) + droplet = self.manager.show_droplet(host) + info = self.do_namespace(droplet) + return {'droplet': info} + + ########################################################################### + # Cache Management + ########################################################################### + + def is_cache_valid(self): + ''' Determines if the cache files have expired, or if it is still valid ''' + if os.path.isfile(self.cache_filename): + mod_time = os.path.getmtime(self.cache_filename) + current_time = time() + if (mod_time + self.cache_max_age) > current_time: + return True + return False + + def load_from_cache(self): + ''' Reads the data from the cache file and assigns it to member variables as Python Objects''' + try: + cache = open(self.cache_filename, 'r') + json_data = cache.read() + cache.close() + data = json.loads(json_data) + except IOError: + data = {'data': {}, 'inventory': {}} + + self.data = data['data'] + self.inventory = data['inventory'] + + def write_to_cache(self): + ''' Writes data in JSON format to a file ''' + data = {'data': self.data, 'inventory': self.inventory} + json_data = json.dumps(data, sort_keys=True, indent=2) + + cache = open(self.cache_filename, 'w') + cache.write(json_data) + cache.close() + + ########################################################################### + # Utilities + ########################################################################### + + def push(self, my_dict, key, element): + ''' Pushed an element onto an array that may not have been defined in the dict ''' + if key in my_dict: + my_dict[key].append(element) + else: + my_dict[key] = [element] + + def to_safe(self, word): + ''' Converts 'bad' characters in a string to underscores so they can be used as Ansible groups ''' + return re.sub("[^A-Za-z0-9\-\.]", "_", word) + + def do_namespace(self, data): + ''' Returns a copy of the dictionary with all the keys put in a 'do_' namespace ''' + info = {} + for k, v in data.items(): + info['do_' + k] = v + return info + + +########################################################################### +# Run the script +DigitalOceanInventory() diff --git a/networks/remote/ansible/reconfig.yml b/networks/remote/ansible/reconfig.yml new file mode 100644 index 00000000..08603ed7 --- /dev/null +++ b/networks/remote/ansible/reconfig.yml @@ -0,0 +1,16 @@ +--- + +#Requires BINARY and CONFIGDIR variables set. + +- hosts: all + user: root + any_errors_fatal: true + gather_facts: no + vars: + - service: tendermint + roles: + - stop + - unsafe_reset + - config + - start + diff --git a/networks/remote/ansible/reset.yml b/networks/remote/ansible/reset.yml new file mode 100644 index 00000000..63b1733c --- /dev/null +++ b/networks/remote/ansible/reset.yml @@ -0,0 +1,14 @@ +--- + +- hosts: all + user: root + any_errors_fatal: true + gather_facts: no + vars: + - service: tendermint + roles: + - stop + - unsafe_reset + - start + + diff --git a/networks/remote/ansible/restart.yml b/networks/remote/ansible/restart.yml new file mode 100644 index 00000000..71d4bc66 --- /dev/null +++ b/networks/remote/ansible/restart.yml @@ -0,0 +1,12 @@ +--- + +- hosts: all + user: root + any_errors_fatal: true + gather_facts: no + vars: + - service: tendermint + roles: + - stop + - start + diff --git a/networks/remote/ansible/roles/config/tasks/main.yml b/networks/remote/ansible/roles/config/tasks/main.yml new file mode 100644 index 00000000..1568b500 --- /dev/null +++ b/networks/remote/ansible/roles/config/tasks/main.yml @@ -0,0 +1,15 @@ +--- + +- name: Copy binary + copy: + src: "{{BINARY}}" + dest: /usr/bin + mode: 0755 + +- name: Copy config + copy: + src: "{{CONFIGDIR}}/node0/" + dest: "/home/{{service}}/.{{service}}/" + owner: "{{service}}" + group: "{{service}}" + diff --git a/networks/remote/ansible/roles/install/handlers/main.yml b/networks/remote/ansible/roles/install/handlers/main.yml new file mode 100644 index 00000000..16afbb61 --- /dev/null +++ b/networks/remote/ansible/roles/install/handlers/main.yml @@ -0,0 +1,5 @@ +--- + +- name: reload services + systemd: "name={{service}} daemon_reload=yes enabled=yes" + diff --git a/networks/remote/ansible/roles/install/tasks/main.yml b/networks/remote/ansible/roles/install/tasks/main.yml new file mode 100644 index 00000000..9e5a7524 --- /dev/null +++ b/networks/remote/ansible/roles/install/tasks/main.yml @@ -0,0 +1,15 @@ +--- + +- name: Create service group + group: "name={{service}}" + +- name: Create service user + user: "name={{service}} group={{service}} home=/home/{{service}}" + +- name: Change user folder to more permissive + file: "path=/home/{{service}} mode=0755" + +- name: Create service + template: "src=systemd.service.j2 dest=/etc/systemd/system/{{service}}.service" + notify: reload services + diff --git a/networks/remote/ansible/roles/install/templates/systemd.service.j2 b/networks/remote/ansible/roles/install/templates/systemd.service.j2 new file mode 100644 index 00000000..34ba3ecf --- /dev/null +++ b/networks/remote/ansible/roles/install/templates/systemd.service.j2 @@ -0,0 +1,17 @@ +[Unit] +Description={{service}} +Requires=network-online.target +After=network-online.target + +[Service] +Restart=on-failure +User={{service}} +Group={{service}} +PermissionsStartOnly=true +ExecStart=/usr/bin/tendermint node --proxy_app=dummy +ExecReload=/bin/kill -HUP $MAINPID +KillSignal=SIGTERM + +[Install] +WantedBy=multi-user.target + diff --git a/networks/remote/ansible/roles/start/tasks/main.yml b/networks/remote/ansible/roles/start/tasks/main.yml new file mode 100644 index 00000000..6bc611c9 --- /dev/null +++ b/networks/remote/ansible/roles/start/tasks/main.yml @@ -0,0 +1,5 @@ +--- + +- name: start service + service: "name={{service}} state=started" + diff --git a/networks/remote/ansible/roles/status/tasks/main.yml b/networks/remote/ansible/roles/status/tasks/main.yml new file mode 100644 index 00000000..50170c74 --- /dev/null +++ b/networks/remote/ansible/roles/status/tasks/main.yml @@ -0,0 +1,10 @@ +--- + +- name: application service status + command: "service {{service}} status" + changed_when: false + register: status + +- name: Result + debug: var=status.stdout_lines + diff --git a/networks/remote/ansible/roles/stop/tasks/main.yml b/networks/remote/ansible/roles/stop/tasks/main.yml new file mode 100644 index 00000000..7db356f2 --- /dev/null +++ b/networks/remote/ansible/roles/stop/tasks/main.yml @@ -0,0 +1,5 @@ +--- + +- name: stop service + service: "name={{service}} state=stopped" + diff --git a/networks/remote/ansible/roles/unsafe_reset/tasks/main.yml b/networks/remote/ansible/roles/unsafe_reset/tasks/main.yml new file mode 100644 index 00000000..6c583198 --- /dev/null +++ b/networks/remote/ansible/roles/unsafe_reset/tasks/main.yml @@ -0,0 +1,3 @@ +- command: "{{service}} node unsafe_reset_all" + become_user: "{{service}}" + diff --git a/networks/remote/ansible/start.yml b/networks/remote/ansible/start.yml new file mode 100644 index 00000000..2be07dc7 --- /dev/null +++ b/networks/remote/ansible/start.yml @@ -0,0 +1,11 @@ +--- + +- hosts: all + user: root + any_errors_fatal: true + gather_facts: no + vars: + - service: tendermint + roles: + - start + diff --git a/networks/remote/ansible/status.yml b/networks/remote/ansible/status.yml new file mode 100644 index 00000000..a1721b87 --- /dev/null +++ b/networks/remote/ansible/status.yml @@ -0,0 +1,11 @@ +--- + +- hosts: all + user: root + any_errors_fatal: true + gather_facts: no + vars: + - service: tendermint + roles: + - status + diff --git a/networks/remote/ansible/stop.yml b/networks/remote/ansible/stop.yml new file mode 100644 index 00000000..abc6031d --- /dev/null +++ b/networks/remote/ansible/stop.yml @@ -0,0 +1,11 @@ +--- + +- hosts: all + user: root + any_errors_fatal: true + gather_facts: no + vars: + - service: tendermint + roles: + - stop + diff --git a/networks/remote/terraform/.gitignore b/networks/remote/terraform/.gitignore new file mode 100644 index 00000000..0cc2d499 --- /dev/null +++ b/networks/remote/terraform/.gitignore @@ -0,0 +1,4 @@ +.terraform +terraform.tfstate +terraform.tfstate.backup +terraform.tfstate.d diff --git a/networks/remote/terraform/README.rst b/networks/remote/terraform/README.rst new file mode 100644 index 00000000..243d1c14 --- /dev/null +++ b/networks/remote/terraform/README.rst @@ -0,0 +1,33 @@ +Using Terraform +=============== + +This is a `Terraform `__ configuration that sets up DigitalOcean droplets. + +Prerequisites +------------- + +- Install `HashiCorp Terraform `__ on a linux machine. +- Create a `DigitalOcean API token `__ with read and write capability. +- Create SSH keys + +Build +----- + +:: + + export DO_API_TOKEN="abcdef01234567890abcdef01234567890" + export SSH_KEY_FILE="$HOME/.ssh/id_rsa.pub" + + terraform init + terraform apply -var DO_API_TOKEN="$DO_API_TOKEN" -var SSH_KEY_FILE="$SSH_KEY_FILE" + +At the end you will get a list of IP addresses that belongs to your new droplets. + +Destroy +------- + +Run the below: + +:: + + terraform destroy diff --git a/networks/remote/terraform/cluster/main.tf b/networks/remote/terraform/cluster/main.tf new file mode 100644 index 00000000..98ab37ce --- /dev/null +++ b/networks/remote/terraform/cluster/main.tf @@ -0,0 +1,28 @@ +resource "digitalocean_tag" "cluster" { + name = "${var.name}" +} + +resource "digitalocean_ssh_key" "cluster" { + name = "${var.name}" + public_key = "${file(var.ssh_key)}" +} + +resource "digitalocean_droplet" "cluster" { + name = "${var.name}-node${count.index}" + image = "centos-7-x64" + size = "${var.instance_size}" + region = "${element(var.regions, count.index)}" + ssh_keys = ["${digitalocean_ssh_key.cluster.id}"] + count = "${var.servers}" + tags = ["${digitalocean_tag.cluster.id}"] + + lifecycle = { + prevent_destroy = false + } + + connection { + timeout = "30s" + } + +} + diff --git a/networks/remote/terraform/cluster/outputs.tf b/networks/remote/terraform/cluster/outputs.tf new file mode 100644 index 00000000..78291b6a --- /dev/null +++ b/networks/remote/terraform/cluster/outputs.tf @@ -0,0 +1,15 @@ +// The cluster name +output "name" { + value = "${var.name}" +} + +// The list of cluster instance IDs +output "instances" { + value = ["${digitalocean_droplet.cluster.*.id}"] +} + +// The list of cluster instance public IPs +output "public_ips" { + value = ["${digitalocean_droplet.cluster.*.ipv4_address}"] +} + diff --git a/networks/remote/terraform/cluster/variables.tf b/networks/remote/terraform/cluster/variables.tf new file mode 100644 index 00000000..3aa837a2 --- /dev/null +++ b/networks/remote/terraform/cluster/variables.tf @@ -0,0 +1,25 @@ +variable "name" { + description = "The cluster name, e.g cdn" +} + +variable "regions" { + description = "Regions to launch in" + type = "list" + default = ["AMS2", "FRA1", "LON1", "NYC3", "SFO2", "SGP1", "TOR1"] +} + +variable "ssh_key" { + description = "SSH key filename to copy to the nodes" + type = "string" +} + +variable "instance_size" { + description = "The instance size to use" + default = "2gb" +} + +variable "servers" { + description = "Desired instance count" + default = 4 +} + diff --git a/networks/remote/terraform/main.tf b/networks/remote/terraform/main.tf new file mode 100644 index 00000000..5618689d --- /dev/null +++ b/networks/remote/terraform/main.tf @@ -0,0 +1,37 @@ +#Terraform Configuration + +variable "DO_API_TOKEN" { + description = "DigitalOcean Access Token" +} + +variable "TESTNET_NAME" { + description = "Name of the testnet" + default = "remotenet" +} + +variable "SSH_KEY_FILE" { + description = "SSH public key file to be used on the nodes" + type = "string" +} + +variable "SERVERS" { + description = "Number of nodes in testnet" + default = "4" +} + +provider "digitalocean" { + token = "${var.DO_API_TOKEN}" +} + +module "cluster" { + source = "./cluster" + name = "${var.TESTNET_NAME}" + ssh_key = "${var.SSH_KEY_FILE}" + servers = "${var.SERVERS}" +} + + +output "public_ips" { + value = "${module.cluster.public_ips}" +} +