Managing Tenants

[Table of Contents](https://github.com/dell-oss/Doradus/wiki/Doradus Administration: Table-of-Contents) | [Previous](https://github.com/dell-oss/Doradus/wiki/Multi Tenant Operation) | [Next](https://github.com/dell-oss/Doradus/wiki/Application Commands in Multi-Tenant Mode)
[Multi-Tenant Configuration](https://github.com/dell-oss/Doradus/wiki/Multi-Tenant Configuration): Managing Tenants

---

The REST commands to create, modify, and delete tenants are considered privileged operations, hence they must be accompanied with valid super user credentials. REST commands use *basic authorization* (basic auth), which means credentials are passed using the `Authorization` header:

Authorization: Basic xxx

Where xxx is the user ID and password, separated by a colon, and then base64 encoded. For example, if the super user and password are cassandra:Cassandra, the header would look like this:

Authorization: Basic Y2Fzc2FuZHJhOmNhc3NhbmRyYQo=

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">
    <users>
        <user name="Katniss" password="Everdeen"/>
    </users>
    <options>
        <option name="ReplicationFactor">3</option>
    </options>
</tenant>

In JSON:

{"HelloKitty": {
	"users": {
		"Katniss": {"password": "Everdeen"}
	},
	"options": {
		"ReplicationFactor": "3"
	}
}}

Only the new tenant name (HelloKitty) is required. Optionally, one or more tenant user/password can be defined (e.g., Katniss/Everdeen) with a users group. A tenant options group is also allowed, though the only option currently supported is ReplicationFactor. When set, this option overrides the replication_factor defined with the ks_defaults parameter (in doradus.yaml).

When a POST /_tenants command is received, if the given tenant already exists, a 409 Conflict error response is returned. (This means tenant creation is not idempotent—a POST of the same request will produce an error.) If the tenant does not already exist, the following occurs:

• A new 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.

• If no tenant users are specified, a new random user ID and password are chosen for the tenant.

• CQL commands are issued to create all new tenant user IDs/passwords and authorize them for full access to the new keyspace. The 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 by creating the Applications and Tasks ColumnFamilies.

• 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 options using the same document format shown above.

List All Tenants

This command lists all existing tenants:

GET /_tenants

This command returns each tenant’s name and the list of applications owned by each tenant. An example response in XML is shown below:

<tenants>
	<tenant name="Doradus">
		<applications>
			<value>SmokeTest</value>
			<value>App_Default</value>
		</applications>
	</tenant>
	<tenant name="Bibliotecha">
		<applications>
			<value>App_Biblio</value>
		</applications>
	</tenant>
</tenants>

As with all REST commands, a JSON response can be requested by adding ?format=json to the URI. Example:

GET /_tenants?format=json

Which returns:

{"tenants": {
	"Doradus": {
		"applications": [
		"SmokeTest",
		"App_Default"
		]
	},
	"Bibliotecha": {
		"applications": [
		"App_Biblio"
		]
	}
}}

List Tenant

Details of a specific tenant can be listed with the following REST command:

GET /_tenants/{tenant}

Where {tenant} is the tenant name. This command returns all tenant details includes its name, the list all tenant user IDs and passwords, and any special options used to create the tenant. An example in XML is shown below:

<tenant name="Bibliotecha">
	<users>
		<user name="Uqyam0my7ivcm" password="r13dc42ppyu8"></user>
	</users>
</tenant>

Modify Tenant

An existing tenant can be modified via the following REST command:

PUT /_tenants/{tenant}

Where {tenant} is the tenant name. Currently, the only changed allowed are modifications to the tenant’s users: New users can be added and the password of existing users can be modified. The command must include an XML or JSON document with the same format used to create a tenant. Example:

<tenant>
	<users>
		<user name="Katniss" password="MockingJay"/>
		<user name="Rumpleteazer" password="Mongojerrie"/>
	</users>
</tenant>

In this example, the password for user Katniss is modified and a new user Rumpleteazer is added.

Delete Tenant

An existing tenant can be deleted via the following REST command:

DELETE /_tenants/{tenant}

Where {tenant} is the tenant name. No message body is provided in the command. The tenant’s keyspace, all of its applications, and of its data are deleted. (Note that Cassandra creates a snapshot of a CF when it is deleted, so the data is still recoverable for a while.)