stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
main
git.stella-ops.org/docs/modules/release-orchestrator/api/agents.md

5.6 KiB
Raw Permalink Blame History

Agent APIs

API endpoints for agent registration, lifecycle management, and task coordination.

Status: Planned (not yet implemented) Source: Architecture Advisory Section 6.3.2 Related Modules: Agents Module, Agent Security

Overview

The Agent API provides endpoints for registering deployment agents, managing their lifecycle, and coordinating task execution. Agents use mTLS for secure communication after initial registration.

Registration Endpoints

Register Agent

Endpoint: POST /api/v1/agents/register

Registers a new agent with the orchestrator. Requires a one-time registration token.

Headers:

X-Agent-Token: {registration-token}

Request:

{
  "name": "agent-prod-01",
  "version": "1.0.0",
  "capabilities": ["docker", "compose"],
  "labels": {
    "datacenter": "us-east-1",
    "role": "deployment"
  }
}

Response: 201 Created

{
  "agentId": "uuid",
  "token": "jwt-token-for-subsequent-requests",
  "config": {
    "heartbeatInterval": 30,
    "taskPollInterval": 5,
    "logLevel": "info"
  },
  "certificate": {
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN PRIVATE KEY-----...",
    "ca": "-----BEGIN CERTIFICATE-----...",
    "expiresAt": "2026-01-11T14:23:45Z"
  }
}

Notes:

  • Registration token is single-use and expires after 24 hours
  • After registration, agent must use mTLS for all subsequent requests
  • Certificate is short-lived (24h) and must be renewed via heartbeat

Lifecycle Endpoints

List Agents

Endpoint: GET /api/v1/agents

Query Parameters:

  • status (string): Filter by status (online, offline, degraded)
  • capability (string): Filter by capability (docker, compose, ssh, winrm, ecs, nomad)

Response: 200 OK

[
  {
    "id": "uuid",
    "name": "agent-prod-01",
    "version": "1.0.0",
    "status": "online",
    "capabilities": ["docker", "compose"],
    "lastHeartbeat": "2026-01-10T14:23:45Z",
    "resourceUsage": {
      "cpu": 15.5,
      "memory": 45.2
    }
  }
]

Get Agent

Endpoint: GET /api/v1/agents/{id}

Response: 200 OK - Full agent details including assigned targets

Update Agent

Endpoint: PUT /api/v1/agents/{id}

Request:

{
  "labels": {
    "datacenter": "us-west-2"
  },
  "capabilities": ["docker", "compose", "ssh"]
}

Response: 200 OK - Updated agent

Delete Agent

Endpoint: DELETE /api/v1/agents/{id}

Revokes agent credentials and removes registration.

Response: 200 OK

{ "deleted": true }

Heartbeat Endpoints

Send Heartbeat

Endpoint: POST /api/v1/agents/{id}/heartbeat

Agents must send heartbeats at the configured interval to maintain online status and receive pending tasks.

Request:

{
  "status": "healthy",
  "resourceUsage": {
    "cpu": 15.5,
    "memory": 45.2,
    "disk": 60.0
  },
  "capabilities": ["docker", "compose"],
  "runningTasks": 2
}

Response: 200 OK

{
  "tasks": [
    {
      "taskId": "uuid",
      "taskType": "docker.pull",
      "payload": {
        "image": "myapp",
        "tag": "v2.3.1",
        "digest": "sha256:abc123..."
      },
      "credentials": {
        "registry.username": "user",
        "registry.password": "token"
      },
      "timeout": 300
    }
  ],
  "certificateRenewal": {
    "cert": "-----BEGIN CERTIFICATE-----...",
    "expiresAt": "2026-01-11T14:23:45Z"
  }
}

Notes:

  • Certificate renewal is included when current certificate is within 1 hour of expiration
  • Tasks array contains pending work for the agent
  • Missing heartbeats for 3 intervals marks agent as offline

Task Endpoints

Complete Task

Endpoint: POST /api/v1/agents/{id}/tasks/{taskId}/complete

Reports task completion status back to the orchestrator.

Request:

{
  "success": true,
  "result": {
    "imageId": "sha256:abc123...",
    "containerId": "container-uuid"
  },
  "logs": [
    { "timestamp": "2026-01-10T14:23:45Z", "level": "info", "message": "Pulling image..." },
    { "timestamp": "2026-01-10T14:23:50Z", "level": "info", "message": "Image pulled successfully" }
  ]
}

Response: 200 OK

{ "acknowledged": true }

Get Pending Tasks

Endpoint: GET /api/v1/agents/{id}/tasks

Alternative to heartbeat for polling pending tasks.

Response: 200 OK

{
  "tasks": [
    {
      "taskId": "uuid",
      "taskType": "docker.run",
      "priority": 10,
      "createdAt": "2026-01-10T14:20:00Z"
    }
  ]
}

WebSocket Endpoints

Task Stream

Endpoint: WS /api/v1/agents/{id}/task-stream

Real-time task assignment stream for agents.

Messages (Server to Agent):

{ "type": "task_assigned", "task": { "taskId": "uuid", "taskType": "docker.pull", ... } }
{ "type": "task_cancelled", "taskId": "uuid" }

Messages (Agent to Server):

{ "type": "task_progress", "taskId": "uuid", "progress": 50, "message": "Pulling layer 3/5" }
{ "type": "task_log", "taskId": "uuid", "level": "info", "message": "..." }

Error Responses

Status Code Description
401 Invalid or expired registration token
403 Agent not authorized for this operation
404 Agent not found
409 Agent name already registered
503 Agent offline or unreachable

See Also