Documentation Reference REST API reference API: tenants Reference For: developers
API: tenants
Operations of the tenants tag of the native REST API.
Multi-tenant self-service (docs/cloud/SELF_SERVICE.md section 2): tenants with their folders and pools, quota, suspend/resume/close, tenant users and API tokens, monthly usage
GET /v1/tenantsEvery tenant (Kyvernon.Tenant.Read).
CLI kyvernon tenants listResponses
Status Description Schema 200 OK array of TenantView 403 Permission denied; args.privilege names the missing privilege ErrorBody
POST /v1/tenantsCreates a tenant: a folder Tenants/<name> per datacenter and a resource pool per cluster (Kyvernon.Tenant.Create).
CLI kyvernon tenants create <name>Request body
application/json: CreateTenantRequest
Name Type Required Description anchorDayinteger (int32) or nullDay of the month (1 to 28) the traffic period starts (default: the 1st). displayNamestringDisplay name. externalRefstringThe portal's account id. labelsobjectLabels. namestringyes Short name ([a-z0-9-], 1..=63), also the name of its folders and pools. quotaQuotaViewLimits (default: unlimited).
Responses
Status Description Schema 201 Created TenantView400 Invalid argument; the error body names the field ErrorBody409 Conflict: the object exists, or expectedVersion is stale ErrorBody
GET /v1/tenants/{tenant}One tenant with its quota and current use (operators, and the tenant's own users).
CLI kyvernon tenants get <tenant>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N)
Responses
POST /v1/tenants/{tenant}/closeCloses a tenant: VMs are powered off now and destroyed with their disks after the grace period; users cannot log in any more (Kyvernon.Tenant.Close).
CLI kyvernon tenants close <tenant>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N)
Request body
application/json: CloseTenantRequest
Name Type Required Description graceSecondsinteger (int64) or nullSeconds until VMs and disks are destroyed (default: the controller's [tenancy] close_grace, 7 days).
Responses
Status Description Schema 202 Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait) TaskRef412 Failed precondition; the error body says which ErrorBody
PUT /v1/tenants/{tenant}/quotaReplaces the quota (Kyvernon.Tenant.SetQuota); null is unlimited.
CLI kyvernon tenants quota <tenant> --body <json>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N)
Request body
application/json: QuotaView
Name Type Required Description diskGibinteger (int64) or nullDisk (GiB). fwGroupMembersinteger (int64) or nullFirewall group members (null: 1,000). fwGroupsinteger (int64) or nullFirewall groups (null: 100). fwPoliciesinteger (int64) or nullFirewall policies (null: 50). fwRulesinteger (int64) or nullFirewall rules (null: 500). memoryMibinteger (int64) or nullMemory (MiB). publicIpv4integer (int64) or nullPublic IPv4 addresses. snapshotsinteger (int64) or nullSnapshots. trafficGibMonthinteger (int64) or nullTraffic per month (GiB; enforced by the traffic accounting). vcpusinteger (int64) or nullvCPUs. vmsinteger (int64) or nullVMs.
Responses
POST /v1/tenants/{tenant}/resumeResumes a suspended tenant and starts the VMs that ran at suspend (Kyvernon.Tenant.Resume).
CLI kyvernon tenants resume <tenant>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N)
Responses
Status Description Schema 202 Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait) TaskRef412 Failed precondition; the error body says which ErrorBody
POST /v1/tenants/{tenant}/suspendSuspends a tenant: running VMs are shut down (through the guest, then hard) and their power state recorded; users become read-only; power-on and console are refused (Kyvernon.Tenant.Suspend).
CLI kyvernon tenants suspend <tenant>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N)
Responses
Status Description Schema 202 Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait) TaskRef412 Failed precondition; the error body says which ErrorBody
GET /v1/tenants/{tenant}/usageUsage of a month per server: hours per plan (proration over a resize), snapshot GiB-hours, and the network side's traffic and extra-IP figures (Kyvernon.Usage.Read on the tenant).
CLI kyvernon tenants usage <tenant>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N) monthquery string or nullYYYY-MM (UTC; default: the current month, up to now).
Responses
GET /v1/tenants/{tenant}/usersThe tenant's accounts (Kyvernon.Tenant.ManageUsers on the tenant).
CLI kyvernon tenants users <tenant> listParameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N)
Responses
Status Description Schema 200 OK array of UserView 404 Not found (or not visible to the caller) ErrorBody
POST /v1/tenants/{tenant}/usersCreates an account of the tenant; its role (admin, user, read-only) is granted on the tenant's folders and pools only.
CLI kyvernon tenants users <tenant> create <username>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N)
Request body
application/json: CreateTenantUserRequest
Name Type Required Description displayNamestringDisplay name. emailstringE-mail. passwordstringyes Initial password. rolestringadmin (Tenant administrator), user (Tenant user) or read-only.rotationRequiredbooleanThe password must be changed at first login. serviceAccountbooleanAutomation account (API logins only). usernamestringyes Login name.
Responses
Status Description Schema 201 Created UserView400 Invalid argument; the error body names the field ErrorBody409 Conflict: the object exists, or expectedVersion is stale ErrorBody
DELETE /v1/tenants/{tenant}/users/{username}Deletes an account of the tenant.
CLI kyvernon tenants users <tenant> delete <username>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N) usernamepath stringyes User name of the account
Responses
Status Description Schema 204 Done; no body 404 Not found (or not visible to the caller) ErrorBody
GET /v1/tenants/{tenant}/users/{username}/api-tokensAPI tokens of a tenant account.
CLI kyvernon tenants users <tenant> api-tokens <username> listParameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N) usernamepath stringyes User name of the account
Responses
POST /v1/tenants/{tenant}/users/{username}/api-tokensCreates an API token for a tenant account (the token is shown once).
CLI kyvernon tenants users <tenant> api-tokens <username> create <name>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N) usernamepath stringyes User name of the account
Request body
application/json: CreateApiTokenRequest
Name Type Required Description namestringyes Label (1..=64 characters). ttlSecondsinteger (int64) or nullLifetime in seconds, 1 up to the controller maximum ([identity.policy] api_token_max_ttl, 365 days unless configured otherwise). Absent: the maximum. Every token expires; a longer lifetime is refused (error.api_token.ttl).
Responses
DELETE /v1/tenants/{tenant}/users/{username}/api-tokens/{id}Revokes an API token of a tenant account.
CLI kyvernon tenants users <tenant> api-tokens <username> delete <id>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N) usernamepath stringyes User name of the account idpath stringyes Id of the API token
Responses
Status Description Schema 204 Done; no body 404 Not found (or not visible to the caller) ErrorBody
Guides
Previous API: tasks Next API: traffic Version 0.1.