Skip to content
NebulaCtrlInstall

Reference

View as Markdown

Instance services API

6 operations. Every call needs a session cookie or an Authorization: Bearer nct_… token unless marked Public. Conventions, errors and scopes

GET/admin/instance-services

Built-in services: health, default quota and every team's slice

Instance administrator only (403 instance_admin_required). S3 holds NebulaCtrl's own data (backups), the registry the teams' images, Loki their central logs. Each team has a slice of each; slices of deleted teams stay until purgeAt. No key, bucket or address is returned.

Response 200 · OK · application/json
InstanceServicesView
  • defaultQuotaBytesinteger (int64)required
    The S3 quota of every team without its own
  • InstanceServiceView[] | nullrequired
  • SliceView[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbiddeninstance_admin_required
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PUT/admin/instance-services

Set the default S3 quota of the teams

Instance administrator only. The default applies to every team without its own quota (50 GiB until changed); the minimum is 1 GiB (422 quota_too_small). Lowering it below what a team already uses only blocks that team's new backups: nothing is deleted. Audited.

Request body · application/json · required
UpdateServicesInputBody
  • defaultQuotaBytesinteger (int64)required
    The S3 quota of every team without its own, in bytes. At least 1 GiB.
Response 200 · OK · application/json
InstanceServicesView
  • defaultQuotaBytesinteger (int64)required
    The S3 quota of every team without its own
  • InstanceServiceView[] | nullrequired
  • SliceView[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entityquota_too_small
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/admin/instance-services/check

Check the built-in services now

Instance administrator only. Runs the same check as the minute-by-minute one: health of each service, the system bucket, and a slice for every team that lacks one.

Response 200 · OK · application/json
InstanceServicesView
  • defaultQuotaBytesinteger (int64)required
    The S3 quota of every team without its own
  • InstanceServiceView[] | nullrequired
  • SliceView[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PUT/admin/team-slices/{sliceId}/quota

Set one team's S3 quota

Instance administrator only. quotaBytes null resets the team to the instance default. Only the S3 slice has a quota (422 quota_not_supported). Lowering it below use only blocks new backups; existing backups are never deleted to make room. Audited.

ParameterInTypeDescription
sliceIdrequiredpathstring
Request body · application/json · required
SliceQuotaInputBody
  • quotaBytesinteger (int64) | nullrequired
    The team's own quota in bytes, at least 1 GiB; null resets it to the instance default.
Response 200 · OK · application/json
SliceView
  • deletedAtstring (date-time) | nullrequired
    Set when the team was deleted; the slice is purged at purgeAt
  • effectiveQuotaBytesinteger (int64)required
    The quota that applies (s3); 0 for kinds without a quota
  • idstringrequired
  • kindenum: s3 | registry | lokirequired
  • messagestringrequired
    Why the slice is failed; empty otherwise
  • purgeAtstring (date-time) | nullrequired
  • quotaBytesinteger (int64) | nullrequired
    The team's own quota; null = the instance default (s3 only)
  • stateenum: provisioning | ready | full | failedrequired
  • teamIdstringrequired
  • teamNamestringrequired
  • usedBytesinteger (int64)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Unprocessable Entityquota_not_supported
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

DELETE/admin/team-slices/{teamId}

Purge a deleted team's slices now

Instance administrator only. Deletes the bucket, its key, the registry images and the logs of a team that was deleted, instead of waiting for the 30 days. confirm is the team's name. 409 team_still_exists while the team exists, 404 when it has no slices left, 422 confirmation_mismatch. Audited.

ParameterInTypeDescription
teamIdrequiredpathstring
confirmquerystringThe deleted team's name, as the slice table shows it.
Response 204 · No Content

No body.

Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflictteam_still_exists
  • 422Unprocessable Entityconfirmation_mismatch
  • 500Internal Server Error
  • 502Bad Gateway

Errors are RFC 9457 application/problem+json with a stable code field.

GET/team-slice

The team's built-in backup storage, registry and logs

Used space and quota of the team's built-in backup storage, the size of its registry images and the log retention. Never a key, bucket, repository prefix or address: the services are managed by the instance administrator.

Response 200 · OK · application/json
TeamSliceView
  • BackupSliceViewrequired
  • LogsSliceViewrequired
  • RegistrySliceViewrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.