======================
Upgrading a Deployment
======================
Upgrading charms can be sped up using the ``--upgrade`` option given in
``deploy.py``. The upgrade option is deployment aware and only attempts to
upgrade services that are deployed. Likewise, it will not modify any services
that are not described in the deployer configuration files.

The ``--upgrade`` option is described as:

.. code-block:: none

  --upgrade {charms,code,config,all}
                   Upgrade an existing deployment. This argument allows
                   you to choose the order and number of upgrade
                   operations. ie - you could just update the charms,
                   update the configs, or update the code.


The upgrade choices allow for fine grain control over specific aspects of
a deployment.

 * **charms** - This upgrades the charms themselves, performing
   ``juju upgrade-charm --force`` for each deployed service.
 * **config** - Updates the options for the deployed services via ``juju set``.
   This includes an update of the application code (as that is part of the
   deployment configuration).
 * **code** - This is a special case of the config option tht only updates the
   deployed application code. This is to provide an efficient path for the
   common development case of iterating on application code.
 * **all** - This is a synonym for ``--upgrade charms --upgrade config``.

These options are particularly useful when combined with the lxc deployment
method described under "Upgrade" under
:doc:`using-lxc-for-local-development`

Examples
--------
Assuming the initial setup of :doc:`using-lxc-for-local-development` or
:doc:`setting-up-a-cloud-deployment` has been performed, the generic steps
where upgrade becomes useful are:

.. note::

 In all of the below examples, if only a few services were deployed, the
 ``--upgrade`` option will only upgrade the services that were already
 deployed. No new services will be deployed as part of the upgrade.

--upgrade all
^^^^^^^^^^^^^

.. code-block:: none

   1) bzr branch lp:uci-engine
   2) juju bootstrap
   3) cd uci-engine
   4) ./juju-deployer/deploy.py
      or
   4) ./juju-deployer/deploy.py test-runner  # for deploying only test-runner service
   5) <do changes in charms and code for the deployed services>
   6) ./juju-deployer/deploy.py --upgrade all


--upgrade charms
^^^^^^^^^^^^^^^^

.. code-block:: none

   1-4) <same as --upgrade all example above>
   5) <do changes to charms for the deployed services>
   6) ./juju-deployer/deploy.py --upgrade charms


--upgrade config
^^^^^^^^^^^^^^^^

.. code-block:: none

   1-4) <same as --upgrade all example above>
   5) <do changes to charm config and/or code for the deployed services>
   6) ./juju-deployer/deploy.py --upgrade config

--upgrade code
^^^^^^^^^^^^^^

.. code-block:: none

   1-4) <same as --upgrade all example above>
   5) <do changes to code for the deployed services>
   6) ./juju-deployer/deploy.py --upgrade code

Upgrading adt-run for the test runner
-------------------------------------

The test runner depends on :command:`adt-run` to run the tests.

When needed (new upstream version, bug fix) the `CI gated branch
<lp:~ci-engineering-private/autopkgtest/uci-engine>`_ needs to be updated.

Gating these updates guarantees that they can be tested before being
deployed and that hot fixes can also be deployed without requiring upstream
intervention (those fixes should be rare and upstreamed in any case).

Then, there is a `recipe
<https://code.launchpad.net/~canonical-ci-engineering/+recipe/autopkgtest-phase-0>`_
to build autopkgtest into the `phase-0 PPA
<https://launchpad.net/~canonical-ci-engineering/+archive/ci-airline-phase-0>`_.

Trigerring that recipe will build :command:`autopkgtest` for the series that
are used in the CI engine.

The last step is to update the deployed test runner workers themselves:

.. code-block:: none

  juju run --service ci-airline-tr-rabbit-worker 'apt-get update; apt-get install autopkgtest'