]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | ||
c07f9fc5 FG |
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. | |
7c673cae FG |
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 | ||
99 | Notes and known issues | |
100 | ---------------------- | |
101 | ||
102 | Just to be clear, it is not possible to create buckets in other | |
103 | tenants at present. The owner of newly created bucket is extracted | |
104 | from authentication information. | |
105 | ||
106 | This document needs examples of administration of Keystone users. | |
107 | The keystone.rst may need to be updated. |