ceph/doc/cephadm/upgrade.rst

   1 ==============
   2 Upgrading Ceph
   3 ==============
   4
   5 Cephadm is capable of safely upgrading Ceph from one bugfix release to
   6 another.  For example, you can upgrade from v15.2.0 (the first Octopus
   7 release) to the next 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 Keep in mind that the Ceph cluster health status is likely to switch to
  16 `HEALTH_WARNING` during the upgrade.
  17
  18
  19 Starting the upgrade
  20 ====================
  21
  22 Before you start, you should verify that all hosts are currently online
  23 and your cluster is healthy.
  24
  25 ::
  26
  27   # ceph -s
  28
  29 To upgrade (or downgrade) to a specific release::
  30
  31   # ceph orch upgrade start --ceph-version <version>
  32
  33 For example, to upgrade to v15.2.1::
  34
  35   # ceph orch upgrade start --ceph-version 15.2.1
  36
  37
  38 Monitoring the upgrade
  39 ======================
  40
  41 Determine whether an upgrade is in process and what version the cluster is
  42 upgrading to with::
  43
  44   # ceph orch upgrade status
  45
  46 While the upgrade is underway, you will see a progress bar in the ceph
  47 status output.  For example::
  48
  49   # ceph -s
  50   [...]
  51     progress:
  52       Upgrade to docker.io/ceph/ceph:v15.2.1 (00h 20m 12s)
  53         [=======.....................] (time remaining: 01h 43m 31s)
  54
  55 You can also watch the cephadm log with::
  56
  57   # ceph -W cephadm
  58
  59
  60 Canceling an upgrade
  61 ====================
  62
  63 You can stop the upgrade process at any time with::
  64
  65   # ceph orch upgrade stop
  66
  67
  68 Potential problems
  69 ==================
  70
  71 There are a few health alerts that can arise during the upgrade process.
  72
  73 UPGRADE_NO_STANDBY_MGR
  74 ----------------------
  75
  76 Ceph requires an active and standby manager daemon in order to proceed, but
  77 there is currently no standby.
  78
  79 You can ensure that Cephadm is configured to run 2 (or more) managers with::
  80
  81   # ceph orch apply mgr 2  # or more
  82
  83 You can check the status of existing mgr daemons with::
  84
  85   # ceph orch ps --daemon-type mgr
  86
  87 If an existing mgr daemon has stopped, you can try restarting it with::
  88
  89   # ceph orch daemon restart <name>
  90
  91 UPGRADE_FAILED_PULL
  92 -------------------
  93
  94 Ceph was unable to pull the container image for the target version.
  95 This can happen if you specify an version or container image that does
  96 not exist (e.g., 1.2.3), or if the container registry is not reachable from
  97 one or more hosts in the cluster.
  98
  99 You can cancel the existing upgrade and specify a different target version with::
 100
 101   # ceph orch upgrade stop
 102   # ceph orch upgrade start --ceph-version <version>
 103
 104
 105 Using customized container images
 106 =================================
 107
 108 For most users, simplify specifying the Ceph version is sufficient.
 109 Cephadm will locate the specific Ceph container image to use by
 110 combining the ``container_image_base`` configuration option (default:
 111 ``docker.io/ceph/ceph``) with a tag of ``vX.Y.Z``.
 112
 113 You can also upgrade to an arbitrary container image.  For example, to
 114 upgrade to a development build::
 115
 116   # ceph orch upgrade start --image quay.io/ceph-ci/ceph:recent-git-branch-name
 117
 118 For more information about available container images, see :ref:`containers`.