@spider-mesh/k8s

Kubernetes transporters for Spider Mesh: HTTP/2 RPC with automatic service-name → hostname routing, plus a lightweight discovery-only peer-sync server/client for wait() / watch() / nodes.

This package is transport + discovery only — no metrics, logs, or system monitoring.

Installation

bun add @spider-mesh/k8s @spider-mesh/core

Packages

| Export | Description | |---|---| | @spider-mesh/k8s | All components | | @spider-mesh/k8s/discovery-server | WebsocketDiscoveryServer only | | @spider-mesh/k8s/discovery-client | WebsocketDiscoveryClient only |

WebsocketDiscoveryServer (discovery only)

Peer-sync server. Nodes connect, announce themselves (hello), receive the current peer list, and are notified when peers go offline. Pure routing support — discovery only, no metrics or logs.

import { WebsocketDiscoveryServer } from '@spider-mesh/k8s/discovery-server'

const server = new WebsocketDiscoveryServer({ port: 8788 })
// server.port, server.close()

WebsocketDiscoveryClient (discovery only)

Connects to a WebsocketDiscoveryServer, announces the local node, and tracks the peer table — implements DiscoveryTransporter + ServiceDirectory so core can answer wait()/watch()/nodes when routing via K8sRpcTransporter.

import { SpiderMesh } from '@spider-mesh/core'
import { WebsocketDiscoveryClient } from '@spider-mesh/k8s/discovery-client'

const mesh = new SpiderMesh()
mesh.registerTransporter(new WebsocketDiscoveryClient('ws://discovery:8788', {
  reconnectIntervalMs: 1000,
  heartbeatIntervalMs: 30000,
}))

K8sRpcTransporter

HTTP/2 RPC transporter that automatically converts service names to k8s hostname using a configurable postfix. No registry or manual IP management needed.

import { K8sRpcTransporter } from '@spider-mesh/k8s'

const rpc = new K8sRpcTransporter({
    port: 8080,                                  // fixed listen port (default: SPIDER_MESH_K8S_PORT or 8080)
    postfix: '.default.svc.cluster.local',       // hostname postfix (default: SPIDER_MESH_K8S_POSTFIX)
})

Service name → hostname conversion:

| Service name | Resolved hostname | |---|---| | UserService | user-service.default.svc.cluster.local:8080 | | OrderServiceV2 | order-service-v2.default.svc.cluster.local:8080 | | PaymentGatewayService | payment-gateway-service.default.svc.cluster.local:8080 |

Full k8s setup

import 'reflect-metadata' // required by @spider-mesh/core for @Microservice() decorators
import { SpiderMesh, Microservice, RemoteServiceLinker } from '@spider-mesh/core'
import { K8sRpcTransporter, WebsocketDiscoveryClient } from '@spider-mesh/k8s'

// Provider
@Microservice()
class UserService {
    async getUser(id: string) {
        return { id, name: 'Alice' }
    }
}
new UserService()

const mesh = new SpiderMesh()
mesh.registerTransporter(new WebsocketDiscoveryClient('ws://discovery:8788'))
mesh.registerTransporter(new K8sRpcTransporter())

// Consumer
interface IUserService { getUser(id: string): Promise<{ id: string, name: string }> }

const userService = RemoteServiceLinker.link<IUserService>(mesh, { service: 'UserService' })
await userService.wait()
const user = await userService.getUser('123')

Test / non-k8s environments

Use resolver to bypass DNS, pointing directly to a known host:port:

const rpc = new K8sRpcTransporter({
    resolver: () => ({ host: 'localhost', port: 9000 })
})

Configuration

All options can be set via environment variables. Code-level options take precedence.

Node identity

| Env var | Description | Default | |---|---|---| | SPIDERMESH_NODE_ID | Stable node ID (recommended in k8s) | HOSTNAME → random | | HOSTNAME | Set automatically by k8s (pod name) | — | | SPIDERMESH_NAMESPACE | Mesh namespace for isolation | default | | SPIDERMESH_NODE_HOSTNAME | Advertised host address | "" |

Build info

Automatically attached to every node announcement. Set these in your k8s Deployment or ConfigMap:

| Env var | Field | Example | |---|---|---| | APP_VERSION / SPIDERMESH_VERSION | build.version | 1.2.3 | | GIT_TAG | build.git_tag | v1.2.3 | | GIT_BRANCH | build.git_branch | main | | GIT_COMMIT | build.git_commit | a3f9c12 | | BUILD_TIME | build.build_time | 1718000000000 | | APP_ENV / NODE_ENV | build.environment | production | | APP_TAGS | build.tags | {"team":"platform"} |

build.runtime is detected automatically ([email protected] or [email protected]).

K8s RPC transporter

| Env var | Description | Default | |---|---|---| | SPIDER_MESH_K8S_PORT | HTTP/2 listen port | 8080 | | SPIDER_MESH_K8S_POSTFIX | Hostname postfix | "" |

k8s Deployment example

Discovery server

apiVersion: apps/v1
kind: Deployment
metadata:
  name: spider-mesh-discovery
spec:
  replicas: 1
  selector:
    matchLabels:
      app: spider-mesh-discovery
  template:
    spec:
      containers:
        - name: discovery
          image: your-registry/spider-mesh-discovery:latest
          ports:
            - containerPort: 8788   # WebSocket peer-sync
---
apiVersion: v1
kind: Service
metadata:
  name: spider-mesh-discovery
spec:
  selector:
    app: spider-mesh-discovery
  ports:
    - name: ws
      port: 8788

Service node

apiVersion: apps/v1
kind: Deployment
metadata:
  name: user-service
spec:
  template:
    spec:
      containers:
        - name: app
          env:
            - name: SPIDER_MESH_K8S_PORT
              value: "8080"
            - name: SPIDER_MESH_K8S_POSTFIX
              value: ".default.svc.cluster.local"
            - name: APP_VERSION
              value: "1.2.3"
            - name: GIT_COMMIT
              value: "a3f9c12"
            - name: APP_ENV
              value: "production"
          ports:
            - containerPort: 8080

The HOSTNAME env (pod name) is injected automatically by k8s — no extra config needed for stable node_id.

Stable node_id

| Environment | node_id source | Stable across restart? | |---|---|---| | k8s | Pod name (auto from HOSTNAME) | Yes — same pod, same id | | Non-k8s, single process | Machine hostname | Yes | | Non-k8s, multiple processes | Set SPIDERMESH_NODE_ID manually | Yes | | No config | Random | No |