Skip to main content

Clusters

Manage Docker Swarm clusters with full node management, service monitoring, scaling, secrets, and configs.

Pro Feature

Cluster management requires a Pro license. Requests to these endpoints return 402 Payment Required on free instances.

List Clusters​

GET /api/v1/clusters

Response:

{
  "data": [
    {
      "uuid": "cl-abc123",
      "name": "Production Swarm",
      "type": "swarm",
      "status": "healthy",
      "node_count": 3,
      "service_count": 12,
      "created_at": "2024-03-01T10:00:00Z"
    }
  ]
}

Cluster Statuses​

StatusDescription
healthyAll manager nodes reachable
degradedSome nodes unreachable
unreachablePrimary manager not reachable

Get Cluster Details​

GET /api/v1/clusters/{uuid}

Returns full cluster metadata including Swarm ID, node counts by role, and service overview.

Auto-Detect Clusters​

Scan connected servers for existing Docker Swarm clusters:

POST /api/v1/clusters/detect

Response:

{
  "message": "Detection complete.",
  "clusters_found": 1,
  "data": [
    {
      "uuid": "cl-abc123",
      "name": "Production Swarm",
      "swarm_id": "swarm-xyz",
      "manager_count": 1,
      "worker_count": 2
    }
  ]
}

Auto-detection inspects docker info on all Swarm manager servers, extracts the Swarm ID, and creates or updates cluster records.

Node Management​

List Nodes​

GET /api/v1/clusters/{uuid}/nodes

Response:

{
  "data": [
    {
      "id": "node-abc123",
      "hostname": "manager-1",
      "role": "manager",
      "status": "ready",
      "availability": "active",
      "engine_version": "24.0.7",
      "ip": "195.201.xxx.xxx",
      "labels": {
        "region": "eu-central"
      }
    }
  ]
}

Drain Node​

Remove workloads from a node (for maintenance):

POST /api/v1/clusters/{uuid}/nodes/{nodeId}/drain

Response:

{
  "message": "Node drained. Running tasks will be rescheduled."
}

Activate Node​

Return a drained node to active status:

POST /api/v1/clusters/{uuid}/nodes/{nodeId}/activate

Promote Node​

Promote a worker to manager:

POST /api/v1/clusters/{uuid}/nodes/{nodeId}/promote

Demote Node​

Demote a manager to worker:

POST /api/v1/clusters/{uuid}/nodes/{nodeId}/demote

Update Node Labels​

PATCH /api/v1/clusters/{uuid}/nodes/{nodeId}/labels
{
  "labels": {
    "region": "eu-central",
    "tier": "production"
  }
}

Service Management​

List Services​

GET /api/v1/clusters/{uuid}/services

Response:

{
  "data": [
    {
      "id": "svc-abc123",
      "name": "web",
      "image": "myapp:latest",
      "replicas": "3/3",
      "ports": ["80:8080"],
      "updated_at": "2024-06-15T14:30:00Z"
    }
  ]
}

Scale Service​

POST /api/v1/clusters/{uuid}/services/{serviceId}/scale
{
  "replicas": 5
}

Response:

{
  "message": "Service scaled to 5 replicas."
}

Get Service Tasks​

GET /api/v1/clusters/{uuid}/services/{serviceId}/tasks

Returns the list of tasks (container instances) for a service, including their node placement and status.

Secrets​

List Secrets​

GET /api/v1/clusters/{uuid}/secrets

Create Secret​

POST /api/v1/clusters/{uuid}/secrets
{
  "name": "db_password",
  "data": "my-secret-value"
}

Delete Secret​

DELETE /api/v1/clusters/{uuid}/secrets/{secretId}

Configs​

List Configs​

GET /api/v1/clusters/{uuid}/configs

Create Config​

POST /api/v1/clusters/{uuid}/configs
{
  "name": "nginx_config",
  "data": "server { listen 80; ... }"
}

Delete Config​

DELETE /api/v1/clusters/{uuid}/configs/{configId}

Events​

List Cluster Events​

GET /api/v1/clusters/{uuid}/events
ParameterTypeDescription
sincestringISO 8601 timestamp to filter events after
limitintegerMaximum events to return (default: 50)

Returns a chronological list of cluster events (node joins/leaves, service updates, scaling operations).