ceph/doc/dev/mon-on-disk-formats.rst

   1 ##############
   2 ON-DISK FORMAT
   3 ##############
   4
   5
   6 ************
   7 UPGRADE PATH
   8 ************
   9
  10 On-disk formats, or even data structure formats, may be changed during an
  11 upgrade. Services wishing to do so, may so do it via the
  12 `PaxosService::upgrade_format()` call path. There is no formalized, unified
  13 format versioning; the `PaxosService` class keeps track of its
  14 `format_version` through a key in the store, assumed an `unsigned int`,  but
  15 it will be the service's responsibility to give meaning to those versions.
  16
  17 AUTH MONITOR
  18 ============
  19
  20 versions
  21 --------
  22
  23 versions are represented with a single `unsigned int`. By default, the value
  24 zero represents the absence of a formal upgraded format. The first format
  25 version was introduced in Dumpling; clusters upgrading to Dumpling saw their
  26 format version being increased from zero to one::
  27
  28   0 to 1 - introduced in v0.65, dev release for v0.67 dumpling
  29   1 to 2 - introduced in v12.0.2, dev release for luminous
  30   2 to 3 - introduced in mimic
  31
  32   0 - all clusters pre-dumpling
  33   1 - all clusters dumpling+ and pre-luminous
  34   2 - all clusters luminous+ and pre-mimic
  35   3 - all clusters mimic+
  36
  37   version 1: introduces new-style monitor caps (i.e., profiles)
  38   version 2: introduces mgr caps and bootstrap-mgr key
  39   version 3: creates all bootstrap and admin keys if they don't yet exist
  40
  41 callstack
  42 ---------
  43
  44 format_version set on `PaxosService::refresh()`::
  45
  46   - initially called from Monitor::refresh_from_paxos
  47     - initially called from Monitor::init_paxos()
  48       - initially called from Monitor::preinit()
  49
  50 AuthMonitor::upgrade_format() called by `PaxosService::_active()`::
  51
  52   - called from C_Committed callback, from PaxosService::propose_pending()
  53   - called from C_Active callback, from PaxosService::_active()
  54   - called from PaxosService::election_finished()
  55
  56   - on a freshly deployed cluster, upgrade_format() will be first called
  57     *after* create_initial().
  58   - on an existing cluster, upgrade_format() will be called after the first
  59     election.
  60
  61   - upgrade_format() is irrelevant on a freshly deployed cluster, as there is
  62     no format to upgrade at this point.
  63
  64 boil down
  65 ---------
  66
  67 * if `format_version >= current_version` then format is up-to-date, return.
  68 * if `features doesn't contain LUMINOUS` then `current_version = 1`
  69 * else if `features doesn't contain MIMIC` then `current_version = 2`
  70 * else `current_version = 3`
  71
  72 if `format_version == 0`::
  73
  74   - upgrade to format version 1
  75     - move to new-style monitor caps (i.e., profiles):
  76       - set daemon profiles for existing entities
  77       - set profile for existing bootstrap keys
  78
  79 if `format_version == 1`::
  80
  81   - upgrade to format version 2
  82     - for existing entities:
  83       - add new cap for mgr
  84     - for existing 'mgr' entities, fix 'mon' caps due to bug from kraken
  85       setting 'allow \*', and set 'allow profile mgr' instead.
  86     - add bootstrap-mgr key.
  87
  88 if `format_version == 2`::
  89
  90   - upgrade to format version 3
  91     - create all bootstrap keys if they don't currently exist