diff --git a/doc/source/architecture.rst b/doc/source/architecture.rst index 82b21f5..9f936e8 100644 --- a/doc/source/architecture.rst +++ b/doc/source/architecture.rst @@ -26,12 +26,12 @@ Tenks has a concept of 'physical network' which currently must map one-to-one to the hardware networks plugged into the hypervisors. It requires device mappings to be specified on a hypervisor for each physical network that is to be connected to nodes on that hypervisor. This device can be an interface, a -Linux bridge or an Open vSwitch bridge. For each physical network that is give +Linux bridge or an Open vSwitch bridge. For each physical network that is given a mapping on a hypervisor, a new Tenks-managed Open vSwitch bridge is created. If the device mapped to this physnet is an interface, it is plugged directly into the new bridge. If the device is an existing Linux bridge, a veth pair is created to connect the existing bridge to the new bridge. If the device is an -existing Open vSwitch bridge, an Open vSwitch patch port is created to link th +existing Open vSwitch bridge, an Open vSwitch patch port is created to link the two bridges. A new veth pair is created for each physical network that each node on each diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index e65636c..b1f9804 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration.rst @@ -23,11 +23,11 @@ setup on the host where the ``ansible-playbook`` command is executed Variable Configuration ---------------------- -An override file should be created to configure Tenks. Any variables specified -in this file will take precedence over their default settings in Tenks. This -will allow you to set options as necessary for your setup, without needing to -directly modify Tenks' variable files. An example override file can be found -in ``ansible/override.yml.example``. +A variable override file should be created to configure Tenks. Any variables +specified in this file will take precedence over their default settings in +Tenks. This will allow you to set options as necessary for your setup, without +needing to directly modify Tenks' variable files. An example override file can +be found in ``ansible/override.yml.example``. Most of the configuration you will need to do relates to variables defined in ``ansible/host_vars/localhost``. You can set your own values for these in your @@ -37,14 +37,14 @@ define the types of node you'd like to be able to manage as a dict in Format and guidance for available options will be found within the variable file. -Broadly, most variables in ``ansible/group_vars/*`` have sensible defaults which -may be left as-is unless you have a particular need to configure them. A +Broadly, most variables in ``ansible/group_vars/*`` have sensible defaults +which may be left as-is unless you have a particular need to configure them. A notable exception to this is the variable ``physnet_mappings`` in ``ansible/group_vars/hypervisors``, which should map physical network names to the device to use for that network: this can be a network interface, or an existing OVS or Linux bridge. If these mappings are the same for all hosts in -your ``hypervisors`` group, you may set a single dict ``physnet_mappings`` in your -overrides file, and this will be used for all hosts. If different mappings are -required for different hosts, you will need to individually specify them: for a -host with hostname *myhost*, set ``physnet_mappings`` within the file -``ansible/host_vars/myhost``. +your ``hypervisors`` group, you may set a single dict ``physnet_mappings`` in +your overrides file, and this will be used for all hosts. If different mappings +are required for different hosts, you will need to individually specify them in +an inventory host_vars file: for a host with hostname *myhost*, set +``physnet_mappings`` within the file ``ansible/inventory/host_vars/myhost``. diff --git a/doc/source/index.rst b/doc/source/index.rst index eff830a..8d7a800 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -12,9 +12,9 @@ testing purposes. .. toctree:: :maxdepth: 2 - architecture configuration - development install - limitations run + architecture + development + limitations diff --git a/doc/source/install.rst b/doc/source/install.rst index 200c86e..07f904f 100644 --- a/doc/source/install.rst +++ b/doc/source/install.rst @@ -1,8 +1,48 @@ +.. _installation: + Installation -=============== +============ + +Pre-Requisites +-------------- + +Currently, Tenks supports CentOS 7.5. + +To avoid conflicts with Python packages installed by the system package manager +it is recommended to install Tenks in a virtualenv. Ensure that the +``virtualenv`` Python module is available. For cloning and working with the +Tenks source code repository, Git is required. These pre-requisites can be +installed with a command such as:: + + $ yum install --assumeyes python-virtualenv git + +Tenks Installation +------------------ + +Create a virtualenv for Tenks. For example:: + + $ virtualenv tenks + +Activate the virtualenv and update pip:: + + $ source tenks/bin/activate + (tenks) $ pip install --upgrade pip + +Obtain the Tenks source code and change into the directory. For example:: + + (tenks) $ git clone https://github.com/stackhpc/tenks.git + (tenks) $ cd tenks Tenks has dependencies on Ansible roles that are hosted by Ansible Galaxy. -Given that your virtualenv of choice is active and Ansible (>=2.6) is -installed inside it, Tenks' role dependencies can be installed by -``ansible-galaxy install --role-file=requirements.yml ---roles-path=ansible/roles/``. +These can be installed by a command such as:: + + (tenks) $ ansible-galaxy install --role-file=requirements.yml --roles-path=ansible/roles/ + +Install Tenks and its requirements using the source code checkout:: + + (tenks) $ pip install . + +If you now wish to run Tenks (see :ref:`run`), keep your virtualenv active. If +not, deactivate it:: + + (tenks) $ deactivate diff --git a/doc/source/run.rst b/doc/source/run.rst index fac0fd0..1c86cbd 100644 --- a/doc/source/run.rst +++ b/doc/source/run.rst @@ -1,3 +1,5 @@ +.. _run: + Running Tenks ============= @@ -16,21 +18,29 @@ possible values it can take are: Execution --------- -Currently, Tenks does not have a CLI or wrapper. Deployment can be run by -calling ``ansible-playbook --inventory ansible/inventory ansible/deploy.yml ---extra-vars=@override.yml``, where ``override.yml`` is the path to your -override file. +Currently, Tenks does not have a CLI or wrapper. Before running any of the +``ansible-playbook`` commands in this section, ensure that your Tenks +virtualenv is active (see :ref:`installation`). In this section, +``override.yml`` represents the path to your override file (see +:ref:`configuration`). + +The ``deploy.yml`` playbook will run deployment from start to finish. This can +be run by calling:: + + (tenks) $ ansible-playbook --inventory ansible/inventory ansible/deploy.yml --extra-vars=@override.yml -The ``deploy.yml`` playbook will run deployment from start to finish; ``teardown.yml`` is ``deploy.yml``'s "mirror image" to tear down a cluster. -These playbooks automatically set ``cmd`` appropriately, and they contain -various constituent playbooks which perform different parts of the deployment. -An individual section of Tenks can be run separately by substituting -``ansible/deploy.yml`` in the command above with the path to the playbook(s) -you want to run. The current playbooks can be seen in the Ansible structure -diagram in :ref:`architecture`. Bear in mind that you will have to set -``cmd`` in your override file if you are running any of the sub-playbooks -individually. +This can be run by calling:: + + (tenks) $ ansible-playbook --inventory ansible/inventory ansible/teardown.yml --extra-vars=@override.yml + +``deploy.yml`` and ``teardown.yml`` automatically set ``cmd`` appropriately, +and they contain various constituent playbooks which perform different parts of +the deployment. An individual section of Tenks can be run separately by +substituting the path to the playbook(s) you want to run into one of the +commands above. The current playbooks can be seen in the Ansible structure +diagram in :ref:`architecture`. Bear in mind that you will have to set ``cmd`` +in your override file if you are running any of the sub-playbooks individually. Once a cluster has been deployed, it can be reconfigured by modifying the Tenks configuration and rerunning ``deploy.yml``. Node specs can be changed