====== Khaleesi Guide ======

==== Overview ====
The purpose of this guide is to walk through necessary steps to install and run Khaleesi in order to control Foreman nodes and use Tempest.

Khaleesi is an Ansible framework used to run [[https://openstack.redhat.com/Main_Page | RDO]] CI.  It contains the necessary playbooks, roles, and libraries in order to control Foreman nodes and install/execute Tempest on a node.

-----

==== Prerequisites ====
You should have BMC control enabled in Foreman via IPMI.  Khaleesi will issue a REST API call to the Foreman server to reboot your nodes.  Please see the "Using Foreman to Control Hardware" section in the [[https://wiki.opnfv.org/foreman_guide |Foreman Guide]].

==== Installation ====
Khaleesi can be installed on your provisioning server.  First you need EPEL and some other packages:

<code>
sudo rpm -i http://dl.fedoraproject.org/pub/epel/7/x86_64/e/epel-release-7-5.noarch.rpm
sudo yum -y install python-pip python-virtualenv gcc git \
                    python-keystoneclient python-novaclient \
                    python-glanceclient python-neutronclient \
                    python-keystoneclient sshpass
</code>

Now clone Khaleesi where you like:

<code>git clone -b foreman https://github.com/trozet/khaleesi.git</code>

Khaleesi recommeds using a virtual environment provided by python-virtualenv.  Follow these steps to setup your virtualenv:

<code>
virtualenv khaleesi_venv
source khaleesi_venv/bin/activate
pip install ansible
cd khaleesi/tools/ksgen
python setup.py develop
cd ../..
</code>

From the above you can see that ''source khaleesi_venv/bin/activate'' will activate your virtual environment.  Simply use deactivate to exit.  Now we need to create a default Ansible config:

<code>
cat > ansible.cfg << EOF
[defaults]
host_key_checking = False
roles_path = ./roles
library = ./library:$VIRTUAL_ENV/share/ansible/
lookup_plugins = ./plugins/lookups
EOF
</code>

==== Configuration ====
Khaleesi uses a ksgen_settings.yml file for directing Khaleesi's execution.  It is a YAML file that contains variables and topology information.  This file can either be edited manually or can be autogenerated using another project called [[https://github.com/redhat-openstack/khaleesi-settings | khaleesi-settings]].

For our purposes it is easier to just modify an existing ksgen_settings file.  Please use this as a template: [[https://gist.github.com/trozet/c5bde608822d8e6b063a| ksgen_settings Intel example]].  The configuration make look like a lot at first, but you only need to modify two pieces:

=== Modify External Network ===
You will notice part of the config that looks like this:
<code yaml>
  public_allocation_end: 10.2.84.71
  skip:
    files: null
    tests: null
  public_allocation_start: 10.2.84.51
  physnet: physnet1
  use_custom_repo: false
  public_subnet_cidr: 10.2.84.0/24
  public_subnet_gateway: 10.2.84.1
</code>

Simply modify these IP addresses and subnets to match your external Public network that will provide Neutron external network access.  You can also just leave these alone and Tempest will still run while failing the external network test cases.

=== Modify Inventory ===
The second piece of the configuration you need to change is the nodes dictionary.  This configuration provides your Host inventory to ansible:

<code yaml>
nodes:
  compute:
    name: oscompute11.ci.com
    hostname: oscompute11.ci.com
    type: compute
    ansible_ssh_pass: "Op3nStack"
    admin_password: ""
    groups:
    - compute
    - foreman_nodes
    - puppet
    - rdo
    - neutron
  tempest:
    name: tempest
    hostname: tempest1.ci.com
    remote_user: ""
    type: tempest
    ansible_ssh_pass: "Op3nStack"
    admin_password: ""
    groups:
    - tempest
    - foreman_nodes
    - puppet
    - rdo
    - neutron
  controller:
    name: oscontroller1.ci.com
    hostname: oscontroller1.ci.com
    type: controller
    ansible_ssh_pass: "Op3nStack"
    admin_password: "octopus"
    groups:
    - controller
    - foreman_nodes
    - puppet
    - rdo
    - neutron

</code>

Simply replace the hostnames with the hostnames of your nodes in Foreman.  The "ansible_ssh_pass" is the ssh password to your provisioned hosts, and admin_password is the password for admin within your OpenStack context.

You also need to make sure that your provisioning server can access your your hosts via their FQDN.  Therefore it is necessary to add them to /etc/hosts:
<code>
[root@foreman-server /]# cat /etc/hosts
10.2.84.4  tempest1.ci.com tempest1
10.2.84.3  oscontroller1.ci.com oscontroller1
10.2.84.5  oscompute11.ci.com oscompute11
</code>

Note: This is also a good time to mention that you should have tempest.pp applied to your tempest host group in Foreman.  It contains a package required for Tempest to run.

==== Running Khaleesi ====
Now that you have Khaleesi installed and a configuration file, you are ready to rebuild your nodes.  To run simply execute the following inside of your Khaleesi directory:

<code>
./run.sh --use ../ksgen_settings.yml playbooks/quickstack.yml --no-logs -vv
</code>

The sequence of execution is as follows:
  - Issue a reboot and rebuild to Foreman nodes given in your configuration
  - Wait for Foreman to finish installing CentOS7 on your nodes
  - Wait for puppet to check in and OPNFV puppet to install OPNFV target system
  - Install and Configure the Tempest node
  - Execute Tempest

==== Checking Tempest Results ====
Assuming everything executed you will get a "nosetests.xml" file in your Khaleesi/playbooks directory.  This contains all of your Tempest test case results.

The first line will give you the overall execution summary, followed by individual results:
<code xml>
<testsuite errors="0" failures="179" name="" tests="2141" time="880.284">
<testcase classname="" name="setUpClass (tempest.api.compute.flavors.test_flavors.FlavorsV3Test)" time="0.000">
<skipped>FlavorsV3Test skipped as nova v3 api is not available</skipped>
</testcase>
<testcase classname="tempest.api.compute.admin.test_quotas.QuotasAdminTestJSON" name="test_get_updated_quotas[gate]" time="0.394"/>
</code>

As you can see from the above, a skipped or failed test case will contain that XML tag inside of the testcase tag.  If a test case passed it will smiply show up as you see in the 3rd entry with no subtag.