src/ceph/doc/dev/cache-pool.rst

   1 Cache pool
   2 ==========
   3
   4 Purpose
   5 -------
   6
   7 Use a pool of fast storage devices (probably SSDs) and use it as a
   8 cache for an existing slower and larger pool.
   9
  10 Use a replicated pool as a front-end to service most I/O, and destage
  11 cold data to a separate erasure coded pool that does not currently (and
  12 cannot efficiently) handle the workload.
  13
  14 We should be able to create and add a cache pool to an existing pool
  15 of data, and later remove it, without disrupting service or migrating
  16 data around.
  17
  18 Use cases
  19 ---------
  20
  21 Read-write pool, writeback
  22 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  23
  24 We have an existing data pool and put a fast cache pool "in front" of
  25 it.  Writes will go to the cache pool and immediately ack.  We flush
  26 them back to the data pool based on the defined policy.
  27
  28 Read-only pool, weak consistency
  29 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  30
  31 We have an existing data pool and add one or more read-only cache
  32 pools.  We copy data to the cache pool(s) on read.  Writes are
  33 forwarded to the original data pool.  Stale data is expired from the
  34 cache pools based on the defined policy.
  35
  36 This is likely only useful for specific applications with specific
  37 data access patterns.  It may be a match for rgw, for example.
  38
  39
  40 Interface
  41 ---------
  42
  43 Set up a read/write cache pool foo-hot for pool foo::
  44
  45  ceph osd tier add foo foo-hot
  46  ceph osd tier cache-mode foo-hot writeback
  47
  48 Direct all traffic for foo to foo-hot::
  49
  50  ceph osd tier set-overlay foo foo-hot
  51
  52 Set the target size and enable the tiering agent for foo-hot::
  53
  54  ceph osd pool set foo-hot hit_set_type bloom
  55  ceph osd pool set foo-hot hit_set_count 1
  56  ceph osd pool set foo-hot hit_set_period 3600   # 1 hour
  57  ceph osd pool set foo-hot target_max_bytes 1000000000000  # 1 TB
  58  ceph osd pool set foo-hot min_read_recency_for_promote 1
  59  ceph osd pool set foo-hot min_write_recency_for_promote 1
  60
  61 Drain the cache in preparation for turning it off::
  62
  63  ceph osd tier cache-mode foo-hot forward
  64  rados -p foo-hot cache-flush-evict-all
  65
  66 When cache pool is finally empty, disable it::
  67
  68  ceph osd tier remove-overlay foo
  69  ceph osd tier remove foo foo-hot
  70
  71 Read-only pools with lazy consistency::
  72
  73  ceph osd tier add foo foo-east
  74  ceph osd tier cache-mode foo-east readonly
  75  ceph osd tier add foo foo-west
  76  ceph osd tier cache-mode foo-west readonly
  77
  78
  79
  80 Tiering agent
  81 -------------
  82
  83 The tiering policy is defined as properties on the cache pool itself.
  84
  85 HitSet metadata
  86 ~~~~~~~~~~~~~~~
  87
  88 First, the agent requires HitSet information to be tracked on the
  89 cache pool in order to determine which objects in the pool are being
  90 accessed.  This is enabled with::
  91
  92  ceph osd pool set foo-hot hit_set_type bloom
  93  ceph osd pool set foo-hot hit_set_count 1
  94  ceph osd pool set foo-hot hit_set_period 3600   # 1 hour
  95
  96 The supported HitSet types include 'bloom' (a bloom filter, the
  97 default), 'explicit_hash', and 'explicit_object'.  The latter two
  98 explicitly enumerate accessed objects and are less memory efficient.
  99 They are there primarily for debugging and to demonstrate pluggability
 100 for the infrastructure.  For the bloom filter type, you can additionally
 101 define the false positive probability for the bloom filter (default is 0.05)::
 102
 103  ceph osd pool set foo-hot hit_set_fpp 0.15
 104
 105 The hit_set_count and hit_set_period define how much time each HitSet
 106 should cover, and how many such HitSets to store.  Binning accesses
 107 over time allows Ceph to independently determine whether an object was
 108 accessed at least once and whether it was accessed more than once over
 109 some time period ("age" vs "temperature").
 110
 111 The ``min_read_recency_for_promote`` defines how many HitSets to check for the
 112 existence of an object when handling a read operation. The checking result is
 113 used to decide whether to promote the object asynchronously. Its value should be
 114 between 0 and ``hit_set_count``. If it's set to 0, the object is always promoted.
 115 If it's set to 1, the current HitSet is checked. And if this object is in the
 116 current HitSet, it's promoted. Otherwise not. For the other values, the exact
 117 number of archive HitSets are checked. The object is promoted if the object is
 118 found in any of the most recent ``min_read_recency_for_promote`` HitSets.
 119
 120 A similar parameter can be set for the write operation, which is
 121 ``min_write_recency_for_promote``. ::
 122
 123  ceph osd pool set {cachepool} min_read_recency_for_promote 1
 124  ceph osd pool set {cachepool} min_write_recency_for_promote 1
 125
 126 Note that the longer the ``hit_set_period`` and the higher the
 127 ``min_read_recency_for_promote``/``min_write_recency_for_promote`` the more RAM
 128 will be consumed by the ceph-osd process. In particular, when the agent is active
 129 to flush or evict cache objects, all hit_set_count HitSets are loaded into RAM.
 130
 131 Cache mode
 132 ~~~~~~~~~~
 133
 134 The most important policy is the cache mode:
 135
 136  ceph osd pool set foo-hot cache-mode writeback
 137
 138 The supported modes are 'none', 'writeback', 'forward', and
 139 'readonly'.  Most installations want 'writeback', which will write
 140 into the cache tier and only later flush updates back to the base
 141 tier.  Similarly, any object that is read will be promoted into the
 142 cache tier.
 143
 144 The 'forward' mode is intended for when the cache is being disabled
 145 and needs to be drained.  No new objects will be promoted or written
 146 to the cache pool unless they are already present.  A background
 147 operation can then do something like::
 148
 149   rados -p foo-hot cache-try-flush-evict-all
 150   rados -p foo-hot cache-flush-evict-all
 151
 152 to force all data to be flushed back to the base tier.
 153
 154 The 'readonly' mode is intended for read-only workloads that do not
 155 require consistency to be enforced by the storage system.  Writes will
 156 be forwarded to the base tier, but objects that are read will get
 157 promoted to the cache.  No attempt is made by Ceph to ensure that the
 158 contents of the cache tier(s) are consistent in the presence of object
 159 updates.
 160
 161 Cache sizing
 162 ~~~~~~~~~~~~
 163
 164 The agent performs two basic functions: flushing (writing 'dirty'
 165 cache objects back to the base tier) and evicting (removing cold and
 166 clean objects from the cache).
 167
 168 The thresholds at which Ceph will flush or evict objects is specified
 169 relative to a 'target size' of the pool.  For example::
 170
 171  ceph osd pool set foo-hot cache_target_dirty_ratio .4
 172  ceph osd pool set foo-hot cache_target_dirty_high_ratio .6
 173  ceph osd pool set foo-hot cache_target_full_ratio .8
 174
 175 will begin flushing dirty objects when 40% of the pool is dirty and begin
 176 evicting clean objects when we reach 80% of the target size.
 177
 178 The target size can be specified either in terms of objects or bytes::
 179
 180  ceph osd pool set foo-hot target_max_bytes 1000000000000  # 1 TB
 181  ceph osd pool set foo-hot target_max_objects 1000000       # 1 million objects
 182
 183 Note that if both limits are specified, Ceph will begin flushing or
 184 evicting when either threshold is triggered.
 185
 186 Other tunables
 187 ~~~~~~~~~~~~~~
 188
 189 You can specify a minimum object age before a recently updated object is
 190 flushed to the base tier::
 191
 192  ceph osd pool set foo-hot cache_min_flush_age 600   # 10 minutes
 193
 194 You can specify the minimum age of an object before it will be evicted from
 195 the cache tier::
 196
 197  ceph osd pool set foo-hot cache_min_evict_age 1800   # 30 minutes
 198
 199
 200