src/ceph/doc/radosgw/layout.rst

   1 ===========================
   2  Rados Gateway Data Layout
   3 ===========================
   4
   5 Although the source code is the ultimate guide, this document helps
   6 new developers to get up to speed with the implementation details.
   7
   8 Introduction
   9 ------------
  10
  11 Swift offers something called a container, that we use interchangeably with
  12 the term bucket. One may say that RGW's buckets implement Swift containers.
  13
  14 This document does not consider how RGW operates on these structures,
  15 e.g. the use of encode() and decode() methods for serialization and so on.
  16
  17 Conceptual View
  18 ---------------
  19
  20 Although RADOS only knows about pools and objects with their xattrs and
  21 omap[1], conceptually RGW organizes its data into three different kinds:
  22 metadata, bucket index, and data.
  23
  24 Metadata
  25 ^^^^^^^^
  26
  27 We have 3 'sections' of metadata: 'user', 'bucket', and 'bucket.instance'.
  28 You can use the following commands to introspect metadata entries: ::
  29
  30     $ radosgw-admin metadata list
  31     $ radosgw-admin metadata list bucket
  32     $ radosgw-admin metadata list bucket.instance
  33     $ radosgw-admin metadata list user
  34
  35     $ radosgw-admin metadata get bucket:<bucket>
  36     $ radosgw-admin metadata get bucket.instance:<bucket>:<bucket_id>
  37     $ radosgw-admin metadata get user:<user>   # get or set
  38
  39 Some variables have been used in above commands, they are:
  40
  41 - user: Holds user information
  42 - bucket: Holds a mapping between bucket name and bucket instance id
  43 - bucket.instance: Holds bucket instance information[2]
  44
  45 Every metadata entry is kept on a single rados object.
  46 See below for implementation defails.
  47
  48 Note that the metadata is not indexed. When listing a metadata section we do a
  49 rados pgls operation on the containing pool.
  50
  51 Bucket Index
  52 ^^^^^^^^^^^^
  53
  54 It's a different kind of metadata, and kept separately. The bucket index holds
  55 a key-value map in rados objects. By default it is a single rados object per
  56 bucket, but it is possible since Hammer to shard that map over multiple rados
  57 objects. The map itself is kept in omap, associated with each rados object.
  58 The key of each omap is the name of the objects, and the value holds some basic
  59 metadata of that object -- metadata that shows up when listing the bucket.
  60 Also, each omap holds a header, and we keep some bucket accounting metadata
  61 in that header (number of objects, total size, etc.).
  62
  63 Note that we also hold other information in the bucket index, and it's kept in
  64 other key namespaces. We can hold the bucket index log there, and for versioned
  65 objects there is more information that we keep on other keys.
  66
  67 Data
  68 ^^^^
  69
  70 Objects data is kept in one or more rados objects for each rgw object.
  71
  72 Object Lookup Path
  73 ------------------
  74
  75 When accessing objects, ReST APIs come to RGW with three parameters:
  76 account information (access key in S3 or account name in Swift),
  77 bucket or container name, and object name (or key). At present, RGW only
  78 uses account information to find out the user ID and for access control.
  79 Only the bucket name and object key are used to address the object in a pool.
  80
  81 The user ID in RGW is a string, typically the actual user name from the user
  82 credentials and not a hashed or mapped identifier.
  83
  84 When accessing a user's data, the user record is loaded from an object
  85 "<user_id>" in pool "default.rgw.meta" with namespace "users.uid".
  86
  87 Bucket names are represented in the pool "default.rgw.meta" with namespace
  88 "root". Bucket record is
  89 loaded in order to obtain so-called marker, which serves as a bucket ID.
  90
  91 The object is located in pool "default.rgw.buckets.data".
  92 Object name is "<marker>_<key>",
  93 for example "default.7593.4_image.png", where the marker is "default.7593.4"
  94 and the key is "image.png". Since these concatenated names are not parsed,
  95 only passed down to RADOS, the choice of the separator is not important and
  96 causes no ambiguity. For the same reason, slashes are permitted in object
  97 names (keys).
  98
  99 It is also possible to create multiple data pools and make it so that
 100 different users buckets will be created in different rados pools by default,
 101 thus providing the necessary scaling. The layout and naming of these pools
 102 is controlled by a 'policy' setting.[3]
 103
 104 An RGW object may consist of several RADOS objects, the first of which
 105 is the head that contains the metadata, such as manifest, ACLs, content type,
 106 ETag, and user-defined metadata. The metadata is stored in xattrs.
 107 The head may also contain up to 512 kilobytes of object data, for efficiency
 108 and atomicity. The manifest describes how each object is laid out in RADOS
 109 objects.
 110
 111 Bucket and Object Listing
 112 -------------------------
 113
 114 Buckets that belong to a given user are listed in an omap of an object named
 115 "<user_id>.buckets" (for example, "foo.buckets") in pool "default.rgw.meta"
 116 with namespace "users.uid".
 117 These objects are accessed when listing buckets, when updating bucket
 118 contents, and updating and retrieving bucket statistics (e.g. for quota).
 119
 120 See the user-visible, encoded class 'cls_user_bucket_entry' and its
 121 nested class 'cls_user_bucket' for the values of these omap entires.
 122
 123 These listings are kept consistent with buckets in pool ".rgw".
 124
 125 Objects that belong to a given bucket are listed in a bucket index,
 126 as discussed in sub-section 'Bucket Index' above. The default naming
 127 for index objects is ".dir.<marker>" in pool "default.rgw.buckets.index".
 128
 129 Footnotes
 130 ---------
 131
 132 [1] Omap is a key-value store, associated with an object, in a way similar
 133 to how Extended Attributes associate with a POSIX file. An object's omap
 134 is not physically located in the object's storage, but its precise
 135 implementation is invisible and immaterial to RADOS Gateway.
 136 In Hammer, one LevelDB is used to store omap in each OSD.
 137
 138 [2] Before the Dumpling release, the 'bucket.instance' metadata did not
 139 exist and the 'bucket' metadata contained its information. It is possible
 140 to encounter such buckets in old installations.
 141
 142 [3] The pool names have been changed starting with the Infernalis release.
 143 If you are looking at an older setup, some details may be different. In
 144 particular there was a different pool for each of the namespaces that are
 145 now being used inside the default.root.meta pool.
 146
 147 Appendix: Compendium
 148 --------------------
 149
 150 Known pools:
 151
 152 .rgw.root
 153   Unspecified region, zone, and global information records, one per object.
 154
 155 <zone>.rgw.control
 156   notify.<N>
 157
 158 <zone>.rgw.meta
 159   Multiple namespaces with different kinds of metadata:
 160
 161   namespace: root
 162     <bucket>
 163     .bucket.meta.<bucket>:<marker>   # see put_bucket_instance_info()
 164
 165     The tenant is used to disambiguate buckets, but not bucket instances.
 166     Example::
 167
 168       .bucket.meta.prodtx:test%25star:default.84099.6
 169       .bucket.meta.testcont:default.4126.1
 170       .bucket.meta.prodtx:testcont:default.84099.4
 171       prodtx/testcont
 172       prodtx/test%25star
 173       testcont
 174
 175   namespace: users.uid
 176     Contains _both_ per-user information (RGWUserInfo) in "<user>" objects
 177     and per-user lists of buckets in omaps of "<user>.buckets" objects.
 178     The "<user>" may contain the tenant if non-empty, for example::
 179
 180       prodtx$prodt
 181       test2.buckets
 182       prodtx$prodt.buckets
 183       test2
 184
 185   namespace: users.email
 186     Unimportant
 187
 188   namespace: users.keys
 189     47UA98JSTJZ9YAN3OS3O
 190
 191     This allows radosgw to look up users by their access keys during authentication.
 192
 193   namespace: users.swift
 194     test:tester
 195
 196 <zone>.rgw.buckets.index
 197   Objects are named ".dir.<marker>", each contains a bucket index.
 198   If the index is sharded, each shard appends the shard index after
 199   the marker.
 200
 201 <zone>.rgw.buckets.data
 202   default.7593.4__shadow_.488urDFerTYXavx4yAd-Op8mxehnvTI_1
 203   <marker>_<key>
 204
 205 An example of a marker would be "default.16004.1" or "default.7593.4".
 206 The current format is "<zone>.<instance_id>.<bucket_id>". But once
 207 generated, a marker is not parsed again, so its format may change
 208 freely in the future.