Skip to content
NebulaCtrlInstall

Reference

View as Markdown

Fleet API

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

GET/fleet

Capacity and placement of every server

Per server: resource usage, the memory promised through service limits (committed), whether that exceeds the host, and the services placed on it (limited to the caller's projects).

Response 200 · OK · application/json
Overview
  • FleetServer[] | nullrequired
  • FleetTotalsrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 500Internal Server Error

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

GET/servers/{serverId}/drain

Progress of a server's drain

ParameterInTypeDescription
serverIdrequiredpathstring
Response 200 · OK · application/json
GetDrainOutputBody
  • DrainViewrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

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

POST/servers/{serverId}/drain

Drain a server

Marks the server as draining (nothing new is placed on it) and moves its services one at a time: each move changes the placement and deploys the service to the target; the old container is removed once the new one is live. The first failed move stops the drain and leaves the remaining services untouched. Scopes: servers:write, deployments:write, projects:write.

ParameterInTypeDescription
Idempotency-KeyheaderstringClient-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours.
serverIdrequiredpathstring
Request body · application/json · required
StartInputBody
  • confirmStatefulboolean
    Required when a moved service has volumes or is a database: their data is not copied
  • MoveBody[] | nullrequired
    Where every service on the server goes; each service must appear exactly once
Response 202 · Accepted · application/json
DrainView
  • actorLabelstringrequired
  • cancelRequestedbooleanrequired
  • createdAtstring (date-time)required
  • finishedAtstring (date-time) | nullrequired
  • idstringrequired
  • messagestringrequired
  • Move[] | nullrequired
  • serverIdstringrequired
  • stateenum: running | completed | failed | canceledrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

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

POST/servers/{serverId}/drain/cancel

Stop a drain after the move in flight

The drain ends after the current move. The server returns to none when nothing was moved yet, otherwise it becomes failed with "Canceled after N of M moves".

ParameterInTypeDescription
serverIdrequiredpathstring
Response 200 · OK · application/json
DrainView
  • actorLabelstringrequired
  • cancelRequestedbooleanrequired
  • createdAtstring (date-time)required
  • finishedAtstring (date-time) | nullrequired
  • idstringrequired
  • messagestringrequired
  • Move[] | nullrequired
  • serverIdstringrequired
  • stateenum: running | completed | failed | canceledrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

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

POST/servers/{serverId}/drain/plan

Plan evacuating a server

Dry run: proposes a target for every service on the server, flags stateful services (volumes are not copied), and checks that the targets have the memory. Requires a token that is not restricted to projects.

ParameterInTypeDescription
serverIdrequiredpathstring
Request body · application/json · required
PlanInputBody1
  • targetServerIdstring
    Send every service to this server; omit to pick the online server with the most free memory per service
Response 200 · OK · application/json
DrainPlan
  • Capacityrequired
  • PlanMove[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

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

POST/servers/{serverId}/undrain

Make a drained server schedulable again

Clears the drain state of a drained or failed-drain server. Services that were moved stay where they are.

ParameterInTypeDescription
serverIdrequiredpathstring
Response 200 · OK · application/json
Server
  • acceptWorkloadsbooleanrequired
    Whether services may be scheduled on this server. Turning it off keeps what already runs here and refuses new placements and moves.
  • acmeEmailstring | nullrequired
  • agentVersionstring | nullrequired
  • baseDomainstring | nullrequired
  • buildAllowEmulationbooleanrequired
    Allow building for another CPU architecture through emulation (slow); needs the agent to report emulation for the platform
  • buildAllowPreviewsbooleanrequired
    Allow pull request previews (untrusted code) to build here; off by default
  • buildEnabledbooleanrequired
    The server builds images for other servers and pushes them to a registry (the Builds or Both role). Independent of acceptWorkloads.
  • buildMaxConcurrentinteger (int64)required
    Builds that run at the same time; more queue on the control plane
  • composeVersionstringrequired
    Docker Compose plugin version the agent reported, empty when it has none
  • controlPlanebooleanrequired
    The host the installer put the control plane on; its proxy serves the dashboard
  • createdAtstring (date-time)required
  • diskAlertbooleanrequired
    True while the root filesystem is at or above the threshold
  • diskAlertThresholdPercentinteger (int64)required
    Root filesystem usage that raises the disk alert (50-99)
  • drainMessagestringrequired
    Why the last drain failed or was canceled, empty otherwise
  • drainStartedAtstring (date-time) | nullrequired
  • drainStateenum: none | draining | drained | failedrequired
    Evacuation state; draining and drained servers accept no new services
  • Factsrequired
  • geoEnabledbooleanrequired
    Count where requests come from (country, and city at the city level) from the client IP; IPs are never stored
  • geoLevelenum: country | cityrequired
    country needs a ~8 MB database on the server, city ~130 MB
  • geoRefreshDaysinteger (int64)required
    Check for a newer database every N days (1-90)
  • geoSourceenum: dbip | maxmindrequired
    dbip = DB-IP Lite (CC BY 4.0, no key); maxmind = MaxMind GeoLite2 with the team's account
  • idstringrequired
  • lastSeenAtstring (date-time) | nullrequired
  • Latestrequired
  • metricsRetentionDaysinteger (int64)required
    How long resource metric history is kept (1-90)
  • namestringrequired
  • ServerPatchSummaryrequired
  • protocolVersioninteger (int32) | nullrequired
  • Proxyrequired
  • publicIpstring | nullrequired
  • serviceCountinteger (int64)required
  • statusenum: pending | online | offline | revokedrequired
  • trafficAnalyticsEnabledbooleanrequired
    Aggregate Traefik access logs into traffic analytics
  • trafficDailyRetentionDaysinteger (int64)required
    Daily traffic history (7-365 days)
  • trafficHourlyRetentionDaysinteger (int64)required
    Hourly traffic history (2-90 days)
  • ServerTunnelSummaryrequired
  • unrestrictedbooleanrequired
    An instance admin made this server unrestricted: stacks and services on it may use privileged mode, host networking, devices, GPUs, a runtime, the host PID namespace, unconfined seccomp or AppArmor, NET_ADMIN, SYS_ADMIN, the Docker socket and host bind mounts
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

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