Creating a New Tenant

A new tenant is created with the REST command:

POST /_tenants

This command must include a message body that minimally identifiers the new tenant’s name. Optionally, the command can define one or more tenant users and/or tenant options. An example in XML is shown below:

<tenant name="HelloKitty">

<options>

<option name="ReplicationFactor">3</option>

</options>

<properties>

<property name="Owner_Organization">Cats, Inc.</property>

</properties>

<users>

<user name="Katniss" password="Everdeen"/>

<user name="Asparagus" password="Gus">

<permissions>APPEND</permissions>

</user>

<user name="Skimbleshanks" password="Skanks">

<permissions>READ</permissions>

</user>

</users>

</tenant>

In JSON:

{"HelloKitty": {

"options": {

"ReplicationFactor": "3"

},

"properties": {

"Owner_Organization": "Cats, Inc."

},

"users": {

"Katniss": {

"password": "Everdeen"

},

"Asparagus": {

"password": "Gus",

"permissions": "APPEND"

},

"Skimbleshanks": {

"password": "Skanks",

"permissions": "READ"

}

}

}}

Only the new tenant name (HelloKitty) is required. Options, properties, and/or users can also be defined with the following semantics:

•

options: This group sets system-defined tenant options. Currently, the only option supported is ReplicationFactor, which overrides the replication_factor defined within the ks_defaults parameter in doradus.yaml. This option sets the replication factor for data stored within the tenant. It should not be larger than the number of nodes in the underlying Cassandra cluster.

•	properties: This group is for storing information about the tenant such as company, organization, or license keys. Any property name and value can be used, however, property names cannot begin with an underscore (_).

•

users: This group is used to define an initial set of users. If this group is not present, an initial user is created with a random user ID and password and ALL permissions. When users are defined, a password must be provided. Optionally, a permissions can be specified, which is a comma-separated list of permission mnemonics. If no permissions are defined, ALL is assigned by default. Currently, the following permissions are supported:

•	ALL: This permission allows the user to perform all commands on all applications within the tenant.

•	APPEND: This permission restricts the user to POST commands.

•	UPDATE: This permission allows the user to perform PUT and POST commands.

•	READ: This permission allows the user to perform GET commands.

When a POST /_tenants command is received, the following occurs:

•	A new tenant is created with the given name.

•	If no tenant users are specified, a new user is created for the tenant with a random user ID, random password, and ALL permissions.

•	A new Cassandra keyspace is created using the tenant name. If the option ReplicationFactor is specified, it is used for the new keyspace. All other defaults come from the doradus.yaml parameter ks_defaults.

•	CQL commands are issued to create all new tenant user IDs/passwords. Each Cassandra user is named {tenant}_{user} so that user names are unique across tenants. The Cassandra user can be used for direct access to Cassandra.

•	The keyspace is initialized with Doradus metadata ColumnFamilies (Applications and Tasks).

•	The tenant’s definition is written to the Applications CF so it can be recovered if needed.

The POST command returns the new tenant’s full definition, including name; user IDs, passwords, and permissions; properties; and options, using the same document format shown above. The response also includes the system-assigned _CreatedOn property, which is a timestamp documenting when the tenant was created. Example:

<tenant name="HelloKitty">

<options>

<option name="ReplicationFactor">3</option>

</options>

<properties>

<property name="Owner_Organization">Cats, LLC</property>

<property name="_CreatedOn">2015-06-17 15:41:40</property>

</properties>

<users>

<user name="Katniss" password="Everdeen">

<permissions>APPEND</permissions>

</user>

<user name="Asparagus" password="Gus">

<permissions>APPEND</permissions>

</user>

<user name="Skimbleshanks" password="Skanks">

<permissions>READ</permissions>

</user>

</users>

</tenant>

If the tenant is modified, the _CreatedOn property can be specified but must match the existing value.

If a create tenant command is received but the given tenant name already exists, a 409 Conflict response is returned. This prevents the accidental creation of a new tenant using a name already used.