Setting-up-OpenStack-client-in-a-python-virtual-environment.md

+To create the virtual python environment to host the OpenStack client, the inbuilt python 'venv' or virtual environment tool will be used.
+This should be installed on any installation of python3.
+### Steps for setting up environment
+These steps are taken from the Python Packaging User Guide which can be found at https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/
+
+Go to or create a project directory you want to host the virtual environment in. Then create the virtual environment using the appropriate command.
+
+Unix/macOS
+```
+source -m venv <name of environment>
+```
+Windows
+```
+py -m venv <name of environment>
+```
+The name of the environment can be used to identify the virtual environment directory more easily. As we have created a project folder for this however for this example
+we will use the standard naming convention of naming it ".venv"
+```
+source -m venv .venv
+```
+
+Next to activate the virtual environment.
+
+Unix/macOS
+```
+source <name of environment>/bin/activate
+```
+Windows
+```
+<name of environment>\Scripts\activate
+```
+Then to confirm that you are in a python virtual environment, check the location of your python interpreter.
+
+Unix/macOS
+```
+which python
+```
+Windows
+```
+where python
+```
+On MacOS the Python installers inclue pip. On Linux it might have to be installed using the following commands.
+```
+python3 -m pip install --upgrade pip
+# Check if pip is installed (also works on macOS)
+python3 -m pip --version
+```
+Then on Windows again most installers include pip. To check if pip is up-to-date run these commands
+```
+py -m pip install --upgrade pip
+py -m pip --version
+```
+
+### Installing the Openstack-client
+From this point on all installs will be done with pip so there should be no difference between operating systems. To install the openstackclient use the following command.
+```
+pip install python-openstackclient
+```
+Then check if it is installed using.
+```
+openstack --version
+```
+This will give the version number if installed correctly. Now if you try to list the servers on the openstack cloud with `openstack server list --all` it will give an authorisation error. 
+
+To run commands on the openstack client on the cloud it needs to have the right credentials so it can verify the user. In the top right corner of the OpenStack horizon dashboard click the drop-down and they click the download for the OpenStack RC File which will download "admin-openrc.sh" or the equivalent openrc file for the relevant user. Source this file in the same directory you want to use the client in with source [path/to/file] this will prompt you to enter a password before the file is sourced which will be your relevant users login password.By entering in the correct password it will authorise you to use the client as that user.
+
+If you try running the client now it will hang for a while until producing the following exceptions when failing requests.exceptions.ConnectTimeout: HTTPConnectionPool(host='cloud.waltoninstitute.ie', port=5000): Max retries exceeded with url: /v3/auth/tokens (Caused by ConnectTimeoutError(<urllib3.connection.HTTPConnection object at 0x108df5890>, 'Connection to cloud.waltoninstitute.ie timed out. (connect timeout=None)'))" and "keystoneauth1.exceptions.connection.ConnectTimeout: Request to http://cloud.waltoninstitute.ie:5000/v3/auth/tokens timed out". These exceptions are due to the client not being able to resolve the url of the controller as there has not been a route set up for it in the hosts file for a DNS entry. This is why it says it is something like "Failed to discover available identity versions when contacting http://cloud.waltoninstitute.ie:5000/v3/. Attempting to parse version from URL.
+Request to http://cloud.waltoninstitute.ie:5000/v3/auth/tokens timed out". To resolve this issue we need to add an entry to the hosts file to pint to the right ip for in this case pointing to cloud.waltoninstitute.ie. The entry in the hosts file `'/etc/hosts'` for Unix/macOS
+and `C:\Windows\System32\drivers\etc` for Windows would be formatted like this.
+
+`10.37.93.100    controller   cloud.waltoninstitute.ie`.
+
+In this case the DNS entry is pointing to the OpenStack controller. This is because the client has the ability to perform CRUD operations on the OpenStack cloud therefore needs access to the controller to perform these operations even if a user does not have permissions to utilize all functions.
+
+Finally with this set up it should be possible to contact the OpenStack controller and use the SDK. To test this run a command to list things on the OpenStack cloud such as servers using the following command.
+```
+openstack server list --all
+```
+If this runs successfully and an output is visible then your configuration is set up correctly.