feat: add Kubernetes orchestrator for MCP server pod management
mcpd can now deploy MCP server instances as Kubernetes pods instead of Docker containers. Set MCPD_ORCHESTRATOR=kubernetes to enable. - Add @kubernetes/client-node with thin wrapper (context enforcement via MCPD_K8S_CONTEXT to prevent multi-cluster mishaps) - Rewrite KubernetesOrchestrator: pod CRUD, pod IP extraction, exec via SPDY (one-shot + interactive), log streaming - Manifest generator: stdin:true for STDIO servers, args (not command) to preserve runner image entrypoint, security hardening - Orchestrator selection in main.ts via MCPD_ORCHESTRATOR env var - 25 unit tests for k8s orchestrator, all 624 tests pass Tested end-to-end on local k3s: - mcpd deployed via Pulumi, creates pods in mcpctl-servers namespace - NetworkPolicy verified: only mcpd can reach MCP server pods - Python runner (uvx) successfully runs aws-documentation-mcp-server Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Michal
@@ -1,86 +1,122 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import type { K8sClientConfig } from '../src/services/k8s/k8s-client.js';
|
||||
import type { ContainerSpec } from '../src/services/orchestrator.js';
|
||||
|
||||
// Mock the K8sClient before importing KubernetesOrchestrator
|
||||
vi.mock('../src/services/k8s/k8s-client.js', () => {
|
||||
class MockK8sClient {
|
||||
defaultNamespace: string;
|
||||
// Store mock handlers so tests can override
|
||||
_handlers = new Map<string, { statusCode: number; body: unknown }>();
|
||||
// Mock @kubernetes/client-node before imports
|
||||
vi.mock('@kubernetes/client-node', () => {
|
||||
const handlers = new Map<string, { resolve: unknown; reject?: unknown }>();
|
||||
|
||||
constructor(config: K8sClientConfig) {
|
||||
this.defaultNamespace = config.namespace ?? 'default';
|
||||
}
|
||||
function setHandler(key: string, resolveVal: unknown, rejectVal?: unknown) {
|
||||
handlers.set(key, { resolve: resolveVal, reject: rejectVal });
|
||||
}
|
||||
|
||||
_setResponse(key: string, statusCode: number, body: unknown) {
|
||||
this._handlers.set(key, { statusCode, body });
|
||||
}
|
||||
function getHandler(key: string) {
|
||||
return handlers.get(key);
|
||||
}
|
||||
|
||||
_getResponse(key: string) {
|
||||
return this._handlers.get(key) ?? { statusCode: 200, body: {} };
|
||||
}
|
||||
function clearHandlers() {
|
||||
handlers.clear();
|
||||
}
|
||||
|
||||
async get(path: string) { return this._getResponse(`GET:${path}`); }
|
||||
async post(path: string, _body: unknown) { return this._getResponse(`POST:${path}`); }
|
||||
async delete(path: string) { return this._getResponse(`DELETE:${path}`); }
|
||||
async patch(path: string, _body: unknown) { return this._getResponse(`PATCH:${path}`); }
|
||||
async getLogs(_ns: string, _pod: string, _opts?: unknown) {
|
||||
return this._getResponse('LOGS')?.body ?? '';
|
||||
}
|
||||
const mockCore = {
|
||||
listNamespace: vi.fn(async () => {
|
||||
const h = getHandler('listNamespace');
|
||||
if (h?.reject) throw h.reject;
|
||||
return h?.resolve ?? { items: [] };
|
||||
}),
|
||||
createNamespacedPod: vi.fn(async (params: { namespace: string; body: { metadata: { name: string } } }) => {
|
||||
const h = getHandler('createNamespacedPod');
|
||||
if (h?.reject) throw h.reject;
|
||||
return h?.resolve ?? params.body;
|
||||
}),
|
||||
readNamespacedPod: vi.fn(async (params: { name: string }) => {
|
||||
const h = getHandler(`readNamespacedPod:${params.name}`);
|
||||
if (h?.reject) throw h.reject;
|
||||
return h?.resolve;
|
||||
}),
|
||||
deleteNamespacedPod: vi.fn(async (params: { name: string }) => {
|
||||
const h = getHandler(`deleteNamespacedPod:${params.name}`);
|
||||
if (h?.reject) throw h.reject;
|
||||
return h?.resolve ?? {};
|
||||
}),
|
||||
listNamespacedPod: vi.fn(async () => {
|
||||
const h = getHandler('listNamespacedPod');
|
||||
if (h?.reject) throw h.reject;
|
||||
return h?.resolve ?? { items: [] };
|
||||
}),
|
||||
readNamespace: vi.fn(async (params: { name: string }) => {
|
||||
const h = getHandler(`readNamespace:${params.name}`);
|
||||
if (h?.reject) throw h.reject;
|
||||
return h?.resolve ?? {};
|
||||
}),
|
||||
createNamespace: vi.fn(async () => {
|
||||
const h = getHandler('createNamespace');
|
||||
if (h?.reject) throw h.reject;
|
||||
return h?.resolve ?? {};
|
||||
}),
|
||||
};
|
||||
|
||||
class MockKubeConfig {
|
||||
loadFromDefault = vi.fn();
|
||||
setCurrentContext = vi.fn();
|
||||
getContexts = vi.fn(() => []);
|
||||
getCurrentContext = vi.fn(() => 'default');
|
||||
makeApiClient = vi.fn(() => mockCore);
|
||||
}
|
||||
|
||||
class MockExec {
|
||||
exec = vi.fn();
|
||||
}
|
||||
|
||||
class MockLog {
|
||||
log = vi.fn();
|
||||
}
|
||||
|
||||
return {
|
||||
K8sClient: MockK8sClient,
|
||||
loadDefaultConfig: vi.fn(),
|
||||
parseKubeconfig: vi.fn(),
|
||||
KubeConfig: MockKubeConfig,
|
||||
CoreV1Api: class {},
|
||||
Exec: MockExec,
|
||||
Log: MockLog,
|
||||
// Export test helpers
|
||||
__testHelpers: { setHandler, getHandler, clearHandlers, mockCore },
|
||||
};
|
||||
});
|
||||
|
||||
// Import after mock
|
||||
import { KubernetesOrchestrator } from '../src/services/k8s/kubernetes-orchestrator.js';
|
||||
import type { ContainerSpec } from '../src/services/orchestrator.js';
|
||||
|
||||
function getClient(orch: KubernetesOrchestrator): {
|
||||
_setResponse(key: string, statusCode: number, body: unknown): void;
|
||||
} {
|
||||
// Access private client for test setup
|
||||
return (orch as unknown as { client: { _setResponse(k: string, sc: number, b: unknown): void } }).client;
|
||||
}
|
||||
|
||||
const testConfig: K8sClientConfig = {
|
||||
apiServer: 'https://localhost:6443',
|
||||
token: 'test-token',
|
||||
namespace: 'test-ns',
|
||||
};
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
const k8sMock = await import('@kubernetes/client-node') as any;
|
||||
const { setHandler, clearHandlers, mockCore } = k8sMock.__testHelpers;
|
||||
|
||||
const testSpec: ContainerSpec = {
|
||||
image: 'mcpctl/server:latest',
|
||||
image: 'mysources.co.uk/michal/mcpctl-node-runner:latest',
|
||||
name: 'my-server',
|
||||
env: { PORT: '3000' },
|
||||
containerPort: 3000,
|
||||
};
|
||||
|
||||
const podStatusRunning = {
|
||||
const podRunning = {
|
||||
metadata: {
|
||||
name: 'my-server',
|
||||
namespace: 'test-ns',
|
||||
namespace: 'mcpctl-servers',
|
||||
creationTimestamp: '2026-01-01T00:00:00Z',
|
||||
labels: { 'mcpctl.managed': 'true' },
|
||||
},
|
||||
status: {
|
||||
phase: 'Running',
|
||||
podIP: '10.42.0.15',
|
||||
containerStatuses: [{
|
||||
state: { running: { startedAt: '2026-01-01T00:00:00Z' } },
|
||||
}],
|
||||
},
|
||||
spec: {
|
||||
containers: [{ ports: [{ containerPort: 3000 }] }],
|
||||
containers: [{ name: 'my-server', ports: [{ containerPort: 3000 }] }],
|
||||
},
|
||||
};
|
||||
|
||||
const podStatusPending = {
|
||||
const podPending = {
|
||||
metadata: {
|
||||
name: 'my-server',
|
||||
namespace: 'test-ns',
|
||||
namespace: 'mcpctl-servers',
|
||||
creationTimestamp: '2026-01-01T00:00:00Z',
|
||||
},
|
||||
status: {
|
||||
@@ -89,23 +125,28 @@ const podStatusPending = {
|
||||
state: { waiting: { reason: 'ContainerCreating' } },
|
||||
}],
|
||||
},
|
||||
spec: {
|
||||
containers: [{ name: 'my-server' }],
|
||||
},
|
||||
};
|
||||
|
||||
describe('KubernetesOrchestrator', () => {
|
||||
let orch: KubernetesOrchestrator;
|
||||
|
||||
beforeEach(() => {
|
||||
orch = new KubernetesOrchestrator(testConfig);
|
||||
clearHandlers();
|
||||
vi.clearAllMocks();
|
||||
orch = new KubernetesOrchestrator({ serversNamespace: 'mcpctl-servers' });
|
||||
});
|
||||
|
||||
describe('ping', () => {
|
||||
it('returns true on successful API call', async () => {
|
||||
getClient(orch)._setResponse('GET:/api/v1', 200, { kind: 'APIResourceList' });
|
||||
setHandler('listNamespace', { items: [] });
|
||||
expect(await orch.ping()).toBe(true);
|
||||
});
|
||||
|
||||
it('returns false on error', async () => {
|
||||
getClient(orch)._setResponse('GET:/api/v1', 500, { message: 'internal error' });
|
||||
setHandler('listNamespace', undefined, new Error('connection refused'));
|
||||
expect(await orch.ping()).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -118,113 +159,94 @@ describe('KubernetesOrchestrator', () => {
|
||||
|
||||
describe('createContainer', () => {
|
||||
it('creates a pod and returns container info', async () => {
|
||||
const client = getClient(orch);
|
||||
// ensureNamespace check
|
||||
client._setResponse('GET:/api/v1/namespaces/test-ns', 200, {});
|
||||
// create pod
|
||||
client._setResponse('POST:/api/v1/namespaces/test-ns/pods', 201, podStatusRunning);
|
||||
// inspect after creation
|
||||
client._setResponse('GET:/api/v1/namespaces/test-ns/pods/my-server', 200, podStatusRunning);
|
||||
// ensureNamespace
|
||||
setHandler('readNamespace:mcpctl-servers', {});
|
||||
// createPod returns the pod
|
||||
setHandler('createNamespacedPod', podRunning);
|
||||
// inspectContainer after create
|
||||
setHandler('readNamespacedPod:my-server', podRunning);
|
||||
|
||||
const info = await orch.createContainer(testSpec);
|
||||
expect(info.containerId).toBe('my-server');
|
||||
expect(info.state).toBe('running');
|
||||
expect(info.port).toBe(3000);
|
||||
expect(info.ip).toBe('10.42.0.15');
|
||||
});
|
||||
|
||||
it('throws on API error', async () => {
|
||||
const client = getClient(orch);
|
||||
client._setResponse('GET:/api/v1/namespaces/test-ns', 200, {});
|
||||
client._setResponse('POST:/api/v1/namespaces/test-ns/pods', 422, {
|
||||
message: 'pod already exists',
|
||||
});
|
||||
setHandler('readNamespace:mcpctl-servers', {});
|
||||
setHandler('createNamespacedPod', undefined, new Error('pod already exists'));
|
||||
|
||||
await expect(orch.createContainer(testSpec)).rejects.toThrow('Failed to create pod');
|
||||
await expect(orch.createContainer(testSpec)).rejects.toThrow('pod already exists');
|
||||
});
|
||||
});
|
||||
|
||||
describe('inspectContainer', () => {
|
||||
it('returns running container info', async () => {
|
||||
getClient(orch)._setResponse('GET:/api/v1/namespaces/test-ns/pods/my-server', 200, podStatusRunning);
|
||||
it('returns running container info with pod IP', async () => {
|
||||
setHandler('readNamespacedPod:my-server', podRunning);
|
||||
|
||||
const info = await orch.inspectContainer('my-server');
|
||||
expect(info.state).toBe('running');
|
||||
expect(info.name).toBe('my-server');
|
||||
expect(info.ip).toBe('10.42.0.15');
|
||||
expect(info.port).toBe(3000);
|
||||
});
|
||||
|
||||
it('maps pending state correctly', async () => {
|
||||
getClient(orch)._setResponse('GET:/api/v1/namespaces/test-ns/pods/my-server', 200, podStatusPending);
|
||||
setHandler('readNamespacedPod:my-server', podPending);
|
||||
|
||||
const info = await orch.inspectContainer('my-server');
|
||||
expect(info.state).toBe('starting');
|
||||
});
|
||||
|
||||
it('throws on 404', async () => {
|
||||
getClient(orch)._setResponse('GET:/api/v1/namespaces/test-ns/pods/missing', 404, {
|
||||
message: 'pods "missing" not found',
|
||||
});
|
||||
it('throws when pod not found', async () => {
|
||||
setHandler('readNamespacedPod:missing', undefined, { statusCode: 404, message: 'not found' });
|
||||
|
||||
await expect(orch.inspectContainer('missing')).rejects.toThrow('not found');
|
||||
await expect(orch.inspectContainer('missing')).rejects.toBeDefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('stopContainer', () => {
|
||||
it('deletes the pod', async () => {
|
||||
getClient(orch)._setResponse('DELETE:/api/v1/namespaces/test-ns/pods/my-server', 200, {});
|
||||
setHandler('deleteNamespacedPod:my-server', {});
|
||||
await expect(orch.stopContainer('my-server')).resolves.toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('removeContainer', () => {
|
||||
it('deletes the pod successfully', async () => {
|
||||
getClient(orch)._setResponse('DELETE:/api/v1/namespaces/test-ns/pods/my-server', 200, {});
|
||||
setHandler('deleteNamespacedPod:my-server', {});
|
||||
await expect(orch.removeContainer('my-server')).resolves.toBeUndefined();
|
||||
});
|
||||
|
||||
it('ignores 404 (already deleted)', async () => {
|
||||
getClient(orch)._setResponse('DELETE:/api/v1/namespaces/test-ns/pods/my-server', 404, {});
|
||||
setHandler('deleteNamespacedPod:my-server', undefined, { statusCode: 404 });
|
||||
await expect(orch.removeContainer('my-server')).resolves.toBeUndefined();
|
||||
});
|
||||
|
||||
it('throws on other errors', async () => {
|
||||
getClient(orch)._setResponse('DELETE:/api/v1/namespaces/test-ns/pods/my-server', 403, {
|
||||
message: 'forbidden',
|
||||
});
|
||||
await expect(orch.removeContainer('my-server')).rejects.toThrow('Failed to delete pod');
|
||||
});
|
||||
});
|
||||
|
||||
describe('getContainerLogs', () => {
|
||||
it('returns logs from pod', async () => {
|
||||
getClient(orch)._setResponse('LOGS', 200, 'log line 1\nlog line 2\n');
|
||||
|
||||
const logs = await orch.getContainerLogs('my-server');
|
||||
expect(logs.stdout).toBe('log line 1\nlog line 2\n');
|
||||
expect(logs.stderr).toBe('');
|
||||
setHandler('deleteNamespacedPod:my-server', undefined, { statusCode: 403, message: 'forbidden' });
|
||||
await expect(orch.removeContainer('my-server')).rejects.toBeDefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('listContainers', () => {
|
||||
it('lists managed pods', async () => {
|
||||
getClient(orch)._setResponse(
|
||||
'GET:/api/v1/namespaces/test-ns/pods?labelSelector=mcpctl.managed%3Dtrue',
|
||||
200,
|
||||
{ items: [podStatusRunning] },
|
||||
);
|
||||
setHandler('listNamespacedPod', { items: [podRunning] });
|
||||
|
||||
const containers = await orch.listContainers();
|
||||
expect(containers).toHaveLength(1);
|
||||
expect(containers[0]!.containerId).toBe('my-server');
|
||||
expect(containers[0]!.state).toBe('running');
|
||||
expect(containers[0]!.ip).toBe('10.42.0.15');
|
||||
|
||||
expect(mockCore.listNamespacedPod).toHaveBeenCalledWith(
|
||||
expect.objectContaining({ labelSelector: 'mcpctl.managed=true' }),
|
||||
);
|
||||
});
|
||||
|
||||
it('returns empty on API error', async () => {
|
||||
getClient(orch)._setResponse(
|
||||
'GET:/api/v1/namespaces/test-ns/pods?labelSelector=mcpctl.managed%3Dtrue',
|
||||
500,
|
||||
{},
|
||||
);
|
||||
|
||||
it('returns empty when no pods', async () => {
|
||||
setHandler('listNamespacedPod', { items: [] });
|
||||
const containers = await orch.listContainers();
|
||||
expect(containers).toEqual([]);
|
||||
});
|
||||
@@ -232,35 +254,100 @@ describe('KubernetesOrchestrator', () => {
|
||||
|
||||
describe('ensureNamespace', () => {
|
||||
it('does nothing if namespace exists', async () => {
|
||||
getClient(orch)._setResponse('GET:/api/v1/namespaces/test-ns', 200, {});
|
||||
setHandler('readNamespace:test-ns', {});
|
||||
await expect(orch.ensureNamespace('test-ns')).resolves.toBeUndefined();
|
||||
expect(mockCore.createNamespace).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('creates namespace if not found', async () => {
|
||||
const client = getClient(orch);
|
||||
client._setResponse('GET:/api/v1/namespaces/new-ns', 404, {});
|
||||
client._setResponse('POST:/api/v1/namespaces', 201, {});
|
||||
setHandler('readNamespace:new-ns', undefined, { statusCode: 404 });
|
||||
setHandler('createNamespace', {});
|
||||
await expect(orch.ensureNamespace('new-ns')).resolves.toBeUndefined();
|
||||
expect(mockCore.createNamespace).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('handles conflict (namespace already created by another process)', async () => {
|
||||
const client = getClient(orch);
|
||||
client._setResponse('GET:/api/v1/namespaces/new-ns', 404, {});
|
||||
client._setResponse('POST:/api/v1/namespaces', 409, { message: 'already exists' });
|
||||
setHandler('readNamespace:new-ns', undefined, { statusCode: 404 });
|
||||
setHandler('createNamespace', undefined, { statusCode: 409, message: 'already exists' });
|
||||
await expect(orch.ensureNamespace('new-ns')).resolves.toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('getNamespace', () => {
|
||||
it('returns configured namespace', () => {
|
||||
expect(orch.getNamespace()).toBe('test-ns');
|
||||
expect(orch.getNamespace()).toBe('mcpctl-servers');
|
||||
});
|
||||
|
||||
it('defaults to "default"', () => {
|
||||
const defaultOrch = new KubernetesOrchestrator({
|
||||
apiServer: 'https://localhost:6443',
|
||||
});
|
||||
expect(defaultOrch.getNamespace()).toBe('default');
|
||||
it('defaults to mcpctl-servers', () => {
|
||||
const defaultOrch = new KubernetesOrchestrator();
|
||||
expect(defaultOrch.getNamespace()).toBe('mcpctl-servers');
|
||||
});
|
||||
});
|
||||
|
||||
describe('pod IP extraction', () => {
|
||||
it('extracts podIP from status', async () => {
|
||||
setHandler('readNamespacedPod:my-server', podRunning);
|
||||
const info = await orch.inspectContainer('my-server');
|
||||
expect(info.ip).toBe('10.42.0.15');
|
||||
});
|
||||
|
||||
it('returns undefined ip when no podIP', async () => {
|
||||
const podWithoutIP = {
|
||||
...podRunning,
|
||||
status: { ...podRunning.status, podIP: undefined },
|
||||
};
|
||||
setHandler('readNamespacedPod:my-server', podWithoutIP);
|
||||
const info = await orch.inspectContainer('my-server');
|
||||
expect(info.ip).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('manifest security', () => {
|
||||
it('creates pods with security hardening', async () => {
|
||||
setHandler('readNamespace:mcpctl-servers', {});
|
||||
setHandler('createNamespacedPod', podRunning);
|
||||
setHandler('readNamespacedPod:my-server', podRunning);
|
||||
|
||||
await orch.createContainer(testSpec);
|
||||
|
||||
const createCall = mockCore.createNamespacedPod.mock.calls[0]![0];
|
||||
const container = createCall.body.spec.containers[0];
|
||||
expect(container.securityContext.runAsNonRoot).toBe(false);
|
||||
expect(container.securityContext.readOnlyRootFilesystem).toBe(false);
|
||||
expect(container.securityContext.allowPrivilegeEscalation).toBe(false);
|
||||
expect(container.securityContext.capabilities.drop).toEqual(['ALL']);
|
||||
expect(container.securityContext.seccompProfile.type).toBe('RuntimeDefault');
|
||||
});
|
||||
|
||||
it('creates pods with automountServiceAccountToken disabled', async () => {
|
||||
setHandler('readNamespace:mcpctl-servers', {});
|
||||
setHandler('createNamespacedPod', podRunning);
|
||||
setHandler('readNamespacedPod:my-server', podRunning);
|
||||
|
||||
await orch.createContainer(testSpec);
|
||||
|
||||
const createCall = mockCore.createNamespacedPod.mock.calls[0]![0];
|
||||
expect(createCall.body.spec.automountServiceAccountToken).toBe(false);
|
||||
});
|
||||
|
||||
it('creates pods with stdin enabled for STDIO servers', async () => {
|
||||
setHandler('readNamespace:mcpctl-servers', {});
|
||||
setHandler('createNamespacedPod', podRunning);
|
||||
setHandler('readNamespacedPod:my-server', podRunning);
|
||||
|
||||
await orch.createContainer(testSpec);
|
||||
|
||||
const createCall = mockCore.createNamespacedPod.mock.calls[0]![0];
|
||||
expect(createCall.body.spec.containers[0].stdin).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('context enforcement', () => {
|
||||
it('sets context when configured', () => {
|
||||
const _orch = new KubernetesOrchestrator({ context: 'default' });
|
||||
// The mock KubeConfig.setCurrentContext should have been called
|
||||
// This verifies the safety mechanism works
|
||||
expect(_orch.getNamespace()).toBe('mcpctl-servers');
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user