From 2371646868298d047a5c92eee9e29edc22d73ece Mon Sep 17 00:00:00 2001 From: Edoardo Putti Date: Sat, 8 Apr 2017 17:54:42 +0200 Subject: [PATCH] update documentation --- doc/source/index.rst | 1 + doc/source/lxc_guest.rst | 11 +++++-- doc/source/prepare_host.rst | 18 ++++++++++++ doc/source/reverse_proxy.rst | 56 ++++++++++++++++++++++++++++++++++++ 4 files changed, 84 insertions(+), 2 deletions(-) create mode 100644 doc/source/prepare_host.rst create mode 100644 doc/source/reverse_proxy.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 4aa241b..bee0e3a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -13,6 +13,7 @@ Welcome to lilik_playbook's documentation! quickstart prepare_host lxc_guest + reverse_proxy Indices and tables diff --git a/doc/source/lxc_guest.rst b/doc/source/lxc_guest.rst index d8487b2..5a0557c 100644 --- a/doc/source/lxc_guest.rst +++ b/doc/source/lxc_guest.rst @@ -3,14 +3,21 @@ lxc_guest ========= -This role provides the building blocks to create a virtual machine using lxc containers on a phisical server:: +This role provides the building blocks to create a virtual machine using lxc containers on a phisical server + +Usage +----- + +.. code-block:: yaml - hosts: phisical_host roles: - role: lxc_guest vm_name: virtual_machine_name -Additional parameter can be specified, the defaults are documented into the `lxc_guest` default folder:: + Additional parameter can be specified, the defaults are documented into the `lxc_guest` default folder + +.. code-block:: yaml - hosts: phisical_host roles: diff --git a/doc/source/prepare_host.rst b/doc/source/prepare_host.rst new file mode 100644 index 0000000..d3db8e5 --- /dev/null +++ b/doc/source/prepare_host.rst @@ -0,0 +1,18 @@ +.. + +`prepare_host.yaml` +============ + +This playbook provides the necessary setup for a phisical server to become a server in the lilik architecture. + +This is not a role as the requirements for this step are very simple and not sophisticated. + +The configuration of the phisical server touches the following features. + +- Installation of the lxc binaries, python bindings and network bridge utilities. +- Installation of the vlan module +- Configuration of bridge network with vlans for management and virtual machine segregation +- Installation of packages required by humans such as `htop` and `vim`- Configuration to use user ssh certificates as credentials + +The only variables that are specified in here are the vlans ids, `9` for the management vlan and `13` for the virtual machine vlan. + diff --git a/doc/source/reverse_proxy.rst b/doc/source/reverse_proxy.rst new file mode 100644 index 0000000..d2bee4b --- /dev/null +++ b/doc/source/reverse_proxy.rst @@ -0,0 +1,56 @@ +.. highlight:: yaml + +reverse_proxy +============= + +This role provides the mean of exposing a machine to the web (http and https), it is currently bound to the *reverse_proxy* host but it will be extended to be available to other as well. + +Usage +----- + +To expose the web services to the internet (http and https) for the resource pippo (a machine or a group) add the role **reverse_proxy** to the playbook. + +This will first connect to the `pippo` hosts, execute the `role1` and then connect to the `reverse_proxy` host to add the proxy rules for `pippo`. + +.. code-block:: yaml + + - hosts: pippo + roles: + - role: role1 + - role: reverse_proxy + +By default the domain exposed is created from the resource name, i.e. `pippo.lilik.it` but this can be changed by setting the `hostname` variable for the role `reverse_proxy`. + +.. code-block:: yaml + + - hosts: pippo + roles: + - role: role1 + - role: reverse_proxy + hostname: pluto + +Rationale behind this role +-------------------------- + +We have choosen to use **nginx** as our reverse proxy and because of the number of targets this can't be accomplished using a unique configuration file for nginx as it would need to know every rule every time it's configuration changes. + +Nginx provides the featuer to load configuration files from multiple directories and then merge the into one so we have choose to use three different directories. + +.. code-block:: bash + + nginx.conf + map.conf.d/ + upstream.conf.d/ + http.conf.d/ + +`nginx.conf` is the nginx configuration file, there we specify to include the the three directories in specific directives. + +`http.conf.d` contains the files for the *http* reverse proxy directive. + +`upstream.conf.d` contains the files where we specify a map from an id to the pool of the machines associated. + +`map.conf.d` contains the files where we specify the list of domains and their mappings to a resource id. + +We have choosen to separate this relation domain <-> machine by using an id because it will be used to make fun things such as high-availability or mapping more domains to the same resource id (but in different files) without the assle of checking if the nginx configuration will be broken by our automation. + +As an example take the mapping from `ca.lilik.it` to the machine `10.150.42.x`, we can have another mapping from `certificationauthority.lilik.it` to the same machine without the hassle of checking if a upstream rule is used by some mappings when we want to deprecate `certificationauthority.lilik.it`