Skip to main content

Tenants

A tenant is a separate space for your data, with its own entities, temporal history, subscriptions and registrations. You pick one with the NGSILD-Tenant header. Leave the header out and you get the default tenant, which always exists.

You never create a tenant on its own. A tenant comes into being the first time a write stores something under its name. Until then, every other request to it gets an error.

Creating a tenant​

Write to it. Once one of the creating operations below succeeds, the tenant exists and every later request finds it.

POST /ngsi-ld/v1/entities
Content-Type: application/json
NGSILD-Tenant: acme

{
    "id": "urn:ngsi-ld:Building:1",
    "type": "Building"
}
HTTP/1.1 201 Created
Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Building:1

These operations create a tenant when they succeed:

  • Create Entity
  • Batch Entity Creation
  • Create or Update Temporal Evolution of an Entity
  • Create Subscription
  • Register Context Source
  • Create Context Source Registration Subscription

A refused write stores nothing, so it doesn't create a tenant either. The cause doesn't matter. A 400 for a bad identifier, a 504 because an @context couldn't be fetched, and a batch where every entity failed all leave no tenant behind.

The same rule has a side effect. A successful write under a mistyped header creates the mistyped tenant as well. If acme-stagng gets a write that succeeds, that tenant now exists, and the stray data sits there until someone removes it.

Using a tenant that does not exist​

Reads, updates, deletes and every other operation get 404 NonexistentTenant:

GET /ngsi-ld/v1/entities/urn:ngsi-ld:Building:1
NGSILD-Tenant: acme-staging
HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "type": "https://uri.etsi.org/ngsi-ld/errors/NonexistentTenant",
    ...
}

The tenant management endpoints answer the same way when that extension is on. They never list a tenant that doesn't exist.

A request racing the first write​

A request can arrive while the first write to a new tenant is still running. If the broker admits it before that write has stored anything, it gets NonexistentTenant. Given the order the two requests arrived in, that is the correct answer.

An interrupted setup​

If the very first request to a new tenant gets 503 with a Retry-After header, the broker was interrupted while it was setting the tenant up. Send the request again.

Tenant names​

A tenant name matches [A-Za-z_][A-Za-z0-9_-]* and is at most 1,005 octets long. Anything else is refused with 400 BadRequestData. Andromeda's own bounds explains where those numbers come from.

Configuration​

  • tenancy.mode (default "enabled"): with "disabled", the broker has only the default tenant, and any request carrying NGSILD-Tenant gets 501 NoMultiTenantSupport.

Where Andromeda interprets the specification​

Tenants are defined by the specification, and so is the header. A broker may create tenants implicitly on first write, and the specification lists the operations that do. The NonexistentTenant and NoMultiTenantSupport errors are in the status table.

Last updated on