[ceph.git] / ceph / doc / radosgw / multitenancy.rst

.. _rgw-multitenancy:

=================
RGW Multi-tenancy
=================

.. versionadded:: Jewel

The multi-tenancy feature allows to use buckets and users of the same
name simultaneously by segregating them under so-called ``tenants``.
This may be useful, for instance, to permit users of Swift API to
create buckets with easily conflicting names such as "test" or "trove".

From the Jewel release onward, each user and bucket lies under a tenant.
For compatibility, a "legacy" tenant with an empty name is provided.
Whenever a bucket is referred without an explicit tenant, an implicit
tenant is used, taken from the user performing the operation. Since
the pre-existing users are under the legacy tenant, they continue
to create and access buckets as before. The layout of objects in RADOS
is extended in a compatible way, ensuring a smooth upgrade to Jewel.

Administering Users With Explicit Tenants
=========================================

Tenants as such do not have any operations on them. They appear and
disappear as needed, when users are administered. In order to create,
modify, and remove users with explicit tenants, either an additional
option --tenant is supplied, or a syntax "<tenant>$<user>" is used
in the parameters of the radosgw-admin command.

Examples
--------

Create a user testx$tester to be accessed with S3::

  # radosgw-admin --tenant testx --uid tester --display-name "Test User" --access_key TESTER --secret test123 user create

Create a user testx$tester to be accessed with Swift::

  # radosgw-admin --tenant testx --uid tester --display-name "Test User" --subuser tester:test --key-type swift --access full user create
  # radosgw-admin --subuser 'testx$tester:test' --key-type swift --secret test123

.. note:: The subuser with explicit tenant has to be quoted in the shell.

   Tenant names may contain only alphanumeric characters and underscores.

Accessing Buckets with Explicit Tenants
=======================================

When a client application accesses buckets, it always operates with
credentials of a particular user. As mentioned above, every user belongs
to a tenant. Therefore, every operation has an implicit tenant in its
context, to be used if no tenant is specified explicitly. Thus a complete
compatibility is maintained with previous releases, as long as the
referred buckets and referring user belong to the same tenant.
In other words, anything unusual occurs when accessing another tenant's
buckets *only*.

Extensions employed to specify an explicit tenant differ according
to the protocol and authentication system used.

S3
--

In case of S3, a colon character is used to separate tenant and bucket.
Thus a sample URL would be::

  https://ep.host.dom/tenant:bucket

Here's a simple Python sample:

.. code-block:: python
   :linenos:

	from boto.s3.connection import S3Connection, OrdinaryCallingFormat
	c = S3Connection(
		aws_access_key_id="TESTER",
		aws_secret_access_key="test123",
		host="ep.host.dom",
		calling_format = OrdinaryCallingFormat())
	bucket = c.get_bucket("test5b:testbucket")

Note that it's not possible to supply an explicit tenant using
a hostname. Hostnames cannot contain colons, or any other separators
that are not already valid in bucket names. Using a period creates an
ambiguous syntax. Therefore, the bucket-in-URL-path format has to be
used.

Due to the fact that the native S3 API does not deal with
multi-tenancy and radosgw's implementation does, things get a bit
involved when dealing with signed URLs and public read ACLs.

* A **signed URL** does contain the ``AWSAccessKeyId`` query
  parameters, from which radosgw is able to discern the correct user
  and tenant owning the bucket. In other words, an application
  generating signed URLs should be able to take just the un-prefixed
  bucket name, and produce a signed URL that itself contains the
  bucket name without the tenant prefix. However, it is *possible* to
  include the prefix if you so choose.

  Thus, accessing a signed URL of an object ``bar`` in a container
  ``foo`` belonging to the tenant ``7188e165c0ae4424ac68ae2e89a05c50``
  would be possible either via
  ``http://<host>:<port>/foo/bar?AWSAccessKeyId=b200fb6634c547199e436a0f93c0c46e&Expires=1542890806&Signature=eok6CYQC%2FDwmQQmqvY5jTg6ehXU%3D``,
  or via
  ``http://<host>:<port>/7188e165c0ae4424ac68ae2e89a05c50:foo/bar?AWSAccessKeyId=b200fb6634c547199e436a0f93c0c46e&Expires=1542890806&Signature=eok6CYQC%2FDwmQQmqvY5jTg6ehXU%3D``,
  depending on whether or not the tenant prefix was passed in on
  signature generation.

* A bucket with a **public read ACL** is meant to be read by an HTTP
  client *without* including any query parameters that would allow
  radosgw to discern tenants. Thus, publicly readable objects must
  always be accessed using the bucket name with the tenant prefix.

  Thus, if you set a public read ACL on an object ``bar`` in a
  container ``foo`` belonging to the tenant
  ``7188e165c0ae4424ac68ae2e89a05c50``, you would need to access that
  object via the public URL
  ``http://<host>:<port>/7188e165c0ae4424ac68ae2e89a05c50:foo/bar``.

Swift with built-in authenticator
---------------------------------

TBD -- not in test_multen.py yet

Swift with Keystone
-------------------

In the default configuration, although native Swift has inherent
multi-tenancy, radosgw does not enable multi-tenancy for the Swift
API. This is to ensure that a setup with legacy buckets --- that is,
buckets that were created before radosgw supported multitenancy ---,
those buckets retain their dual-API capability to be queried and
modified using either S3 or Swift.

If you want to enable multitenancy for Swift, particularly if your
users only ever authenticate against OpenStack Keystone, you should
enable Keystone-based multitenancy with the following ``ceph.conf``
configuration option::

  rgw keystone implicit tenants = true

Once you enable this option, any newly connecting user (whether they
are using the Swift API, or Keystone-authenticated S3) will prompt
radosgw to create a user named ``<tenant_id>$<tenant_id``, where
``<tenant_id>`` is a Keystone tenant (project) UUID --- for example,
``7188e165c0ae4424ac68ae2e89a05c50$7188e165c0ae4424ac68ae2e89a05c50``.

Whenever that user then creates an Swift container, radosgw internally
translates the given container name into
``<tenant_id>/<container_name>``, such as
``7188e165c0ae4424ac68ae2e89a05c50/foo``. This ensures that if there
are two or more different tenants all creating a container named
``foo``, radosgw is able to transparently discern them by their tenant
prefix.

Notes and known issues
----------------------

Just to be clear, it is not possible to create buckets in other
tenants at present. The owner of newly created bucket is extracted
from authentication information.
Commit	Line	Data
11fdf7f2 TL	1	.. _rgw-multitenancy:
11fdf7f2 TL	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 FG	156
	157	Notes and known issues
	158	----------------------
	159
	160	Just to be clear, it is not possible to create buckets in other
	161	tenants at present. The owner of newly created bucket is extracted
	162	from authentication information.