github.com/misfo/deis@v1.0.1-0.20141111224634-e0eee0392b8a/docs/managing_deis/upgrading-deis.rst (about)

     1  :title: Upgrading Deis
     2  :description: Guide to upgrading Deis to a new release.
     3  
     4  
     5  .. _upgrading-deis:
     6  
     7  Upgrading Deis
     8  ==============
     9  
    10  There are currently two strategies for upgrading a Deis cluster:
    11  
    12  * In-place Upgrade (recommended)
    13  * Migration Upgrade
    14  
    15  Before attempting an upgrade, it is strongly recommended to :ref:`backup your data <backing_up_data>`.
    16  
    17  In-place Upgrade
    18  ----------------
    19  
    20  An in-place upgrade swaps out platform containers for newer versions on the same set of hosts,
    21  leaving your applications and platform data intact.  This is the easiest and least disruptive upgrade strategy.
    22  The general approach is to use ``deisctl`` to uninstall all platform components, update the platform version
    23  and then reinstall platform components.
    24  
    25  .. important::
    26  
    27      Always use a version of ``deisctl`` that matches the Deis release.
    28      Verify this with ``deisctl --version``.
    29  
    30  Use the following steps to perform an in-place upgrade of your Deis cluster.
    31  
    32  .. code-block:: console
    33  
    34      $ deisctl stop platform && deisctl uninstall platform
    35      $ deisctl config platform set version=v1.0.0
    36      $ deisctl install platform
    37      $ deisctl start platform
    38  
    39  .. attention::
    40  
    41      In-place upgrades incur approximately 10-30 minutes of downtime for deployed applications, the router mesh
    42      and the platform control plane.  Please plan your maintenance windows accordingly.
    43  
    44  
    45  Migration Upgrade
    46  -----------------
    47  
    48  This upgrade method provisions a new cluster running in parallel to the old one. Applications are
    49  migrated to this new cluster one-by-one, and DNS records are updated to cut over traffic on a
    50  per-application basis. This results in a no-downtime controlled upgrade, but has the caveat that no
    51  data from the old cluster (users, releases, etc.) is retained. Future ``deisctl`` tooling will have
    52  facilities to export and import this platform data.
    53  
    54  .. note::
    55  
    56      Migration upgrades are useful for moving Deis to a new set of hosts,
    57      but should otherwise be avoided due to the amount of manual work involved.
    58  
    59  .. important::
    60  
    61      In order to migrate applications, your new cluster must have network access
    62      to the registry component on the old cluster
    63  
    64  Enumerate Existing Applications
    65  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    66  Each application will need to be deployed to the new cluster manually.
    67  Log in to the existing cluster as an admin user and use the ``deis`` client to
    68  gather information about your deployed applications.
    69  
    70  List all applications with:
    71  
    72  .. code-block:: console
    73  
    74      $ deis apps:list
    75  
    76  Gather each application's version with:
    77  
    78  .. code-block:: console
    79  
    80      $ deis apps:info -a <app-name>
    81  
    82  Provision servers
    83  ^^^^^^^^^^^^^^^^^
    84  Follow the Deis documentation to provision a new cluster using your desired target release.
    85  Be sure to use a new etcd discovery URL so that the new cluster doesn't interfere with the running one.
    86  
    87  Upgrade Deis clients
    88  ^^^^^^^^^^^^^^^^^^^^
    89  If changing versions, make sure you upgrade your ``deis`` and ``deisctl`` clients
    90  to match the cluster's release.
    91  
    92  Register and login to the new controller
    93  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    94  Register an account on the new controller and login.
    95  
    96  .. code-block:: console
    97  
    98      $ deis register http://deis.newcluster.example.org
    99      $ deis login http://deis.newcluster.example.org
   100  
   101  Migrate applications
   102  ^^^^^^^^^^^^^^^^^^^^
   103  The ``deis pull`` command makes it easy to migrate existing applications from
   104  one cluster to another.  However, you must have network access to the existing
   105  cluster's registry component.
   106  
   107  Migrate a single application with:
   108  
   109  .. code-block:: console
   110  
   111      $ deis create <app-name>
   112      $ deis pull registry.oldcluster.example.org:5000/<app-name>:<version>
   113  
   114  This will move the application's Docker image across clusters, ensuring the application
   115  is migrated bit-for-bit with an identical build and configuration.
   116  
   117  Now each application is running on the new cluster, but they are still running (and serving traffic)
   118  on the old cluster.  Use ``deis domains:add`` to tell Deis that this application can be accessed
   119  by its old name:
   120  
   121  .. code-block:: console
   122  
   123      $ deis domains:add oldappname.oldcluster.example.org
   124  
   125  Repeat for each application.
   126  
   127  Test applications
   128  ^^^^^^^^^^^^^^^^^
   129  Test to make sure applications work as expected on the new Deis cluster.
   130  
   131  Update DNS records
   132  ^^^^^^^^^^^^^^^^^^
   133  For each application, create CNAME records to point the old application names to the new. Note that
   134  once these records propagate, the new cluster is serving live traffic. You can perform cutover on a
   135  per-application basis and slowly retire the old cluster.
   136  
   137  If an application is named 'happy-bandit' on the old Deis cluster and 'jumping-cuddlefish' on the
   138  new cluster, you would create a DNS record that looks like the following:
   139  
   140  .. code-block:: console
   141  
   142      happy-bandit.oldcluster.example.org.        CNAME       jumping-cuddlefish.newcluster.example.org
   143  
   144  Retire the old cluster
   145  ^^^^^^^^^^^^^^^^^^^^^^
   146  Once all applications have been validated, the old cluster can be retired.
   147  
   148  
   149  Upgrading CoreOS
   150  ----------------
   151  
   152  Sometimes you may need to update CoreOS manually in order to get Deis to work. For example, Deis
   153  requires a minimum of CoreOS v472.0.0. To update CoreOS, run the following
   154  commands:
   155  
   156  .. code-block:: console
   157  
   158      $ ssh core@<server ip>
   159      $ sudo su
   160      $ systemctl unmask update-engine.service
   161      $ systemctl start update-engine.service
   162      $ update_engine_client -update
   163      $ systemctl stop update-engine.service
   164      $ systemctl mask update-engine.service
   165      $ reboot
   166  
   167  You can check the CoreOS version by running the following command on the CoreOS machine:
   168  
   169  .. code-block:: console
   170  
   171      $ cat /etc/os-release
   172  
   173  Or from your local machine:
   174  
   175  .. code-block:: console
   176  
   177      $ ssh core@<server ip> 'cat /etc/os-release'