SwarmCracker API Reference

gRPC API protocol between swarmd-firecracker and swarmcracker CLI / swarmctl.

Overview

SwarmCracker uses SwarmKit’s gRPC API via the github.com/moby/swarmkit/v2/api package, extended with a custom API versioning protocol (pkg/apiversion).

┌──────────────────┐       Unix Socket       ┌────────────────────────┐
│  swarmcracker    │ ───── gRPC (TLS) ────── │  swarmd-firecracker    │
│  swarmctl        │   /var/run/swarmkit/     │  (manager/worker)      │
│                  │       swarm.sock         │                        │
└────────┬─────────┘                          └───────────┬────────────┘
         │                                                 │
         │  X-SwarmCracker-Version: 1                       │
         │  (gRPC metadata interceptor)                     │
         └─────────────────────────────────────────────────┘

Connection

Control Socket

Parameter	Value
Socket path	`/var/run/swarmkit/swarm.sock`
State directory	`/var/lib/swarmkit`
Transport	Unix socket + TLS
Certificates	Auto-generated by SwarmKit CA

Connecting (Go)

import (
    "github.com/moby/swarmkit/v2/api"
    "github.com/restuhaqza/swarmcracker/pkg/apiversion"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
)

// Load TLS certificates from state dir
tlsConfig := loadTLSConfig("/var/lib/swarmkit")

conn, err := grpc.Dial(
    "unix:///var/run/swarmkit/swarm.sock",
    grpc.WithTransportCredentials(credentials.NewTLS(tlsConfig)),
    apiversion.WithVersion(), // Injects X-SwarmCracker-Version metadata
)
client := api.NewControlClient(conn)

API Versioning

SwarmCracker extends SwarmKit with a gRPC unary client interceptor that injects metadata into every outgoing RPC.

Protocol

Header	Value	Description
`x-swarmcracker-version`	`"1"`	Current API version

Client Side

import "github.com/restuhaqza/swarmcracker/pkg/apiversion"

// Option 1: Use convenience function
conn, err := apiversion.DialUnix(socketPath, tlsConfig)

// Option 2: Add interceptor manually
conn, err := grpc.Dial(addr,
    grpc.WithTransportCredentials(creds),
    apiversion.WithVersion(),
)

Server Side

import "github.com/restuhaqza/swarmcracker/pkg/apiversion"

func handleRequest(ctx context.Context) {
    // Extract client version from incoming metadata
    if err := apiversion.ValidateVersion(ctx, "1"); err != nil {
        return status.Error(codes.FailedPrecondition, err.Error())
    }
    // Proceed...
}

Version History

Version	Release	Changes
`1`	v0.8.0+	Initial schema — all v0.x releases share this version
(empty)	pre-v0.8.0	Pre-versioning clients — treated as compatible

SwarmKit Services Used

SwarmCracker leverages the following SwarmKit gRPC services via api.ControlClient:

Cluster Management

RPC	Request	Response	Description
`ListClusters`	`ListClustersRequest`	`ListClustersResponse`	List all clusters (used for token generation)
`GetCluster`	`GetClusterRequest`	`GetClusterResponse`	Get cluster details

Node Management

RPC	Request	Response	Description
`ListNodes`	`ListNodesRequest`	`ListNodesResponse`	List all nodes with status
`GetNode`	`GetNodeRequest`	`GetNodeResponse`	Get node details
`UpdateNode`	`UpdateNodeRequest`	`UpdateNodeResponse`	Update node labels/spec

Service Management

RPC	Request	Response	Description
`CreateService`	`CreateServiceRequest`	`CreateServiceResponse`	Deploy a new service
`UpdateService`	`UpdateServiceRequest`	`UpdateServiceResponse`	Update existing service
`RemoveService`	`RemoveServiceRequest`	`RemoveServiceResponse`	Remove a service
`ListServices`	`ListServicesRequest`	`ListServicesResponse`	List all services
`GetService`	`GetServiceRequest`	`GetServiceResponse`	Get service details
`InspectService`	—	—	(via swarmctl)

Task Management

RPC	Request	Response	Description
`ListTasks`	`ListTasksRequest`	`ListTasksResponse`	List tasks with optional filters
`GetTask`	`GetTaskRequest`	`GetTaskResponse`	Get individual task details

Secret & Config Management

RPC	Request	Response	Description
`CreateSecret`	`CreateSecretRequest`	`CreateSecretResponse`	Store a secret
`GetSecret`	`GetSecretRequest`	`GetSecretResponse`	Retrieve a secret
`ListSecrets`	`ListSecretsRequest`	`ListSecretsResponse`	List all secrets
`RemoveSecret`	`RemoveSecretRequest`	`RemoveSecretResponse`	Delete a secret
`CreateConfig`	`CreateConfigRequest`	`CreateConfigResponse`	Store config data
`GetConfig`	`GetConfigRequest`	`GetConfigResponse`	Retrieve config data
`ListConfigs`	`ListConfigsRequest`	`ListConfigsResponse`	List all configs
`RemoveConfig`	`RemoveConfigRequest`	`RemoveConfigResponse`	Delete a config

Network Management

RPC	Request	Response	Description
`CreateNetwork`	`CreateNetworkRequest`	`CreateNetworkResponse`	Create overlay network
`ListNetworks`	`ListNetworksRequest`	`ListNetworksResponse`	List all networks
`GetNetwork`	`GetNetworkRequest`	`GetNetworkResponse`	Get network details
`RemoveNetwork`	`RemoveNetworkRequest`	`RemoveNetworkResponse`	Delete a network

Custom Types

Executor Task Spec

The SwarmKit TaskSpec runtime is used to encode Firecracker-specific configuration:

// SwarmKit container spec is converted to SwarmCracker types:
type Container struct {
    Image   string
    Command []string
    Args    []string
    Env     []string
    Mounts  []Mount
}

type Mount struct {
    Target   string
    Source   string
    ReadOnly bool
}

type NetworkAttachment struct {
    Network   Network
    Addresses []string
}

type SecretRef struct {
    ID     string // Secret ID from manager
    Name   string // Secret name
    Target string // Mount path in VM
    Data   []byte // Fetched by agent from manager
}

type ConfigRef struct {
    ID     string
    Name   string
    Target string
    Data   []byte
}

Health Check API

The daemon exposes a local HTTP health endpoint for monitoring:

Attribute	Value
Bind address	`127.0.0.1:8080`
Endpoint	`GET /healthz`
Rate limit	10 req/s per client
Request timeout	5s

Response

{
    "status": "healthy",
    "timestamp": "2026-06-26T23:00:00Z",
    "checks": {
        "kvm": true,
        "firecracker": true,
        "bridge": true,
        "consul": true
    }
}

Firecracker Machine Config API

Each Firecracker microVM exposes a local HTTP API on its socket:

Attribute	Value
Path	`/var/run/firecracker/<task-id>/api.sock`
Endpoint	`GET /machine-config`
Endpoint	`GET /` (info)
Protocol	HTTP via Unix socket

Used by swarmctl for VM introspection and the executor for lifecycle management.

Code Locations

Component	Path
API versioning	`pkg/apiversion/`
gRPC client helpers	`cmd/swarmcracker/token_helper.go`
gRPC service handlers	`cmd/swarmd-firecracker/main.go`
SwarmKit types	`github.com/moby/swarmkit/v2/api`
Executor bridge	`pkg/swarmkit/executor.go` (SwarmKit → Firecracker translation)
CNI network allocator	`pkg/cni/allocator.go`
Network discovery	`pkg/discovery/consul.go`