ceph/doc/radosgw/multitenancy.rst

   1 =================
   2 RGW Multi-tenancy
   3 =================
   4
   5 .. versionadded:: Jewel
   6
   7 The multi-tenancy feature allows to use buckets and users of the same
   8 name simultaneously by segregating them under so-called ``tenants``.
   9 This may be useful, for instance, to permit users of Swift API to
  10 create buckets with easily conflicting names such as "test" or "trove".
  11
  12 From the Jewel release onward, each user and bucket lies under a tenant.
  13 For compatibility, a "legacy" tenant with an empty name is provided.
  14 Whenever a bucket is referred without an explicit tenant, an implicit
  15 tenant is used, taken from the user performing the operation. Since
  16 the pre-existing users are under the legacy tenant, they continue
  17 to create and access buckets as before. The layout of objects in RADOS
  18 is extended in a compatible way, ensuring a smooth upgrade to Jewel.
  19
  20 Administering Users With Explicit Tenants
  21 =========================================
  22
  23 Tenants as such do not have any operations on them. They appear and
  24 and disappear as needed, when users are administered. In order to create,
  25 modify, and remove users with explicit tenants, either an additional
  26 option --tenant is supplied, or a syntax "<tenant>$<user>" is used
  27 in the parameters of the radosgw-admin command.
  28
  29 Examples
  30 --------
  31
  32 Create a user testx$tester to be accessed with S3::
  33
  34   # radosgw-admin --tenant testx --uid tester --display-name "Test User" --access_key TESTER --secret test123 user create
  35
  36 Create a user testx$tester to be accessed with Swift::
  37
  38   # radosgw-admin --tenant testx --uid tester --display-name "Test User" --subuser tester:test --key-type swift --access full user create
  39   # radosgw-admin --subuser 'testx$tester:test' --key-type swift --secret test123
  40
  41 .. note:: The subuser with explicit tenant has to be quoted in the shell.
  42
  43    Tenant names may contain only alphanumeric characters and underscores.
  44
  45 Accessing Buckets with Explicit Tenants
  46 =======================================
  47
  48 When a client application accesses buckets, it always operates with
  49 credentials of a particular user. As mentioned above, every user belongs
  50 to a tenant. Therefore, every operation has an implicit tenant in its
  51 context, to be used if no tenant is specified explicitly. Thus a complete
  52 compatibility is maintained with previous releases, as long as the
  53 referred buckets and referring user belong to the same tenant.
  54 In other words, anything unusual occurs when accessing another tenant's
  55 buckets *only*.
  56
  57 Extensions employed to specify an explicit tenant differ according
  58 to the protocol and authentication system used.
  59
  60 S3
  61 --
  62
  63 In case of S3, a colon character is used to separate tenant and bucket.
  64 Thus a sample URL would be::
  65
  66   https://ep.host.dom/tenant:bucket
  67
  68 Here's a simple Python sample:
  69
  70 .. code-block:: python
  71    :linenos:
  72
  73         from boto.s3.connection import S3Connection, OrdinaryCallingFormat
  74         c = S3Connection(
  75                 aws_access_key_id="TESTER",
  76                 aws_secret_access_key="test123",
  77                 host="ep.host.dom",
  78                 calling_format = OrdinaryCallingFormat())
  79         bucket = c.get_bucket("test5b:testbucket")
  80
  81 Note that it's not possible to supply an explicit tenant using
  82 a hostname. Hostnames cannot contain colons, or any other separators
  83 that are not already valid in bucket names. Using a period creates an
  84 ambiguous syntax. Therefore, the bucket-in-URL-path format has to be
  85 used.
  86
  87 Swift with built-in authenticator
  88 ---------------------------------
  89
  90 TBD -- not in test_multen.py yet
  91
  92 Swift with Keystone
  93 -------------------
  94
  95 TBD -- don't forget to explain the function of
  96        rgw keystone implicit tenants = true
  97        in commit e9259486decab52a362443d3fd3dec33b0ec654f
  98        [ There is a description of this in keystone.rst ]
  99
 100 Notes and known issues
 101 ----------------------
 102
 103 Just to be clear, it is not possible to create buckets in other
 104 tenants at present. The owner of newly created bucket is extracted
 105 from authentication information.
 106
 107 This document needs examples of administration of Keystone users.
 108 The keystone.rst may need to be updated.