]>
Commit | Line | Data |
---|---|---|
11fdf7f2 TL |
1 | .. _rgw-multitenancy: |
2 | ||
7c673cae FG |
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 | |
11fdf7f2 | 26 | disappear as needed, when users are administered. In order to create, |
7c673cae FG |
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 | ||
c07f9fc5 FG |
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. | |
7c673cae FG |
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 | ||
11fdf7f2 TL |
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 | ||
7c673cae FG |
121 | Swift with built-in authenticator |
122 | --------------------------------- | |
123 | ||
124 | TBD -- not in test_multen.py yet | |
125 | ||
126 | Swift with Keystone | |
127 | ------------------- | |
128 | ||
11fdf7f2 TL |
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. | |
7c673cae | 156 | |
9f95a23c TL |
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 | ||
7c673cae FG |
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. |