ceph/doc/radosgw/multitenancy.rst

   1 .. _rgw-multitenancy:
   2
   3 =================
   4 RGW Multi-tenancy
   5 =================
   6
   7 .. versionadded:: Jewel
   8
   9 The multi-tenancy feature allows to use buckets and users of the same
  10 name simultaneously by segregating them under so-called ``tenants``.
  11 This may be useful, for instance, to permit users of Swift API to
  12 create buckets with easily conflicting names such as "test" or "trove".
  13
  14 From the Jewel release onward, each user and bucket lies under a tenant.
  15 For compatibility, a "legacy" tenant with an empty name is provided.
  16 Whenever a bucket is referred without an explicit tenant, an implicit
  17 tenant is used, taken from the user performing the operation. Since
  18 the pre-existing users are under the legacy tenant, they continue
  19 to create and access buckets as before. The layout of objects in RADOS
  20 is extended in a compatible way, ensuring a smooth upgrade to Jewel.
  21
  22 Administering Users With Explicit Tenants
  23 =========================================
  24
  25 Tenants as such do not have any operations on them. They appear and
  26 disappear as needed, when users are administered. In order to create,
  27 modify, and remove users with explicit tenants, either an additional
  28 option --tenant is supplied, or a syntax '<tenant>$<user>' is used
  29 in the parameters of the radosgw-admin command.
  30
  31 Examples
  32 --------
  33
  34 Create a user testx$tester to be accessed with S3::
  35
  36   # radosgw-admin --tenant testx --uid tester --display-name "Test User" --access_key TESTER --secret test123 user create
  37
  38 Create a user testx$tester to be accessed with Swift::
  39
  40   # radosgw-admin --tenant testx --uid tester --display-name "Test User" --subuser tester:test --key-type swift --access full user create
  41   # radosgw-admin --subuser 'testx$tester:test' --key-type swift --secret test123
  42
  43 .. note:: The subuser with explicit tenant has to be quoted in the shell.
  44
  45    Tenant names may contain only alphanumeric characters and underscores.
  46
  47 Accessing Buckets with Explicit Tenants
  48 =======================================
  49
  50 When a client application accesses buckets, it always operates with
  51 credentials of a particular user. As mentioned above, every user belongs
  52 to a tenant. Therefore, every operation has an implicit tenant in its
  53 context, to be used if no tenant is specified explicitly. Thus a complete
  54 compatibility is maintained with previous releases, as long as the
  55 referred buckets and referring user belong to the same tenant.
  56 In other words, anything unusual occurs when accessing another tenant's
  57 buckets *only*.
  58
  59 Extensions employed to specify an explicit tenant differ according
  60 to the protocol and authentication system used.
  61
  62 S3
  63 --
  64
  65 In case of S3, a colon character is used to separate tenant and bucket.
  66 Thus a sample URL would be::
  67
  68   https://ep.host.dom/tenant:bucket
  69
  70 Here's a simple Python sample:
  71
  72 .. code-block:: python
  73    :linenos:
  74
  75         from boto.s3.connection import S3Connection, OrdinaryCallingFormat
  76         c = S3Connection(
  77                 aws_access_key_id="TESTER",
  78                 aws_secret_access_key="test123",
  79                 host="ep.host.dom",
  80                 calling_format = OrdinaryCallingFormat())
  81         bucket = c.get_bucket("test5b:testbucket")
  82
  83 Note that it's not possible to supply an explicit tenant using
  84 a hostname. Hostnames cannot contain colons, or any other separators
  85 that are not already valid in bucket names. Using a period creates an
  86 ambiguous syntax. Therefore, the bucket-in-URL-path format has to be
  87 used.
  88
  89 Due to the fact that the native S3 API does not deal with
  90 multi-tenancy and radosgw's implementation does, things get a bit
  91 involved when dealing with signed URLs and public read ACLs.
  92
  93 * A **signed URL** does contain the ``AWSAccessKeyId`` query
  94   parameters, from which radosgw is able to discern the correct user
  95   and tenant owning the bucket. In other words, an application
  96   generating signed URLs should be able to take just the un-prefixed
  97   bucket name, and produce a signed URL that itself contains the
  98   bucket name without the tenant prefix. However, it is *possible* to
  99   include the prefix if you so choose.
 100
 101   Thus, accessing a signed URL of an object ``bar`` in a container
 102   ``foo`` belonging to the tenant ``7188e165c0ae4424ac68ae2e89a05c50``
 103   would be possible either via
 104   ``http://<host>:<port>/foo/bar?AWSAccessKeyId=b200fb6634c547199e436a0f93c0c46e&Expires=1542890806&Signature=eok6CYQC%2FDwmQQmqvY5jTg6ehXU%3D``,
 105   or via
 106   ``http://<host>:<port>/7188e165c0ae4424ac68ae2e89a05c50:foo/bar?AWSAccessKeyId=b200fb6634c547199e436a0f93c0c46e&Expires=1542890806&Signature=eok6CYQC%2FDwmQQmqvY5jTg6ehXU%3D``,
 107   depending on whether or not the tenant prefix was passed in on
 108   signature generation.
 109
 110 * A bucket with a **public read ACL** is meant to be read by an HTTP
 111   client *without* including any query parameters that would allow
 112   radosgw to discern tenants. Thus, publicly readable objects must
 113   always be accessed using the bucket name with the tenant prefix.
 114
 115   Thus, if you set a public read ACL on an object ``bar`` in a
 116   container ``foo`` belonging to the tenant
 117   ``7188e165c0ae4424ac68ae2e89a05c50``, you would need to access that
 118   object via the public URL
 119   ``http://<host>:<port>/7188e165c0ae4424ac68ae2e89a05c50:foo/bar``.
 120
 121 Swift with built-in authenticator
 122 ---------------------------------
 123
 124 TBD -- not in test_multen.py yet
 125
 126 Swift with Keystone
 127 -------------------
 128
 129 In the default configuration, although native Swift has inherent
 130 multi-tenancy, radosgw does not enable multi-tenancy for the Swift
 131 API. This is to ensure that a setup with legacy buckets --- that is,
 132 buckets that were created before radosgw supported multitenancy ---,
 133 those buckets retain their dual-API capability to be queried and
 134 modified using either S3 or Swift.
 135
 136 If you want to enable multitenancy for Swift, particularly if your
 137 users only ever authenticate against OpenStack Keystone, you should
 138 enable Keystone-based multitenancy with the following ``ceph.conf``
 139 configuration option::
 140
 141   rgw keystone implicit tenants = true
 142
 143 Once you enable this option, any newly connecting user (whether they
 144 are using the Swift API, or Keystone-authenticated S3) will prompt
 145 radosgw to create a user named ``<tenant_id>$<tenant_id``, where
 146 ``<tenant_id>`` is a Keystone tenant (project) UUID --- for example,
 147 ``7188e165c0ae4424ac68ae2e89a05c50$7188e165c0ae4424ac68ae2e89a05c50``.
 148
 149 Whenever that user then creates an Swift container, radosgw internally
 150 translates the given container name into
 151 ``<tenant_id>/<container_name>``, such as
 152 ``7188e165c0ae4424ac68ae2e89a05c50/foo``. This ensures that if there
 153 are two or more different tenants all creating a container named
 154 ``foo``, radosgw is able to transparently discern them by their tenant
 155 prefix.
 156
 157 It is also possible to limit the effects of implicit tenants
 158 to only apply to swift or s3, by setting ``rgw keystone implicit tenants``
 159 to either ``s3`` or ``swift``.  This will likely primarily
 160 be of use to users who had previously used implicit tenants
 161 with older versions of ceph, where implicit tenants
 162 only applied to the swift protocol.
 163
 164 Notes and known issues
 165 ----------------------
 166
 167 Just to be clear, it is not possible to create buckets in other
 168 tenants at present. The owner of newly created bucket is extracted
 169 from authentication information.