Skip to content
NebulaCtrlInstall

Reference

View as Markdown

Instance API

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

GET/instance/backup

Get the control-plane backup settings

A scheduled pg_dump of NebulaCtrl's own database to one instance-wide destination. The instance secret key is never part of a backup. Instance admin only.

Response 200 · OK · application/json
InstanceBackupView
  • InstanceDestinationViewrequired
  • enabledbooleanrequired
  • keyAcknowledgedAtstring (date-time)
    When an admin confirmed the instance secret key is stored separately. The reminder card shows until then.
  • keyFingerprintstringrequired
  • InstanceRunView
  • lastSuccessAtstring (date-time)
  • localDirEnabledbooleanrequired
    False when NEBULACTRL_BACKUP_DIR is not set: local directory destinations are unavailable.
  • nextRunAtstring (date-time)
  • retentionCountinteger (int64)required
    Successful backups kept (the newest is never removed).
  • schedulestringrequired
    5-field cron expression, evaluated in UTC.
  • toolsAvailablebooleanrequired
    False when pg_dump is missing on the control-plane host: backups can not run.
  • toolsMessagestring
  • updatedAtstring (date-time)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 500Internal Server Error

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

PATCH/instance/backup

Update the control-plane backup settings

Credentials are write-only. Enabling needs a complete destination. Instance admin only.

Request body · application/json · required
PatchInstanceBackupInputBody
  • accessKeystring
    Write-only. Omit or leave empty to keep the stored key.
  • bucketstring
  • compatModeboolean
  • enabledboolean
    Run the schedule. Needs a complete destination.
  • endpointstring
    S3-compatible endpoint URL; empty means AWS S3.
  • kindenum: s3 | local
    Changing the kind starts the destination afresh.
  • localDirstring
    Local destinations: relative sub-directory of NEBULACTRL_BACKUP_DIR.
  • pathStyleboolean
  • prefixstring
    Key prefix inside the bucket or directory.
  • regionstring
  • retentionCountinteger (int64)
    Successful backups kept (default 14).
  • schedulestring
    5-field cron expression or @daily etc., evaluated in UTC (default 30 3 * * *). At most one run every 5 minutes.
  • secretKeystring
    Write-only. Omit or leave empty to keep the stored key.
Response 200 · OK · application/json
InstanceBackupView
  • InstanceDestinationViewrequired
  • enabledbooleanrequired
  • keyAcknowledgedAtstring (date-time)
    When an admin confirmed the instance secret key is stored separately. The reminder card shows until then.
  • keyFingerprintstringrequired
  • InstanceRunView
  • lastSuccessAtstring (date-time)
  • localDirEnabledbooleanrequired
    False when NEBULACTRL_BACKUP_DIR is not set: local directory destinations are unavailable.
  • nextRunAtstring (date-time)
  • retentionCountinteger (int64)required
    Successful backups kept (the newest is never removed).
  • schedulestringrequired
    5-field cron expression, evaluated in UTC.
  • toolsAvailablebooleanrequired
    False when pg_dump is missing on the control-plane host: backups can not run.
  • toolsMessagestring
  • updatedAtstring (date-time)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

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

POST/instance/backup/key-acknowledgement

Confirm the instance secret key is stored separately

Dismisses the reminder card. Backups do not contain NEBULACTRL_SECRET_KEY, and a restore is useless without it: store it in a password manager or vault, apart from the backups.

Response 200 · OK · application/json
InstanceBackupView
  • InstanceDestinationViewrequired
  • enabledbooleanrequired
  • keyAcknowledgedAtstring (date-time)
    When an admin confirmed the instance secret key is stored separately. The reminder card shows until then.
  • keyFingerprintstringrequired
  • InstanceRunView
  • lastSuccessAtstring (date-time)
  • localDirEnabledbooleanrequired
    False when NEBULACTRL_BACKUP_DIR is not set: local directory destinations are unavailable.
  • nextRunAtstring (date-time)
  • retentionCountinteger (int64)required
    Successful backups kept (the newest is never removed).
  • schedulestringrequired
    5-field cron expression, evaluated in UTC.
  • toolsAvailablebooleanrequired
    False when pg_dump is missing on the control-plane host: backups can not run.
  • toolsMessagestring
  • updatedAtstring (date-time)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 500Internal Server Error

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

GET/instance/backup/runs

List control-plane backup runs

