Skip to main content

Tenant management

List your tenants, look at one, and take one out of service and back again, over the API. PATCH /ngsi-ld/v1/tenants/acme with {"isActive": false} suspends the tenant acme. Off by default.

At a glance​

Turning it on​

[extensions.tenant_management]
mode = "enabled"

Using it​

GET /ngsi-ld/v1/tenants/acme
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "urn:ngsi-ld:Tenant:acme",
    "type": "Tenant",
    "tenantName": "acme",
    "isActive": true,
    "status": "active"
}

The operations​

  • GET /ngsi-ld/v1/tenants

    Every tenant, as a JSON array of Tenant resources in name order, paged like every collection (see Pagination). NGSILD-Results-Count always gives the total.

  • GET /ngsi-ld/v1/tenants/{tenantName}

    One tenant. An unknown tenant gets 404 NonexistentTenant.

  • PATCH /ngsi-ld/v1/tenants/{tenantName}

    Suspend or resume the tenant by setting isActive. A status in the body is ignored. The answer is 204, or 404 NonexistentTenant for an unknown tenant.

The tenant resource​

A tenant's identifier is urn:ngsi-ld:Tenant:{tenantName}. Tenant resources are plain JSON and are never expanded against an @context, so their members are Andromeda's own names and can't be mistaken for NGSI-LD core terms.

isActive is yours to set. status is worked out by Andromeda, and also tells you whether the tenant is loaded right now:

  • active: in service, and loaded in this broker.
  • dormant: in service, but not loaded at the moment. Its next request loads it again.
  • suspended: out of service.

A plain read never touches the tenant's database, so it doesn't wake a dormant tenant. Ask for more with options:

  • options=sysAttrs adds createdAt and modifiedAt.
  • options=usage adds databaseName (the PostgreSQL database holding the tenant, the name it also has on a pooler), poolConnections, databaseSize (in bytes), entityCount, snapshotCount, and snapshotQuota when a Snapshot count limit is configured. This one queries the tenant's database.

On the list, options applies to every tenant on the page.

Suspending and resuming​

PATCH with {"isActive": false} suspends a tenant. Andromeda unloads it straight away and closes its database connections once the requests already running on it finish. While it is suspended:

  • Every NGSI-LD request to it gets 404 NonexistentTenant, worded so a suspended tenant can't be told apart from one that doesn't exist.
  • Its background work stops: no periodic notifications, no delivery retries.
  • The management API still tells the truth. GET /ngsi-ld/v1/tenants/{tenantName} returns "isActive": false and "status": "suspended".

PATCH with {"isActive": true} resumes it, and its next request loads it as usual. Suspending doesn't touch the tenant's database, so everything written before is still there afterwards.

Deleting a tenant​

There's no API call for it, on purpose. Dropping a database can't be undone, so Andromeda doesn't offer it over HTTP. To reclaim a tenant's storage, suspend it first so its connections close, then drop its database yourself. The only database Andromeda drops on its own is that of a provisional tenant that never held anything (see Tenants under operations).

What gets refused​

  • 400 for a tenant name longer than 1,005 octets

    BadRequestData in the NGSILD-Tenant header, InvalidRequest in the {tenantName} path segment. The limit is the 1,024-octet identifier limit minus the 19 octets of urn:ngsi-ld:Tenant:.

  • 400 InvalidRequest for an unknown options keyword

    Use sysAttrs or usage.

Context sources​

Tenant management isn't forwarded. Each broker manages its own tenants.

Why it is an extension​

The specification defines the NGSILD-Tenant header, isolation between tenants and creating a tenant on first write (see Tenants). It leaves managing tenants to the implementation.

The isActive and status pair copies the way a Subscription pairs them. A suspended tenant answers like a missing one, and unknown options are refused.

Last updated on