src/ceph/doc/dev/osd_internals/map_message_handling.rst

   1 ===========================
   2 Map and PG Message handling
   3 ===========================
   4
   5 Overview
   6 --------
   7 The OSD handles routing incoming messages to PGs, creating the PG if necessary
   8 in some cases.
   9
  10 PG messages generally come in two varieties:
  11
  12   1. Peering Messages
  13   2. Ops/SubOps
  14
  15 There are several ways in which a message might be dropped or delayed.  It is
  16 important that the message delaying does not result in a violation of certain
  17 message ordering requirements on the way to the relevant PG handling logic:
  18
  19   1. Ops referring to the same object must not be reordered.
  20   2. Peering messages must not be reordered.
  21   3. Subops must not be reordered.
  22
  23 MOSDMap
  24 -------
  25 MOSDMap messages may come from either monitors or other OSDs.  Upon receipt, the
  26 OSD must perform several tasks:
  27
  28   1. Persist the new maps to the filestore.
  29      Several PG operations rely on having access to maps dating back to the last
  30      time the PG was clean.
  31   2. Update and persist the superblock.
  32   3. Update OSD state related to the current map.
  33   4. Expose new maps to PG processes via *OSDService*.
  34   5. Remove PGs due to pool removal.
  35   6. Queue dummy events to trigger PG map catchup.
  36
  37 Each PG asynchronously catches up to the currently published map during
  38 process_peering_events before processing the event.  As a result, different
  39 PGs may have different views as to the "current" map.
  40
  41 One consequence of this design is that messages containing submessages from
  42 multiple PGs (MOSDPGInfo, MOSDPGQuery, MOSDPGNotify) must tag each submessage
  43 with the PG's epoch as well as tagging the message as a whole with the OSD's
  44 current published epoch.
  45
  46 MOSDPGOp/MOSDPGSubOp
  47 --------------------
  48 See OSD::dispatch_op, OSD::handle_op, OSD::handle_sub_op
  49
  50 MOSDPGOps are used by clients to initiate rados operations. MOSDSubOps are used
  51 between OSDs to coordinate most non peering activities including replicating
  52 MOSDPGOp operations.
  53
  54 OSD::require_same_or_newer map checks that the current OSDMap is at least
  55 as new as the map epoch indicated on the message.  If not, the message is
  56 queued in OSD::waiting_for_osdmap via OSD::wait_for_new_map.  Note, this
  57 cannot violate the above conditions since any two messages will be queued
  58 in order of receipt and if a message is received with epoch e0, a later message
  59 from the same source must be at epoch at least e0.  Note that two PGs from
  60 the same OSD count for these purposes as different sources for single PG
  61 messages.  That is, messages from different PGs may be reordered.
  62
  63
  64 MOSDPGOps follow the following process:
  65
  66   1. OSD::handle_op: validates permissions and crush mapping.
  67      discard the request if they are not connected and the client cannot get the reply ( See OSD::op_is_discardable )
  68      See OSDService::handle_misdirected_op
  69      See PG::op_has_sufficient_caps
  70      See OSD::require_same_or_newer_map
  71   2. OSD::enqueue_op
  72
  73 MOSDSubOps follow the following process:
  74
  75   1. OSD::handle_sub_op checks that sender is an OSD
  76   2. OSD::enqueue_op
  77
  78 OSD::enqueue_op calls PG::queue_op which checks waiting_for_map before calling OpWQ::queue which adds the op to the queue of the PG responsible for handling it.
  79
  80 OSD::dequeue_op is then eventually called, with a lock on the PG.  At
  81 this time, the op is passed to PG::do_request, which checks that:
  82
  83   1. the PG map is new enough (PG::must_delay_op)
  84   2. the client requesting the op has enough permissions (PG::op_has_sufficient_caps)
  85   3. the op is not to be discarded (PG::can_discard_{request,op,subop,scan,backfill})
  86   4. the PG is active (PG::flushed boolean)
  87   5. the op is a CEPH_MSG_OSD_OP and the PG is in PG_STATE_ACTIVE state and not in PG_STATE_REPLAY
  88
  89 If these conditions are not met, the op is either discarded or queued for later processing. If all conditions are met, the op is processed according to its type:
  90
  91   1. CEPH_MSG_OSD_OP is handled by PG::do_op
  92   2. MSG_OSD_SUBOP is handled by PG::do_sub_op
  93   3. MSG_OSD_SUBOPREPLY is handled by PG::do_sub_op_reply
  94   4. MSG_OSD_PG_SCAN is handled by PG::do_scan
  95   5. MSG_OSD_PG_BACKFILL is handled by PG::do_backfill
  96
  97 CEPH_MSG_OSD_OP processing
  98 --------------------------
  99
 100 PrimaryLogPG::do_op handles CEPH_MSG_OSD_OP op and will queue it
 101
 102   1. in wait_for_all_missing if it is a CEPH_OSD_OP_PGLS for a designated snapid and some object updates are still missing
 103   2. in waiting_for_active if the op may write but the scrubber is working
 104   3. in waiting_for_missing_object if the op requires an object or a snapdir or a specific snap that is still missing
 105   4. in waiting_for_degraded_object if the op may write an object or a snapdir that is degraded, or if another object blocks it ("blocked_by")
 106   5. in waiting_for_backfill_pos if the op requires an object that will be available after the backfill is complete
 107   6. in waiting_for_ack if an ack from another OSD is expected
 108   7. in waiting_for_ondisk if the op is waiting for a write to complete
 109
 110 Peering Messages
 111 ----------------
 112 See OSD::handle_pg_(notify|info|log|query)
 113
 114 Peering messages are tagged with two epochs:
 115
 116   1. epoch_sent: map epoch at which the message was sent
 117   2. query_epoch: map epoch at which the message triggering the message was sent
 118
 119 These are the same in cases where there was no triggering message.  We discard
 120 a peering message if the message's query_epoch if the PG in question has entered
 121 a new epoch (See PG::old_peering_evt, PG::queue_peering_event).  Notifies,
 122 infos, notifies, and logs are all handled as PG::RecoveryMachine events and
 123 are wrapped by PG::queue_* by PG::CephPeeringEvts, which include the created
 124 state machine event along with epoch_sent and query_epoch in order to
 125 generically check PG::old_peering_message upon insertion and removal from the
 126 queue.
 127
 128 Note, notifies, logs, and infos can trigger the creation of a PG.  See
 129 OSD::get_or_create_pg.
 130
 131