ParameterInTypeDescription
limitqueryinteger (int64)
Response 200 · OK · application/json
InstanceRunListOutputBody
  • InstanceRunView[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

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

POST/instance/backup/runs

Back up the control plane now

Returns 202 with the running backup; poll the runs or listen for instance.backup.updated events. 409 backup_in_progress while one is running.

ParameterInTypeDescription
Idempotency-KeyheaderstringClient-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours.
Response 202 · Accepted · application/json
InstanceRunView
  • actorLabelstring
  • destKindenum: s3 | localrequired
  • destinationstringrequired
    Where the backup was written.
  • errorstring
  • finishedAtstring (date-time)
  • idstringrequired
  • objectDeletedbooleanrequired
    Retention removed the stored objects; the row stays as history.
  • objectKeystring
  • pgVersionstring
  • sha256string
  • sizeBytesinteger (int64)required
  • startedAtstring (date-time)required
  • statusenum: running | succeeded | failedrequired
  • triggerenum: schedule | manual | pre_upgraderequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 409Conflictbackup_in_progress
  • 422Unprocessable Entity
  • 500Internal Server Error

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

POST/instance/backup/test

Test the control-plane backup destination

The control plane writes, reads back and deletes a probe object. The verdict is stored on the settings.

Response 200 · OK · application/json
InstanceBackupView
  • InstanceDestinationViewrequired
  • enabledbooleanrequired
  • keyAcknowledgedAtstring (date-time)
    When an admin confirmed the instance secret key is stored separately. The reminder card shows until then.
  • keyFingerprintstringrequired
  • InstanceRunView
  • lastSuccessAtstring (date-time)
  • localDirEnabledbooleanrequired
    False when NEBULACTRL_BACKUP_DIR is not set: local directory destinations are unavailable.
  • nextRunAtstring (date-time)
  • retentionCountinteger (int64)required
    Successful backups kept (the newest is never removed).
  • schedulestringrequired
    5-field cron expression, evaluated in UTC.
  • toolsAvailablebooleanrequired
    False when pg_dump is missing on the control-plane host: backups can not run.
  • toolsMessagestring
  • updatedAtstring (date-time)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

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

GET/instance/dashboard-access

Get the dashboard access settings

Who may reach the dashboard's hostname (an IP allow list on its system route) and how its certificate is issued (automatic HTTP-01 or a DNS-01 resolver of the control-plane server). clientIp is the caller's address as the allow list sees it. Instance admin only.

Response 200 · OK · application/json
DashboardAccessView
  • allowCidrsstring[] | nullrequired
  • DashboardCertificaterequired
  • clientIpstringrequired
    The caller's address as the dashboard route's allow list sees it. Empty when it cannot be determined
  • clientIpAllowedbooleanrequired
    The current allow list admits clientIp (always true while it is empty or the caller does not come through the route)
  • dnsResolverstringrequired
    DNS-01 provider of the certificate; empty is automatic HTTP-01
  • enabledbooleanrequired
    The dashboard has a system route (an https public URL with a DNS name, installer layout). false: nothing to restrict
  • hoststringrequired
    The dashboard's hostname
  • proxyDeployRequiredbooleanrequired
  • proxyServerIdstringrequired
    The control-plane server, where Deploy proxy lives
  • DashboardResolverOption[] | nullrequired
    Providers with a resolver on the control-plane server (Servers, Proxy)
  • sourceenum: default | installer | adminrequired
    Where the stored settings come from. installer: seeded from the installer's environment and still overwritten by it on restart; admin: saved here, the installer's environment is ignored
  • updatedAtstring (date-time) | nullrequired
  • viaDashboardRoutebooleanrequired
    The caller reached the control plane through the dashboard route, so the allow list applies to them
Errors
  • 401Unauthorized
  • 403Forbidden
  • 500Internal Server Error

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

PUT/instance/dashboard-access

Update the dashboard access settings

Replaces the allow list and the certificate method and re-sends the control-plane server's routes: an allow list applies immediately. Agents on other servers and webhooks reach the control plane through the same hostname, so keep their addresses in the list. 409 dashboard_lockout when a non-empty list excludes the caller's current address, unless confirmLockout is true. 422 resolver_not_configured when the control-plane server has no resolver of that provider. A resolver that is staged but not applied yet sets proxyDeployRequired: the dashboard keeps its HTTP-01 certificate until Deploy proxy. 409 dashboard_route_disabled when the dashboard has no system route. Instance admin only.

Request body · application/json · required
UpdateDashboardAccessInputBody
  • allowCidrsstring[] | nullrequired
    CIDRs or single addresses (IPv4 or IPv6) allowed to reach the dashboard. Empty lifts the restriction.
  • confirmLockoutboolean
    Save even though allowCidrs excludes the caller's current address (otherwise 409 dashboard_lockout).
  • dnsResolverstring
    DNS-01 provider of the dashboard's certificate (a resolver the control-plane server already has, see resolverAvailable). Empty is automatic HTTP-01.
Response 200 · OK · application/json
DashboardAccessView
  • allowCidrsstring[] | nullrequired
  • DashboardCertificaterequired
  • clientIpstringrequired
    The caller's address as the dashboard route's allow list sees it. Empty when it cannot be determined
  • clientIpAllowedbooleanrequired
    The current allow list admits clientIp (always true while it is empty or the caller does not come through the route)
  • dnsResolverstringrequired
    DNS-01 provider of the certificate; empty is automatic HTTP-01
  • enabledbooleanrequired
    The dashboard has a system route (an https public URL with a DNS name, installer layout). false: nothing to restrict
  • hoststringrequired
    The dashboard's hostname
  • proxyDeployRequiredbooleanrequired
  • proxyServerIdstringrequired
    The control-plane server, where Deploy proxy lives
  • DashboardResolverOption[] | nullrequired
    Providers with a resolver on the control-plane server (Servers, Proxy)
  • sourceenum: default | installer | adminrequired
    Where the stored settings come from. installer: seeded from the installer's environment and still overwritten by it on restart; admin: saved here, the installer's environment is ignored
  • updatedAtstring (date-time) | nullrequired
  • viaDashboardRoutebooleanrequired
    The caller reached the control plane through the dashboard route, so the allow list applies to them
Errors
  • 401Unauthorized
  • 403Forbidden
  • 409Conflictdashboard_lockoutdashboard_route_disabled
  • 422Unprocessable Entityresolver_not_configured
  • 500Internal Server Error

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