src/ceph/doc/dev/file-striping.rst

   1 File striping
   2 =============
   3
   4 The text below describes how files from Ceph file system clients are
   5 stored across objects stored in RADOS.
   6
   7 ceph_file_layout
   8 ----------------
   9
  10 Ceph distributes (stripes) the data for a given file across a number
  11 of underlying objects.  The way file data is mapped to those objects
  12 is defined by the ceph_file_layout structure.  The data distribution
  13 is a modified RAID 0, where data is striped across a set of objects up
  14 to a (per-file) fixed size, at which point another set of objects
  15 holds the file's data.  The second set also holds no more than the
  16 fixed amount of data, and then another set is used, and so on.
  17
  18 Defining some terminology will go a long way toward explaining the
  19 way file data is laid out across Ceph objects.
  20
  21 - file
  22     A collection of contiguous data, named from the perspective of
  23     the Ceph client (i.e., a file on a Linux system using Ceph
  24     storage).  The data for a file is divided into fixed-size
  25     "stripe units," which are stored in ceph "objects."
  26 - stripe unit
  27     The size (in bytes) of a block of data used in the RAID 0
  28     distribution of a file.  All stripe units for a file have equal
  29     size.  The last stripe unit is typically incomplete--i.e. it
  30     represents the data at the end of the file as well as unused
  31     "space" beyond it up to the end of the fixed stripe unit size.
  32 - stripe count
  33     The number of consecutive stripe units that constitute a RAID 0
  34     "stripe" of file data.
  35 - stripe
  36     A contiguous range of file data, RAID 0 striped across "stripe
  37     count" objects in fixed-size "stripe unit" blocks.
  38 - object
  39     A collection of data maintained by Ceph storage.  Objects are
  40     used to hold portions of Ceph client files.
  41 - object set
  42     A set of objects that together represent a contiguous portion of
  43     a file.
  44
  45 Three fields in the ceph_file_layout structure define this mapping::
  46
  47         u32 fl_stripe_unit;
  48         u32 fl_stripe_count;
  49         u32 fl_object_size;
  50
  51 (They are actually maintained in their on-disk format, __le32.)
  52
  53 The role of the first two fields should be clear from the
  54 definitions above.
  55
  56 The third field is the maximum size (in bytes) of an object used to
  57 back file data.  The object size is a multiple of the stripe unit.
  58
  59 A file's data is blocked into stripe units, and consecutive stripe
  60 units are stored on objects in an object set.  The number of objects
  61 in a set is the same as the stripe count.  No object storing file
  62 data will exceed the file's designated object size, so after some
  63 fixed number of complete stripes, a new object set is used to store
  64 subsequent file data.
  65
  66 Note that by default, Ceph uses a simple striping strategy in which
  67 object_size equals stripe_unit and stripe_count is 1.  This simply
  68 puts one stripe_unit in each object.
  69
  70 Here's a more complex example::
  71
  72     file size = 1 trillion = 1000000000000 bytes
  73
  74     fl_stripe_unit = 64KB = 65536 bytes
  75     fl_stripe_count = 5 stripe units per stripe
  76     fl_object_size = 64GB = 68719476736 bytes
  77
  78 This means::
  79
  80     file stripe size = 64KB * 5 = 320KB = 327680 bytes
  81     each object holds 64GB / 64KB = 1048576 stripe units
  82     file object set size = 64GB * 5 = 320GB = 343597383680 bytes
  83         (also 1048576 stripe units * 327680 bytes per stripe unit)
  84
  85 So the file's 1 trillion bytes can be divided into complete object
  86 sets, then complete stripes, then complete stripe units, and finally
  87 a single incomplete stripe unit::
  88
  89     - 1 trillion bytes / 320GB per object set = 2 complete object sets
  90         (with 312805232640 bytes remaining)
  91     - 312805232640 bytes / 320KB per stripe = 954605 complete stripes
  92         (with 266240 bytes remaining)
  93     - 266240 bytes / 64KB per stripe unit = 4 complete stripe units
  94         (with 4096 bytes remaining)
  95     - and the final incomplete stripe unit holds those 4096 bytes.
  96
  97 The ASCII art below attempts to capture this::
  98
  99      _________   _________   _________   _________   _________
 100     /object  0\ /object  1\ /object  2\ /object  3\ /object  4\
 101     +=========+ +=========+ +=========+ +=========+ +=========+
 102     |  stripe | |  stripe | |  stripe | |  stripe | |  stripe |
 103   o |   unit  | |   unit  | |   unit  | |   unit  | |   unit  | stripe 0
 104   b |     0   | |     1   | |     2   | |     3   | |     4   |
 105   j |---------| |---------| |---------| |---------| |---------|
 106   e |  stripe | |  stripe | |  stripe | |  stripe | |  stripe |
 107   c |   unit  | |   unit  | |   unit  | |   unit  | |   unit  | stripe 1
 108   t |     5   | |     6   | |     7   | |     8   | |     9   |
 109     |---------| |---------| |---------| |---------| |---------|
 110   s |     .   | |     .   | |     .   | |     .   | |     .   |
 111   e       .           .           .           .           .
 112   t |     .   | |     .   | |     .   | |     .   | |     .   |
 113     |---------| |---------| |---------| |---------| |---------|
 114   0 |  stripe | |  stripe | |  stripe | |  stripe | |  stripe | stripe
 115     |   unit  | |   unit  | |   unit  | |   unit  | |   unit  | 1048575
 116     | 5242875 | | 5242876 | | 5242877 | | 5242878 | | 5242879 |
 117     \=========/ \=========/ \=========/ \=========/ \=========/
 118
 119      _________   _________   _________   _________   _________
 120     /object  5\ /object  6\ /object  7\ /object  8\ /object  9\
 121     +=========+ +=========+ +=========+ +=========+ +=========+
 122     |  stripe | |  stripe | |  stripe | |  stripe | |  stripe | stripe
 123   o |   unit  | |   unit  | |   unit  | |   unit  | |   unit  | 1048576
 124   b | 5242880 | | 5242881 | | 5242882 | | 5242883 | | 5242884 |
 125   j |---------| |---------| |---------| |---------| |---------|
 126   e |  stripe | |  stripe | |  stripe | |  stripe | |  stripe | stripe
 127   c |   unit  | |   unit  | |   unit  | |   unit  | |   unit  | 1048577
 128   t | 5242885 | | 5242886 | | 5242887 | | 5242888 | | 5242889 |
 129     |---------| |---------| |---------| |---------| |---------|
 130   s |     .   | |     .   | |     .   | |     .   | |     .   |
 131   e       .           .           .           .           .
 132   t |     .   | |     .   | |     .   | |     .   | |     .   |
 133     |---------| |---------| |---------| |---------| |---------|
 134   1 |  stripe | |  stripe | |  stripe | |  stripe | |  stripe | stripe
 135     |   unit  | |   unit  | |   unit  | |   unit  | |   unit  | 2097151
 136     | 10485755| | 10485756| | 10485757| | 10485758| | 10485759|
 137     \=========/ \=========/ \=========/ \=========/ \=========/
 138
 139      _________   _________   _________   _________   _________
 140     /object 10\ /object 11\ /object 12\ /object 13\ /object 14\
 141     +=========+ +=========+ +=========+ +=========+ +=========+
 142     |  stripe | |  stripe | |  stripe | |  stripe | |  stripe | stripe
 143   o |   unit  | |   unit  | |   unit  | |   unit  | |   unit  | 2097152
 144   b | 10485760| | 10485761| | 10485762| | 10485763| | 10485764|
 145   j |---------| |---------| |---------| |---------| |---------|
 146   e |  stripe | |  stripe | |  stripe | |  stripe | |  stripe | stripe
 147   c |   unit  | |   unit  | |   unit  | |   unit  | |   unit  | 2097153
 148   t | 10485765| | 10485766| | 10485767| | 10485768| | 10485769|
 149     |---------| |---------| |---------| |---------| |---------|
 150   s |     .   | |     .   | |     .   | |     .   | |     .   |
 151   e       .           .           .           .           .
 152   t |     .   | |     .   | |     .   | |     .   | |     .   |
 153     |---------| |---------| |---------| |---------| |---------|
 154   2 |  stripe | |  stripe | |  stripe | |  stripe | |  stripe | stripe
 155     |   unit  | |   unit  | |   unit  | |   unit  | |   unit  | 3051756
 156     | 15258780| | 15258781| | 15258782| | 15258783| | 15258784|
 157     |---------| |---------| |---------| |---------| |---------|
 158     |  stripe | |  stripe | |  stripe | |  stripe | | (partial| (partial
 159     |   unit  | |   unit  | |   unit  | |   unit  | |  stripe | stripe
 160     | 15258785| | 15258786| | 15258787| | 15258788| |  unit)  | 3051757)
 161     \=========/ \=========/ \=========/ \=========/ \=========/