SwarmCracker API Reference¶

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

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)

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(),
)

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...
}

// 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
}

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