ceph/doc/cephadm/upgrade.rst

   1 ==============
   2 Upgrading Ceph
   3 ==============
   4
   5 Cephadm can safely upgrade Ceph from one bugfix release to the next.  For
   6 example, you can upgrade from v15.2.0 (the first Octopus release) to the next
   7 point release, v15.2.1.
   8
   9 The automated upgrade process follows Ceph best practices.  For example:
  10
  11 * The upgrade order starts with managers, monitors, then other daemons.
  12 * Each daemon is restarted only after Ceph indicates that the cluster
  13   will remain available.
  14
  15 .. note::
  16
  17    The Ceph cluster health status is likely to switch to
  18    ``HEALTH_WARNING`` during the upgrade.
  19
  20 .. note::
  21
  22    In case a host of the cluster is offline, the upgrade is paused.
  23
  24
  25 Starting the upgrade
  26 ====================
  27
  28 Before you use cephadm to upgrade Ceph, verify that all hosts are currently online and that your cluster is healthy by running the following command:
  29
  30 .. prompt:: bash #
  31
  32    ceph -s
  33
  34 To upgrade (or downgrade) to a specific release, run the following command:
  35
  36 .. prompt:: bash #
  37
  38   ceph orch upgrade start --ceph-version <version>
  39
  40 For example, to upgrade to v15.2.1, run the following command:
  41
  42 .. prompt:: bash #
  43
  44   ceph orch upgrade start --ceph-version 15.2.1
  45
  46
  47 Monitoring the upgrade
  48 ======================
  49
  50 Determine (1) whether an upgrade is in progress and (2) which version the
  51 cluster is upgrading to by running the following command:
  52
  53 .. prompt:: bash #
  54
  55   ceph orch upgrade status
  56
  57 Watching the progress bar during a Ceph upgrade
  58 -----------------------------------------------
  59
  60 During the upgrade, a progress bar is visible in the ceph status output. It
  61 looks like this:
  62
  63 .. code-block:: console
  64
  65   # ceph -s
  66
  67   [...]
  68     progress:
  69       Upgrade to docker.io/ceph/ceph:v15.2.1 (00h 20m 12s)
  70         [=======.....................] (time remaining: 01h 43m 31s)
  71
  72 Watching the cephadm log during an upgrade
  73 ------------------------------------------
  74
  75 Watch the cephadm log by running the following command:
  76
  77 .. prompt:: bash #
  78
  79   ceph -W cephadm
  80
  81
  82 Canceling an upgrade
  83 ====================
  84
  85 You can stop the upgrade process at any time by running the following command:
  86
  87 .. prompt:: bash #
  88
  89   ceph orch upgrade stop
  90
  91
  92 Potential problems
  93 ==================
  94
  95 There are a few health alerts that can arise during the upgrade process.
  96
  97 UPGRADE_NO_STANDBY_MGR
  98 ----------------------
  99
 100 This alert (``UPGRADE_NO_STANDBY_MGR``) means that Ceph does not detect an
 101 active standby manager daemon. In order to proceed with the upgrade, Ceph
 102 requires an active standby manager daemon (which you can think of in this
 103 context as "a second manager").
 104
 105 You can ensure that Cephadm is configured to run 2 (or more) managers by
 106 running the following command:
 107
 108 .. prompt:: bash #
 109
 110   ceph orch apply mgr 2  # or more
 111
 112 You can check the status of existing mgr daemons by running the following
 113 command:
 114
 115 .. prompt:: bash #
 116
 117   ceph orch ps --daemon-type mgr
 118
 119 If an existing mgr daemon has stopped, you can try to restart it by running the
 120 following command:
 121
 122 .. prompt:: bash #
 123
 124   ceph orch daemon restart <name>
 125
 126 UPGRADE_FAILED_PULL
 127 -------------------
 128
 129 This alert (``UPGRADE_FAILED_PULL``) means that Ceph was unable to pull the
 130 container image for the target version. This can happen if you specify a
 131 version or container image that does not exist (e.g. "1.2.3"), or if the
 132 container registry can not be reached by one or more hosts in the cluster.
 133
 134 To cancel the existing upgrade and to specify a different target version, run
 135 the following commands:
 136
 137 .. prompt:: bash #
 138
 139   ceph orch upgrade stop
 140   ceph orch upgrade start --ceph-version <version>
 141
 142
 143 Using customized container images
 144 =================================
 145
 146 For most users, upgrading requires nothing more complicated than specifying the
 147 Ceph version number to upgrade to.  In such cases, cephadm locates the specific
 148 Ceph container image to use by combining the ``container_image_base``
 149 configuration option (default: ``docker.io/ceph/ceph``) with a tag of
 150 ``vX.Y.Z``.
 151
 152 But it is possible to upgrade to an arbitrary container image, if that's what
 153 you need. For example, the following command upgrades to a development build:
 154
 155 .. prompt:: bash #
 156
 157   ceph orch upgrade start --image quay.io/ceph-ci/ceph:recent-git-branch-name
 158
 159 For more information about available container images, see :ref:`containers`.