@forgeportal/plugin-kubernetes 1.3.0

package/src/api-client.ts

@@ -0,0 +1,248 @@
+import { Agent } from 'undici';
+import type { Dispatcher } from 'undici';
+import type {
+  ClusterConfig,
+  WorkloadsResponse,
+  RawDeployment,
+  RawPod,
+  RawService,
+  RawIngress,
+  K8sDeployment,
+  K8sPod,
+  K8sService,
+  K8sIngress,
+} from './types.js';
+
+// ─── Cluster config parser ────────────────────────────────────────────────────
+
+/**
+ * Parse the `clusters` JSON string from plugin config and resolve per-cluster
+ * tokens from environment variables.
+ *
+ * Token env var convention: FORGEPORTAL_PLUGIN_KUBERNETES_<CLUSTER_NAME_UPPER>_TOKEN
+ * e.g. cluster "production" → FORGEPORTAL_PLUGIN_KUBERNETES_PRODUCTION_TOKEN
+ */
+export function parseClusters(
+  rawClustersJson: string,
+  getToken: (envKey: string) => string | undefined,
+): ClusterConfig[] {
+  let raw: Array<{ name: string; url: string; skipTLSVerify?: boolean }>;
+  try {
+    raw = JSON.parse(rawClustersJson) as typeof raw;
+  } catch {
+    throw new Error(
+      'kubernetes plugin: config.clusters must be a valid JSON string representing an array of {name, url} objects',
+    );
+  }
+
+  return raw.map((c) => {
+    const envKey = c.name.toUpperCase().replace(/[^A-Z0-9]+/g, '_');
+    return {
+      name:          c.name,
+      url:           c.url.replace(/\/$/, ''),
+      token:         getToken(envKey) ?? '',
+      skipTLSVerify: c.skipTLSVerify ?? false,
+    };
+  });
+}
+
+// ─── Mappers ─────────────────────────────────────────────────────────────────
+
+function mapDeployment(d: RawDeployment): K8sDeployment {
+  const desired   = d.spec.replicas ?? 1;
+  const ready     = d.status?.readyReplicas ?? 0;
+  const available = d.status?.availableReplicas ?? 0;
+  const image     = d.spec.template.spec.containers[0]?.image ?? '';
+
+  const rolloutCondition = d.status?.conditions?.find((c) => c.type === 'Progressing');
+  const lastRollout      = rolloutCondition?.lastUpdateTime ?? d.metadata.creationTimestamp ?? null;
+
+  return {
+    name:        d.metadata.name,
+    namespace:   d.metadata.namespace,
+    replicas:    { desired, ready, available },
+    image,
+    lastRollout,
+    healthy:     ready >= desired && desired > 0,
+  };
+}
+
+function resolvePodStatus(pod: RawPod): string {
+  // Check for CrashLoopBackOff in any container's waiting state
+  for (const cs of pod.status?.containerStatuses ?? []) {
+    if (cs.state?.waiting?.reason === 'CrashLoopBackOff') return 'CrashLoopBackOff';
+  }
+  return pod.status?.phase ?? 'Unknown';
+}
+
+function mapPod(p: RawPod): K8sPod {
+  const containerStatuses = p.status?.containerStatuses ?? [];
+  const ready = containerStatuses.length > 0 && containerStatuses.every((cs) => cs.ready);
+
+  return {
+    name:       p.metadata.name,
+    namespace:  p.metadata.namespace,
+    status:     resolvePodStatus(p),
+    ready,
+    containers: p.spec?.containers?.length ?? containerStatuses.length,
+    nodeName:   p.spec?.nodeName ?? null,
+    startTime:  p.status?.startTime ?? null,
+  };
+}
+
+function mapService(s: RawService): K8sService {
+  return {
+    name:      s.metadata.name,
+    namespace: s.metadata.namespace,
+    type:      s.spec?.type ?? 'ClusterIP',
+    clusterIp: s.spec?.clusterIP ?? '',
+    ports:     (s.spec?.ports ?? []).map((p) => ({
+      port:       p.port,
+      protocol:   p.protocol ?? 'TCP',
+      targetPort: p.targetPort ?? p.port,
+    })),
+  };
+}
+
+function mapIngress(i: RawIngress): K8sIngress {
+  const hosts = (i.spec?.rules ?? [])
+    .map((r) => r.host ?? '')
+    .filter(Boolean);
+
+  return {
+    name:      i.metadata.name,
+    namespace: i.metadata.namespace,
+    hosts,
+    tls:       (i.spec?.tls?.length ?? 0) > 0,
+  };
+}
+
+// ─── Client ───────────────────────────────────────────────────────────────────
+
+export class KubernetesApiClient {
+  private readonly dispatcher: Dispatcher | undefined;
+
+  constructor(private readonly cluster: ClusterConfig) {
+    if (cluster.skipTLSVerify) {
+      this.dispatcher = new Agent({ connect: { rejectUnauthorized: false } });
+    }
+  }
+
+  private async request<T>(path: string, init?: RequestInit): Promise<T> {
+    const url = `${this.cluster.url}${path}`;
+    const options: Record<string, unknown> = {
+      ...(init ?? {}),
+      headers: {
+        Authorization: `Bearer ${this.cluster.token}`,
+        Accept:        'application/json',
+        ...((init?.headers as Record<string, string>) ?? {}),
+      },
+    };
+    if (this.dispatcher) options['dispatcher'] = this.dispatcher;
+
+    const res = await (fetch as (url: string, init: Record<string, unknown>) => Promise<Response>)(url, options);
+    if (!res.ok) {
+      const body = await res.text().catch(() => res.statusText);
+      throw new Error(`Kubernetes API [${this.cluster.name}] ${path} → ${res.status}: ${body}`);
+    }
+    return res.json() as Promise<T>;
+  }
+
+  /**
+   * Aggregate Deployments, Pods, Services, and Ingresses for the given label selector.
+   */
+  async getWorkloads(namespace: string, labelSelector: string): Promise<WorkloadsResponse> {
+    const qs = `labelSelector=${encodeURIComponent(labelSelector)}&limit=100`;
+
+    const [deployments, pods, services, ingresses] = await Promise.all([
+      this.request<{ items: RawDeployment[] }>(
+        `/apis/apps/v1/namespaces/${namespace}/deployments?${qs}`,
+      ),
+      this.request<{ items: RawPod[] }>(
+        `/api/v1/namespaces/${namespace}/pods?${qs}`,
+      ),
+      this.request<{ items: RawService[] }>(
+        `/api/v1/namespaces/${namespace}/services?${qs}`,
+      ),
+      this.request<{ items: RawIngress[] }>(
+        `/apis/networking.k8s.io/v1/namespaces/${namespace}/ingresses?${qs}`,
+      ).catch(() => ({ items: [] as RawIngress[] })),
+    ]);
+
+    return {
+      cluster:       this.cluster.name,
+      namespace,
+      labelSelector,
+      deployments:   deployments.items.map(mapDeployment),
+      pods:          pods.items.map(mapPod),
+      services:      services.items.map(mapService),
+      ingresses:     ingresses.items.map(mapIngress),
+    };
+  }
+
+  /** Returns the last N log lines for a pod container as a plain string. */
+  async getPodLogs(namespace: string, podName: string, tailLines = 100): Promise<string> {
+    const path = `/api/v1/namespaces/${namespace}/pods/${podName}/log?tailLines=${tailLines}&timestamps=true`;
+    const options: Record<string, unknown> = {
+      headers: { Authorization: `Bearer ${this.cluster.token}` },
+    };
+    if (this.dispatcher) options['dispatcher'] = this.dispatcher;
+
+    const res = await (fetch as (url: string, init: Record<string, unknown>) => Promise<Response>)(`${this.cluster.url}${path}`, options);
+    if (!res.ok) throw new Error(`Pod logs [${podName}]: ${res.status}`);
+    return res.text();
+  }
+
+  /** Trigger a rolling restart via a strategic merge patch on the pod template annotation. */
+  async restartDeployment(namespace: string, deploymentName: string): Promise<void> {
+    const patch = {
+      spec: {
+        template: {
+          metadata: {
+            annotations: { 'kubectl.kubernetes.io/restartedAt': new Date().toISOString() },
+          },
+        },
+      },
+    };
+    await this.request<unknown>(
+      `/apis/apps/v1/namespaces/${namespace}/deployments/${deploymentName}`,
+      {
+        method:  'PATCH',
+        headers: { 'Content-Type': 'application/strategic-merge-patch+json' },
+        body:    JSON.stringify(patch),
+      },
+    );
+  }
+
+  /** Scale a deployment to the desired replica count. */
+  async scaleDeployment(namespace: string, deploymentName: string, replicas: number): Promise<void> {
+    await this.request<unknown>(
+      `/apis/apps/v1/namespaces/${namespace}/deployments/${deploymentName}/scale`,
+      {
+        method:  'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body:    JSON.stringify({ spec: { replicas } }),
+      },
+    );
+  }
+}
+
+// ─── Cluster resolver ─────────────────────────────────────────────────────────
+
+export function resolveCluster(
+  clusters: ClusterConfig[],
+  clusterName?: string,
+): ClusterConfig {
+  if (!clusterName) {
+    const first = clusters[0];
+    if (!first) throw new Error('kubernetes plugin: no clusters configured');
+    return first;
+  }
+  const found = clusters.find((c) => c.name === clusterName);
+  if (!found) {
+    throw new Error(
+      `kubernetes plugin: cluster "${clusterName}" not found. Available: ${clusters.map((c) => c.name).join(', ')}`,
+    );
+  }
+  return found;
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+import type { ForgeBackendPluginSDK } from '@forgeportal/plugin-sdk';
+import { parseClusters } from './api-client.js';
+import { createRoutes } from './routes.js';
+import { createRestartDeploymentAction, createScaleDeploymentAction } from './actions.js';
+
+/**
+ * Backend entry point for the Kubernetes plugin.
+ * Called by the ForgePortal plugin loader at startup.
+ *
+ * Configuration (forgeportal.yaml → plugins.kubernetes.config):
+ *   clusters:         JSON string — array of {name, url, skipTLSVerify?}
+ *   defaultNamespace: string (default: "default")
+ *
+ * Per-cluster tokens come from env:
+ *   FORGEPORTAL_PLUGIN_KUBERNETES_<CLUSTER_NAME_UPPER>_TOKEN
+ */
+export function registerBackendPlugin(sdk: ForgeBackendPluginSDK): void {
+  const rawClusters     = sdk.config.get<string>('clusters') ?? '[]';
+  const defaultNs       = sdk.config.get<string>('defaultNamespace') ?? 'default';
+
+  const clusters = parseClusters(
+    rawClusters,
+    (envKey) => process.env[`FORGEPORTAL_PLUGIN_KUBERNETES_${envKey}_TOKEN`],
+  );
+
+  if (clusters.length === 0) {
+    sdk.logger.warn(
+      'kubernetes plugin: no clusters configured. ' +
+      'Set plugins.kubernetes.config.clusters in forgeportal.yaml.',
+    );
+  } else {
+    sdk.logger.info(
+      `kubernetes plugin: ${clusters.length} cluster(s) configured — ${clusters.map((c) => c.name).join(', ')}`,
+    );
+  }
+
+  // Mount backend routes under /api/v1/plugins/kubernetes/
+  sdk.registerBackendRoute({
+    path:    '',
+    handler: createRoutes(clusters, defaultNs),
+  });
+
+  // Register template-usable action providers
+  sdk.registerActionProvider(createRestartDeploymentAction(clusters, defaultNs));
+  sdk.registerActionProvider(createScaleDeploymentAction(clusters, defaultNs));
+}

package/src/routes.ts

@@ -0,0 +1,154 @@
+import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import type { ClusterConfig } from './types.js';
+import { KubernetesApiClient, resolveCluster } from './api-client.js';
+
+interface WorkloadsQuery { labelSelector?: string; namespace?: string; cluster?: string }
+interface WorkloadsParams { entityId: string }
+
+interface LogsQuery  { namespace?: string; cluster?: string; tail?: string }
+interface LogsParams { entityId: string; podName: string }
+
+interface RestartParams { entityId: string; deploymentName: string }
+interface RestartBody   { namespace?: string; cluster?: string }
+
+/**
+ * Creates Fastify route handlers for the Kubernetes plugin.
+ * All routes are mounted under /api/v1/plugins/kubernetes/ by the plugin loader.
+ *
+ * Routes:
+ *   GET  clusters
+ *   GET  entities/:entityId/workloads
+ *   GET  entities/:entityId/pods/:podName/logs
+ *   POST entities/:entityId/deployments/:deploymentName/restart
+ */
+export function createRoutes(
+  clusters:         ClusterConfig[],
+  defaultNamespace: string,
+) {
+  return async function handler(fastify: FastifyInstance): Promise<void> {
+    /**
+     * GET /clusters
+     *
+     * Returns the list of configured cluster names and URLs (no tokens).
+     */
+    fastify.get('clusters', async (_request: FastifyRequest, reply: FastifyReply) => {
+      return reply.send({
+        data: clusters.map((c) => ({
+          name:          c.name,
+          url:           c.url,
+          skipTLSVerify: c.skipTLSVerify,
+        })),
+      });
+    });
+
+    /**
+     * GET /entities/:entityId/workloads
+     *
+     * Query params:
+     *   labelSelector  (required) — K8s label selector, e.g. "app=payment-api"
+     *   namespace      (optional) — K8s namespace, defaults to plugin defaultNamespace
+     *   cluster        (optional) — cluster name, defaults to first configured cluster
+     */
+    fastify.get(
+      'entities/:entityId/workloads',
+      async (
+        request: FastifyRequest<{ Params: WorkloadsParams; Querystring: WorkloadsQuery }>,
+        reply:   FastifyReply,
+      ) => {
+        const { labelSelector, namespace: ns, cluster: clusterName } = request.query;
+
+        if (!labelSelector) {
+          return reply.status(400).send({
+            error:   'Bad Request',
+            message: 'Query parameter "labelSelector" is required.',
+          });
+        }
+
+        const namespace = ns ?? defaultNamespace;
+
+        try {
+          const clusterCfg = resolveCluster(clusters, clusterName);
+          const client     = new KubernetesApiClient(clusterCfg);
+          const workloads  = await client.getWorkloads(namespace, labelSelector);
+          return reply.send({ data: workloads });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          request.log.error({ err }, 'kubernetes plugin: getWorkloads failed');
+          if (message.includes('not found')) {
+            return reply.status(404).send({ error: 'Not Found', message });
+          }
+          return reply.status(502).send({ error: 'Bad Gateway', message });
+        }
+      },
+    );
+
+    /**
+     * GET /entities/:entityId/pods/:podName/logs
+     *
+     * Query params:
+     *   namespace  (optional)
+     *   cluster    (optional)
+     *   tail       (optional, default 100) — number of log lines to return
+     */
+    fastify.get(
+      'entities/:entityId/pods/:podName/logs',
+      async (
+        request: FastifyRequest<{ Params: LogsParams; Querystring: LogsQuery }>,
+        reply:   FastifyReply,
+      ) => {
+        const { podName }                                   = request.params;
+        const { namespace: ns, cluster: clusterName, tail } = request.query;
+
+        const namespace = ns ?? defaultNamespace;
+        const tailLines = tail ? parseInt(tail, 10) : 100;
+
+        try {
+          const clusterCfg = resolveCluster(clusters, clusterName);
+          const client     = new KubernetesApiClient(clusterCfg);
+          const logs       = await client.getPodLogs(namespace, podName, tailLines);
+          return reply.send({ data: { logs } });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          request.log.error({ err }, 'kubernetes plugin: getPodLogs failed');
+          return reply.status(502).send({ error: 'Bad Gateway', message });
+        }
+      },
+    );
+
+    /**
+     * POST /entities/:entityId/deployments/:deploymentName/restart
+     *
+     * Body: { namespace?: string; cluster?: string }
+     */
+    fastify.post(
+      'entities/:entityId/deployments/:deploymentName/restart',
+      async (
+        request: FastifyRequest<{ Params: RestartParams; Body: RestartBody }>,
+        reply:   FastifyReply,
+      ) => {
+        const { deploymentName }                          = request.params;
+        const { namespace: ns, cluster: clusterName } = request.body ?? {};
+
+        const namespace = ns ?? defaultNamespace;
+
+        try {
+          const clusterCfg = resolveCluster(clusters, clusterName);
+          const client     = new KubernetesApiClient(clusterCfg);
+          await client.restartDeployment(namespace, deploymentName);
+          return reply.status(202).send({
+            data: {
+              deploymentName,
+              namespace,
+              cluster:     clusterCfg.name,
+              restartedAt: new Date().toISOString(),
+            },
+          });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          request.log.error({ err }, 'kubernetes plugin: restartDeployment failed');
+          return reply.status(502).send({ error: 'Bad Gateway', message });
+        }
+      },
+    );
+  };
+}

package/src/types.ts

@@ -0,0 +1,103 @@
+// ─── Cluster config ──────────────────────────────────────────────────────────
+
+export interface ClusterConfig {
+  name:          string;
+  url:           string;
+  /** Service-account token. Sourced from FORGEPORTAL_PLUGIN_KUBERNETES_<NAME>_TOKEN. */
+  token:         string;
+  skipTLSVerify: boolean;
+}
+
+// ─── Normalised K8s resource types returned by the plugin API ────────────────
+
+export interface K8sDeployment {
+  name:        string;
+  namespace:   string;
+  replicas:    { desired: number; ready: number; available: number };
+  image:       string;
+  lastRollout: string | null;
+  healthy:     boolean;
+}
+
+export interface K8sPod {
+  name:       string;
+  namespace:  string;
+  /** e.g. "Running" | "Pending" | "CrashLoopBackOff" | "Completed" */
+  status:     string;
+  ready:      boolean;
+  containers: number;
+  nodeName:   string | null;
+  startTime:  string | null;
+}
+
+export interface K8sService {
+  name:      string;
+  namespace: string;
+  type:      string;
+  clusterIp: string;
+  ports:     Array<{ port: number; protocol: string; targetPort: string | number }>;
+}
+
+export interface K8sIngress {
+  name:      string;
+  namespace: string;
+  hosts:     string[];
+  tls:       boolean;
+}
+
+export interface WorkloadsResponse {
+  cluster:       string;
+  namespace:     string;
+  labelSelector: string;
+  deployments:   K8sDeployment[];
+  pods:          K8sPod[];
+  services:      K8sService[];
+  ingresses:     K8sIngress[];
+}
+
+// ─── Raw K8s API shapes (minimal subset) ─────────────────────────────────────
+
+export interface RawDeployment {
+  metadata: { name: string; namespace: string; creationTimestamp?: string };
+  spec:     {
+    replicas?: number;
+    template: { spec: { containers: Array<{ image?: string }> } };
+  };
+  status?: {
+    replicas?:          number;
+    readyReplicas?:     number;
+    availableReplicas?: number;
+    conditions?:        Array<{ type: string; status: string; lastUpdateTime?: string }>;
+  };
+}
+
+export interface RawPod {
+  metadata: { name: string; namespace: string };
+  spec?:    { nodeName?: string; containers?: Array<{ name: string }> };
+  status?:  {
+    phase?:             string;
+    startTime?:         string;
+    conditions?:        Array<{ type: string; status: string }>;
+    containerStatuses?: Array<{
+      ready?: boolean;
+      state?: { waiting?: { reason?: string } };
+    }>;
+  };
+}
+
+export interface RawService {
+  metadata: { name: string; namespace: string };
+  spec?: {
+    type?:      string;
+    clusterIP?: string;
+    ports?:     Array<{ port: number; protocol?: string; targetPort?: string | number }>;
+  };
+}
+
+export interface RawIngress {
+  metadata: { name: string; namespace: string };
+  spec?: {
+    tls?:   unknown[];
+    rules?: Array<{ host?: string }>;
+  };
+}

package/src/ui.ts

@@ -0,0 +1,19 @@
+import type { ForgePluginSDK } from '@forgeportal/plugin-sdk';
+import { KubernetesTab } from './KubernetesTab.js';
+
+/**
+ * UI entry point for the Kubernetes plugin.
+ * Called by the ForgePortal UI shell at startup.
+ *
+ * Registration in apps/ui/src/plugins/index.ts:
+ *   import { registerPlugin as registerKubernetes } from '@forgeportal/plugin-kubernetes/ui';
+ *   registerPluginById('kubernetes', registerKubernetes);
+ */
+export function registerPlugin(sdk: ForgePluginSDK): void {
+  sdk.registerEntityTab({
+    id:        'kubernetes-tab',
+    title:     'Kubernetes',
+    component: KubernetesTab,
+    // No appliesTo restriction — the tab component handles missing annotation gracefully
+  });
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir":         "dist",
+    "rootDir":        "src",
+    "jsx":            "react-jsx",
+    "declaration":    true,
+    "declarationMap": true
+  },
+  "include": ["src"]
+}