|
| 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 | +This guide provides some general information and considerations around upgrading a Deis cluster. |
| 11 | +Additional tooling around upgrading Deis is planned for a future Deis release |
| 12 | +(tracked in `#710`_). The upgrade strategies outlined below |
| 13 | +reflect the current state of the Deis platform - they are certainly not ideal, and significant work |
| 14 | +is planned to make upgrading Deis much less painful for future releases. |
| 15 | + |
| 16 | +The current recommended upgrade paths for Deis are either to provision a new cluster and cut over |
| 17 | +DNS to point to new application endpoints, or to perform an in-place upgrade of Deis components. |
| 18 | + |
| 19 | +Deploying a New Cluster |
| 20 | +----------------------- |
| 21 | + |
| 22 | +This upgrade method provisions a new cluster running in parallel to the old one. Applications are |
| 23 | +pushed to this new cluster one-by-one, and DNS records are updated to cut over traffic on a |
| 24 | +per-application basis. This results in a no-downtime controlled upgrade, but has the caveat that no |
| 25 | +data from the old cluster (users, releases, etc.) is retained. Future upgrade tooling will have |
| 26 | +facilities to export and import cluster data. |
| 27 | + |
| 28 | +Provision servers |
| 29 | +^^^^^^^^^^^^^^^^^ |
| 30 | +A new cluster can be provisioned by following the release's README or contrib/ directory tooling. |
| 31 | +Be sure to use a new etcd discovery URL so that the new cluster doesn't interfere with the running one. |
| 32 | + |
| 33 | +Upgrade Deis client and fleetctl |
| 34 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 35 | +The latest Deis client should be installed. You can either use pip or download a pre-compiled binary. |
| 36 | +See the release notes or the release's README for a link to the latest client. |
| 37 | + |
| 38 | +Also, new Deis releases frequently require upgrades to the fleetctl client. Again, see the release |
| 39 | +notes for the new release to see if an upgrade is necessary. |
| 40 | + |
| 41 | +Before upgrading the client, we should logout with the old client: |
| 42 | + |
| 43 | +.. code-block:: console |
| 44 | +
|
| 45 | + dev $ deis logout |
| 46 | +
|
| 47 | +Register and login to the new controller |
| 48 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 49 | +Register an account on the new controller and login. |
| 50 | + |
| 51 | +.. code-block:: console |
| 52 | +
|
| 53 | + dev $ deis register http://deis.newcluster.example.org |
| 54 | + dev $ deis login http://deis.newcluster.example.org |
| 55 | + dev $ deis keys:add |
| 56 | +
|
| 57 | +Push apps to the new cluster |
| 58 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 59 | +Each application will need to be deployed to the new cluster. You can use ``deis apps:list`` to help |
| 60 | +enumerate all existing applications. |
| 61 | + |
| 62 | +For each existing application, rename the existing deis remote, and create a new application. |
| 63 | + |
| 64 | +.. code-block:: console |
| 65 | +
|
| 66 | + dev $ git remote rename deis deis-old |
| 67 | + dev $ deis create |
| 68 | + dev $ git push deis master |
| 69 | +
|
| 70 | +Note that you'll also need to ``deis config:set`` for each environment variable an application |
| 71 | +references - use ``deis config:list`` to enumerate these. |
| 72 | + |
| 73 | +Now each application is running on the new cluster, but they are still running (and serving traffic) |
| 74 | +on the old cluster. |
| 75 | + |
| 76 | +We need to tell Deis that this application can be accessed by its old name: |
| 77 | + |
| 78 | +.. code-block:: console |
| 79 | +
|
| 80 | + dev $ deis domains:add oldappname.oldcluster.example.org |
| 81 | +
|
| 82 | +Test applications |
| 83 | +^^^^^^^^^^^^^^^^^ |
| 84 | +Test to make sure applications work as expected on the new Deis cluster. |
| 85 | + |
| 86 | +Update DNS records |
| 87 | +^^^^^^^^^^^^^^^^^^ |
| 88 | +For each application, create CNAME records to point the old application names to the new. Note that |
| 89 | +once these records propagate, the new cluster is serving live traffic. You can perform cutover on a |
| 90 | +per-application basis and slowly retire the old cluster. |
| 91 | + |
| 92 | +If an application is named 'happy-bandit' on the old Deis cluster and 'jumping-cuddlefish' on the |
| 93 | +new cluster, you would create a DNS record that looks like the following: |
| 94 | + |
| 95 | +.. code-block:: console |
| 96 | +
|
| 97 | + happy-bandit.oldcluster.example.org. CNAME jumping-cuddlefish.newcluster.example.org |
| 98 | +
|
| 99 | +Retire the old cluster |
| 100 | +^^^^^^^^^^^^^^^^^^^^^^ |
| 101 | +Once all applications have been validated, the old cluster can be retired. |
| 102 | + |
| 103 | +In-place upgrade |
| 104 | +---------------- |
| 105 | + |
| 106 | +This upgrade method involves shutting down the existing cluster, upgrading Deis components, and then |
| 107 | +restarting them. It has the benefit of preserving existing data, but has the caveat that it results |
| 108 | +in cluster downtime. |
| 109 | + |
| 110 | +Stop components |
| 111 | +^^^^^^^^^^^^^^^ |
| 112 | +The Makefile has the ability to stop all Deis copmonents. Once this occurs, all apps will |
| 113 | +be unresponsive. |
| 114 | + |
| 115 | +.. code-block:: console |
| 116 | +
|
| 117 | + dev $ make stop |
| 118 | +
|
| 119 | +You can ``make status`` to ensure that all services are stopped. |
| 120 | + |
| 121 | +Export data containers |
| 122 | +^^^^^^^^^^^^^^^^^^^^^^ |
| 123 | +Two Deis components, builder and database, run separate containers to store their stateful data. |
| 124 | +We export these as tarballs before upgrading the containers. |
| 125 | + |
| 126 | +.. code-block:: console |
| 127 | +
|
| 128 | + dev $ fleetctl ssh deis-database.service |
| 129 | + coreos $ sudo docker export deis-database-data > /home/coreos/deis-database-data-backup.tar |
| 130 | +
|
| 131 | +.. code-block:: console |
| 132 | +
|
| 133 | + dev $ fleetctl ssh deis-builder.service |
| 134 | + coreos $ sudo docker export deis-builder-data > /home/coreos/deis-builder-data-backup.tar |
| 135 | +
|
| 136 | +Upgrade Deis client and fleetctl |
| 137 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 138 | +The latest Deis client should be installed. You can either use pip or download a pre-compiled binary. |
| 139 | +See the release notes or the release's README for a link to the latest client. |
| 140 | + |
| 141 | +Also, new Deis releases frequently require upgrades to the fleetctl client. Again, see the |
| 142 | +release notes for the new release to see if an upgrade is necessary. |
| 143 | + |
| 144 | +Upgrade components |
| 145 | +^^^^^^^^^^^^^^^^^^ |
| 146 | +Now we instruct all servers to download the release's Docker containers. This will take some time... |
| 147 | + |
| 148 | +.. code-block:: console |
| 149 | +
|
| 150 | + dev $ make pull |
| 151 | +
|
| 152 | +Import data containers |
| 153 | +^^^^^^^^^^^^^^^^^^^^^^ |
| 154 | +We need to reimport the saved data containers we exported earlier. |
| 155 | + |
| 156 | +.. code-block:: console |
| 157 | +
|
| 158 | + dev $ fleetctl ssh deis-database.service |
| 159 | + coreos $ cat /home/coreos/deis-database-data-backup.tar | sudo docker import - deis-database-data |
| 160 | +
|
| 161 | +.. code-block:: console |
| 162 | +
|
| 163 | + dev $ fleetctl ssh deis-builder.service |
| 164 | + coreos $ cat /home/coreos/deis-builder-data-backup.tar | sudo docker import - deis-builder-data |
| 165 | +
|
| 166 | +Start the cluster |
| 167 | +^^^^^^^^^^^^^^^^^ |
| 168 | +Again, the Makefile takes care of this logic for us: |
| 169 | + |
| 170 | +.. code-block:: console |
| 171 | +
|
| 172 | + dev $ make run |
| 173 | +
|
| 174 | +Test |
| 175 | +^^^^ |
| 176 | +Ensure all applications function as expected. |
| 177 | + |
| 178 | +.. _`#710`: https://github.com/deis/deis/issues/710 |
0 commit comments