Add ansible provisioning (#122)

* first ansible skeleton * first commit of ansible installation of vulnwhisperer outside docker * first ansible skeleton * first commit of ansible installation of vulnwhisperer outside docker * refactor the ansible role a bit * update readme, add fail validation step to provision.yml and fix typo when calling a logging funciton
2018-11-14 10:14:12 +01:00
parent a8671a7303
commit 3a09f60543
95 changed files with 4459 additions and 1 deletions
--- a/ansible/README.md
+++ b/ansible/README.md
@ -0,0 +1,65 @@
+# Ansible deployment
+
+The code can also be deployed using [Ansible](https://www.ansible.com/) with a playbook and a role.
+
+## Code organization
+
+This ansible configuration is reasonably standard and lives under the `ansible` directory in the main
+repository root. A brief explanation of each file follows.
+
+#### ansible.cfg
+
+Main ansible configuration file, contains some options like the remote username, where to find the roles directory and
+the inventory file name. The only variables that should ever need to be customized are the `remote_user` and `host_key_checking`
+to specify the user to use on the remote system (requires *sudo* access) and if the remote host SSH key must be validated
+before proceeding.
+
+#### hosts
+
+The `hosts` file contains the list of hosts that we want to deploy Vulnwhisperer on. There is a default `[ec2]` tag under which
+any number of hosts can be configured. Please refer to the official [inventory documentation](https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html)
+for further information.
+
+#### provision.yml
+
+The main playbook, it's usually used with the `ansible-playbook` command as follows:
+
+```
+ansible-playbook provision.yml
+```
+
+The playbook will prompt for an install option that can either be `install` or `update`. Each does what the 
+name suggests. A path to the configuration file will be requested. This choice has been made to ensure that 
+there is no coupling between the provisioning process and the configuration one, giving the user full control
+on what configuration file to use and where to have it reside on the host running the playbook.
+
+The playbook will then perform some basic sanity checking (in the `pre_tasks` section) to make sure the inputted
+variables are present and then call the roles that will actually perform the provisioning. 
+
+If you need to customize the `ELK` installation variables please refer to the role section below.
+
+#### ssh.config
+
+The SSH configuration that ansible will use to reach the remote host. The reason for this file is to
+allow the user to customize the local SSH configuration, for example to specify the SSH key to use
+to authenticate to the remote host (it can be a symbolic link) or a `ProxyCommand`.
+
+## Roles
+
+There are a number of roles in this ansible tree, they are detailed below.
+
+### Elasticsearch
+
+This roles comes from the upstream elastic ansible [repository](https://github.com/elastic/ansible-elasticsearch) and has been installed via
+the `ansible-galaxy` tool. Please refer to the [official documentation](https://galaxy.ansible.com/) for more information.
+The various configuration options for this role can be specified in the `provision.yml` playbook directly by editing the list of 
+variables or can be passed from the command line. Please refer to the upstream role documentation for more information.
+
+*Note* vulnwhisperer at the time of writing only supports Elasticsearch version 5.x
+
+### Vulnwhisperer
+
+This is the main role that configures the vulnwhisperer software. It creates a number of directories in which it clones
+the repository from mainline, creates a Python [virtualenv](https://virtualenv.pypa.io/en/latest/) virtualenv in which
+it installs all the required dependencies and Vulnwhisperer itself. The role supports two tags, `install` and `update` that
+do exactly what the name suggests.