Tenants

Object Overview

View is a multi-tenant system allowing you to configure separate virtual deployments within the same physical deployment. Objects other than nodes refer to a specific tenant by GUID, meaning users in one tenant have no access rights to data in another tenant.

Endpoint, URL, and Supported Methods

Objects are managed via the configuration server API at [http|https]://[hostname]:[port]/v1.0/tenants

By default, the configuration server is accessible on port 8601.

Supported methods include: GET HEAD PUT DELETE

Structure

Objects have the following structure:

{
    "GUID": "f4f4fd06-20a1-4e72-9713-0a3732cc986a",
    "Name": "Default Tenant",
    "Region": "us-west-1",
    "S3BaseDomain": "localhost",
    "RestBaseDomain": "localhost",
    "DefaultPoolGUID": "df6c9117-a1ea-44ca-bddc-fa7a3d932fe9",
    "Active": true,
    "CreatedUtc": "2024-07-10T05:09:31.000000Z"
}

Properties:

• GUID string globally unique identifier for the object
• Name string name for the object
• Region string S3 region string
• S3BaseDomain string the hostname on which View should listen for S3 requests for this tenant
• RestBaseDomain string the hostname on which View should listen for REST storage requests for this tenant
• DefaultPoolGUID string the default storage pool GUID to which new buckets should be mapped by default
• Active bool indicates whether or not the tenant is considered active and able to be used
• CreatedUtc datetime timestamp from creation, in UTC time

Create

To create, call PUT /v1.0/tenants with the following properties using the configuration server: Name Region S3BaseDomain RestBaseDomain DefaultPoolGUID

Note: DefaultPoolGUID can be set to null when creating. It is recommended that after creating a tenant, you create its storage pool, and update the tenant object with the storage pool's GUID. The result will be the created object.

curl -X PUT http://localhost:8601/v1.0/tenants \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer [accesskey]" \
     -d '
{
  "Name": "My tenant",
  "Region": "us-west-1",
  "S3BaseDomain": "localhost",
  "RestBaseDomain": "localhost",
  "DefaultPoolGUID": "df6c9117-a1ea-44ca-bddc-fa7a3d932fe9"
}'

Enumerate

Refer to the Enumeration page in REST API for details about the use of enumeration APIs.

Enumerate objects by using GET /v2.0/tenants. The resultant object will appear as:

{
    "Success": true,
    "Timestamp": {
        "Start": "2024-10-21T02:36:37.677751Z",
        "TotalMs": 23.58,
        "Messages": {}
    },
    "MaxResults": 10,
    "IterationsRequired": 1,
    "EndOfResults": true,
    "RecordsRemaining": 16,
    "Objects": [
        {
            "GUID": "example-tenant",
            ... tenant details ...
        },
        { ... }
    ],
    "ContinuationToken": "[continuation-token]"
}

Read

To read an object by GUID, call GET /v1.0/tenants/[tenant-guid]. If the object exists, it will be returned as a JSON object in the response body. If it does not exist, a 404 will be returned with a NotFound error response.

{
    "GUID": "default",
    "Name": "Default Tenant",
    "Region": "us-west-1",
    "S3BaseDomain": "localhost",
    "RestBaseDomain": "localhost",
    "DefaultPoolGUID": "default",
    "Active": true,
    "CreatedUtc": "2024-07-10T05:09:31.000000Z"
}

Note: the HEAD method can be used as an alternative to get to simply check the existence of the object. HEAD requests return either a 200/OK in the event the object exists, or a 404/Not Found if not. No response body is returned with a HEAD request.

Update

To update an object by GUID, call PUT /v1.0/tenants/[tenant-guid] with a fully populated object in the request body. The updated object will be returned to you.

Note: certain fields cannot be modified and will be preserved across updates.

Request body:

{
    "GUID": "default",
    "Name": "My Updated Tenant",
    "Region": "us-west-1",
    "S3BaseDomain": "localhost",
    "RestBaseDomain": "localhost",
    "DefaultPoolGUID": "default",
    "Active": true,
    "CreatedUtc": "2024-07-10T05:09:31.000000Z"
}

Response body:

{
    "GUID": "default",
    "Name": "My Updated Tenant",
    "Region": "us-west-1",
    "S3BaseDomain": "localhost",
    "RestBaseDomain": "localhost",
    "DefaultPoolGUID": "default",
    "Active": true,
    "CreatedUtc": "2024-07-10T05:09:31.000000Z"
}

Delete

To delete an object by GUID, call DELETE /v1.0/tenants/[tenant-guid]. Note that deletion of a tenant does not delete subordinate data, as it may be preferred to retain it for later use. If you wish to entirely delete a tenant, delete subordinate data as described by other APIs.