devtest
=======

(There are detailed instructions available below, the overview and
configuration sections provide background information).

Overview:
 * Define a VM that is your seed node
 * Define N VMs to pretend to be your cluster
 * Create a seed VM
 * Create an undercloud
 * Create an overcloud
 * Deploy a sample workload in the overcloud
 * Add environment variables to be included to ~/.devtestrc, e.g. http_proxy
 * Go to town testing deployments on them.
 * For troubleshooting see :doc:`troubleshooting`
 * For generic deployment information see :doc:`deploying`

This document is extracted from devtest.sh, our automated bring-up story for
CI/experimentation.

More details about the TripleO project and its goals can be found in the
:doc:`README <README>`

.. tip::

   https://wiki.openstack.org/wiki/TripleO#Notes_for_new_developers contains
   notes on setting up a development environment. It's primarily aimed at
   people who intend to become contributors for tripleo, but many of its
   notes (such as those relating to setting up local mirrors for apt and
   pypi) will probably be helpful for everyone.

.. note::

   See :ref:`tested_platforms` for an overview of which releases of which
   distros are tested in our CI system.  We suggest you read that section
   before proceeding, to make sure you're running on a platform that we have
   extensively tested.

Permissions
-----------

These scripts are designed to be run under your normal user account. The
scripts make use of sudo when elevated privileges are needed. You will
either need to run this attended, entering your password when sudo needs
it, or enable passwordless sudo for your user. Another option is to extend
the timeout of sudo sessions so that passwordless sudo will be allowed
enough time on the controlling terminal to complete the devtest run. If
there are any circumstances where running as a normal user, and not root,
fails, this is considered a critical bug.

Sudo
~~~~

In order to set the sudo session timeout higher, add this to /etc/sudoers::

    Defaults    timestamp_timeout=240 # 4 hours

This will result in 4 hour timeouts for sudo session credentials. To
reset the timeout run::

    sudo -k; sudo -v


In order to set a user to full passwordless operation add this (typically
near the end of /etc/sudoers)::

    username    ALL = NOPASSWD: ALL


Initial Checkout
----------------

#. Choose a base location to put all of the source code.

   .. note::

     exports are ephemeral - they will not survive across new shell sessions
     or reboots. If you put these export commands in ``~/.devtestrc``, you
     can simply ``source ~/.devtestrc`` to reload them. Alternatively, you
     can ``$TRIPLEO_ROOT/tripleo-incubator/scripts/write-tripleorc`` and then
     source the generated tripleorc file.

   ::

     export TRIPLEO_ROOT=~/tripleo

   .. note::

     This will be used by devtest.sh and other scripts to store the
     additional tools, images, packages, tarballs and everything else
     needed by the deployment process. The tripleo-incubator tools must
     be cloned within your ``$TRIPLEO_ROOT``.

#. Create the directory and clone tripleo-incubator within ``$TRIPLEO_ROOT``

   ::

     mkdir -p $TRIPLEO_ROOT
     cd $TRIPLEO_ROOT
     git clone https://git.openstack.org/openstack/tripleo-incubator
     cd tripleo-incubator

Optional: stable branch
-----------------------

Note that every effort is made to keep the published set of these instructions
updated for use with only the master branches of the TripleO projects. There is
**NO** guaranteed stability in master. There is also no guaranteed stable
upgrade path from release to release or from one stable branch to a later
stable branch. The stable branches are a point in time and make no
guarantee about deploying older or newer branches of OpenStack projects
correctly.

If you wish to use the stable branches, you should instead checkout and clone
the stable branch of tripleo-incubator you want, and then build the
instructions yourself. For instance, to create a local branch named
``foo`` based on the upstream branch ``stable/foo``::

     git checkout -b foo origin/stable/foo
     tox -edocs
     # View doc/build/html/devtest.html in your browser and proceed from there

Next Steps:
-----------

When run as a standalone script, devtest.sh runs the following commands
to configure the devtest environment, bootstrap a seed, deploy under and
overclouds. Many of these commands are also part of our documentation.
Readers may choose to either run the commands given here, or instead follow
the documentation for each command and walk through it step by step to see
what is going on. This choice can be made on a case by case basis - for
instance, if bootstrapping is not interesting, run that as devtest does,
then step into the undercloud setup for granular details of bringing up a
baremetal cloud.


#. See :doc:`devtest_variables` for documentation. Assuming you're still at
   the root of your checkout::

       source scripts/devtest_variables.sh

#. See :doc:`devtest_setup` for documentation.
   $CONTINUE should be set to '--trash-my-machine' to have it execute
   unattended.
   ::

        devtest_setup.sh $CONTINUE

#. See :doc:`devtest_testenv` for documentation. This step creates the
   seed VM, as well as "baremetal" VMs for the under/overclouds. Details
   of the created VMs are written to ``$TE_DATAFILE``.

   .. warning::

      You should only run this step once, the first time the environment
      is being set up. Unless you remove the VMs and need to recreate
      them, you should skip this step on subsequent runs. Running this
      script with existing VMs will result in information about the existing
      nodes being removed from ``$TE_DATAFILE``

   ::

        devtest_testenv.sh $TE_DATAFILE $NODES_ARG $NETS_ARG

#. See :doc:`devtest_ramdisk` for documentation::

        devtest_ramdisk.sh

#. See :doc:`devtest_seed` for documentation. If you are not deploying an
   undercloud, (see below) then you will want to add --all-nodes to your
   invocation of devtest_seed.sh,which will register all your nodes directly
   with the seed cloud.::

        devtest_seed.sh
        export no_proxy=${no_proxy:-},192.0.2.1
        source $TRIPLEO_ROOT/tripleo-incubator/seedrc


#. See :doc:`devtest_undercloud` for documentation. The undercloud doesn't
   have to be built - the seed is entirely capable of deploying any
   baremetal workload - but a production deployment would quite probably
   want to have a heat deployed (and thus reconfigurable) deployment
   infrastructure layer).
   If you are only building images you won't need to update your no_proxy
   line or source the undercloudrc file.

   ::

        devtest_undercloud.sh $TE_DATAFILE
        export no_proxy=$no_proxy,$(os-apply-config --type raw -m $TE_DATAFILE --key undercloud.endpointhost)
        source $TRIPLEO_ROOT/tripleo-incubator/undercloudrc

#. See :doc:`devtest_overcloud` for documentation.
   If you are only building images you won't need to update your no_proxy
   line or source the overcloudrc file.

   ::

        devtest_overcloud.sh
        export no_proxy=$no_proxy,$(os-apply-config --type raw -m $TE_DATAFILE --key overcloud.endpointhost)
        source $TRIPLEO_ROOT/tripleo-incubator/overcloudrc

#. See :doc:`devtest_end` for documentation::

        devtest_end.sh

