@intentius/chant-lexicon-k8s 0.0.12

package/src/composites/cron-workload.ts

@@ -0,0 +1,167 @@
+/**
+ * CronWorkload composite — CronJob + ServiceAccount + Role + RoleBinding.
+ *
+ * A higher-level construct for deploying scheduled workloads with
+ * proper RBAC permissions.
+ */
+
+export interface CronWorkloadProps {
+  /** Workload name — used in metadata and labels. */
+  name: string;
+  /** Container image. */
+  image: string;
+  /** Cron schedule expression (e.g., "0 * * * *"). */
+  schedule: string;
+  /** Command to run in the container. */
+  command?: string[];
+  /** Arguments to the command. */
+  args?: string[];
+  /** RBAC rules for the service account. */
+  rbacRules?: Array<{
+    apiGroups: string[];
+    resources: string[];
+    verbs: string[];
+  }>;
+  /** Job history limits. */
+  successfulJobsHistoryLimit?: number;
+  failedJobsHistoryLimit?: number;
+  /** Restart policy for the job (default: "OnFailure"). */
+  restartPolicy?: string;
+  /** Additional labels to apply to all resources. */
+  labels?: Record<string, string>;
+  /** Namespace for all resources. */
+  namespace?: string;
+  /** Environment variables. */
+  env?: Array<{ name: string; value: string }>;
+}
+
+export interface CronWorkloadResult {
+  cronJob: Record<string, unknown>;
+  serviceAccount: Record<string, unknown>;
+  role: Record<string, unknown>;
+  roleBinding: Record<string, unknown>;
+}
+
+/**
+ * Create a CronWorkload composite — returns prop objects for
+ * a CronJob, ServiceAccount, Role, and RoleBinding.
+ *
+ * @example
+ * ```ts
+ * import { CronWorkload } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { cronJob, serviceAccount, role, roleBinding } = CronWorkload({
+ *   name: "db-backup",
+ *   image: "postgres:16",
+ *   schedule: "0 2 * * *",
+ *   command: ["pg_dump", "-h", "postgres", "mydb"],
+ *   rbacRules: [
+ *     { apiGroups: [""], resources: ["secrets"], verbs: ["get"] },
+ *   ],
+ * });
+ * ```
+ */
+export function CronWorkload(props: CronWorkloadProps): CronWorkloadResult {
+  const {
+    name,
+    image,
+    schedule,
+    command,
+    args,
+    rbacRules = [],
+    successfulJobsHistoryLimit = 3,
+    failedJobsHistoryLimit = 1,
+    restartPolicy = "OnFailure",
+    labels: extraLabels = {},
+    namespace,
+    env,
+  } = props;
+
+  const saName = `${name}-sa`;
+  const roleName = `${name}-role`;
+  const bindingName = `${name}-binding`;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  const cronJobProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "worker" },
+    },
+    spec: {
+      schedule,
+      successfulJobsHistoryLimit,
+      failedJobsHistoryLimit,
+      jobTemplate: {
+        spec: {
+          template: {
+            spec: {
+              serviceAccountName: saName,
+              restartPolicy,
+              containers: [
+                {
+                  name,
+                  image,
+                  ...(command && { command }),
+                  ...(args && { args }),
+                  ...(env && { env }),
+                },
+              ],
+            },
+          },
+        },
+      },
+    },
+  };
+
+  const serviceAccountProps: Record<string, unknown> = {
+    metadata: {
+      name: saName,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "worker" },
+    },
+  };
+
+  const roleProps: Record<string, unknown> = {
+    metadata: {
+      name: roleName,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+    },
+    rules: rbacRules.length > 0 ? rbacRules : [
+      { apiGroups: [""], resources: ["pods"], verbs: ["get", "list"] },
+    ],
+  };
+
+  const roleBindingProps: Record<string, unknown> = {
+    metadata: {
+      name: bindingName,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+    },
+    roleRef: {
+      apiGroup: "rbac.authorization.k8s.io",
+      kind: "Role",
+      name: roleName,
+    },
+    subjects: [
+      {
+        kind: "ServiceAccount",
+        name: saName,
+        ...(namespace && { namespace }),
+      },
+    ],
+  };
+
+  return {
+    cronJob: cronJobProps,
+    serviceAccount: serviceAccountProps,
+    role: roleProps,
+    roleBinding: roleBindingProps,
+  };
+}

package/src/composites/index.ts

@@ -0,0 +1,14 @@
+export { WebApp } from "./web-app";
+export type { WebAppProps, WebAppResult } from "./web-app";
+export { StatefulApp } from "./stateful-app";
+export type { StatefulAppProps, StatefulAppResult } from "./stateful-app";
+export { CronWorkload } from "./cron-workload";
+export type { CronWorkloadProps, CronWorkloadResult } from "./cron-workload";
+export { AutoscaledService } from "./autoscaled-service";
+export type { AutoscaledServiceProps, AutoscaledServiceResult } from "./autoscaled-service";
+export { WorkerPool } from "./worker-pool";
+export type { WorkerPoolProps, WorkerPoolResult } from "./worker-pool";
+export { NamespaceEnv } from "./namespace-env";
+export type { NamespaceEnvProps, NamespaceEnvResult } from "./namespace-env";
+export { NodeAgent } from "./node-agent";
+export type { NodeAgentProps, NodeAgentResult } from "./node-agent";

package/src/composites/namespace-env.ts

@@ -0,0 +1,163 @@
+/**
+ * NamespaceEnv composite — Namespace + optional ResourceQuota + LimitRange + NetworkPolicy.
+ *
+ * A higher-level construct for multi-tenant namespace provisioning with
+ * resource guardrails and network isolation.
+ */
+
+export interface NamespaceEnvProps {
+  /** Namespace name. */
+  name: string;
+  /** Total namespace CPU quota (e.g., "8"). */
+  cpuQuota?: string;
+  /** Total namespace memory quota (e.g., "16Gi"). */
+  memoryQuota?: string;
+  /** Maximum pods in namespace. */
+  maxPods?: number;
+  /** LimitRange default CPU request (e.g., "100m"). */
+  defaultCpuRequest?: string;
+  /** LimitRange default memory request (e.g., "128Mi"). */
+  defaultMemoryRequest?: string;
+  /** LimitRange default CPU limit (e.g., "500m"). */
+  defaultCpuLimit?: string;
+  /** LimitRange default memory limit (e.g., "512Mi"). */
+  defaultMemoryLimit?: string;
+  /** Create default-deny ingress NetworkPolicy (default: true). */
+  defaultDenyIngress?: boolean;
+  /** Create default-deny egress NetworkPolicy (default: false). */
+  defaultDenyEgress?: boolean;
+  /** Additional labels to apply to all resources. */
+  labels?: Record<string, string>;
+}
+
+export interface NamespaceEnvResult {
+  namespace: Record<string, unknown>;
+  resourceQuota?: Record<string, unknown>;
+  limitRange?: Record<string, unknown>;
+  networkPolicy?: Record<string, unknown>;
+}
+
+/**
+ * Create a NamespaceEnv composite — returns prop objects for
+ * a Namespace, optional ResourceQuota, LimitRange, and NetworkPolicy.
+ *
+ * @example
+ * ```ts
+ * import { NamespaceEnv } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { namespace, resourceQuota, limitRange, networkPolicy } = NamespaceEnv({
+ *   name: "team-alpha",
+ *   cpuQuota: "8",
+ *   memoryQuota: "16Gi",
+ *   defaultCpuRequest: "100m",
+ *   defaultMemoryRequest: "128Mi",
+ *   defaultDenyIngress: true,
+ * });
+ * ```
+ */
+export function NamespaceEnv(props: NamespaceEnvProps): NamespaceEnvResult {
+  const {
+    name,
+    cpuQuota,
+    memoryQuota,
+    maxPods,
+    defaultCpuRequest,
+    defaultMemoryRequest,
+    defaultCpuLimit,
+    defaultMemoryLimit,
+    defaultDenyIngress = true,
+    defaultDenyEgress = false,
+    labels: extraLabels = {},
+  } = props;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  const namespaceProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "namespace" },
+    },
+  };
+
+  const result: NamespaceEnvResult = {
+    namespace: namespaceProps,
+  };
+
+  // ResourceQuota — only if at least one quota prop is set
+  const hasQuota = cpuQuota || memoryQuota || maxPods !== undefined;
+  if (hasQuota) {
+    const hard: Record<string, unknown> = {};
+    if (cpuQuota) hard["limits.cpu"] = cpuQuota;
+    if (memoryQuota) hard["limits.memory"] = memoryQuota;
+    if (maxPods !== undefined) hard.pods = String(maxPods);
+
+    result.resourceQuota = {
+      metadata: {
+        name: `${name}-quota`,
+        namespace: name,
+        labels: { ...commonLabels, "app.kubernetes.io/component": "quota" },
+      },
+      spec: { hard },
+    };
+  }
+
+  // LimitRange — only if at least one default limit prop is set
+  const hasLimits = defaultCpuRequest || defaultMemoryRequest || defaultCpuLimit || defaultMemoryLimit;
+
+  if (hasQuota && !hasLimits) {
+    console.warn(
+      `[NamespaceEnv] "${name}": ResourceQuota set but no LimitRange defaults. ` +
+      `Pods without explicit resource requests will fail to schedule.`
+    );
+  }
+  if (hasLimits) {
+    const defaultLimits: Record<string, string> = {};
+    const defaultRequests: Record<string, string> = {};
+
+    if (defaultCpuLimit) defaultLimits.cpu = defaultCpuLimit;
+    if (defaultMemoryLimit) defaultLimits.memory = defaultMemoryLimit;
+    if (defaultCpuRequest) defaultRequests.cpu = defaultCpuRequest;
+    if (defaultMemoryRequest) defaultRequests.memory = defaultMemoryRequest;
+
+    const limit: Record<string, unknown> = { type: "Container" };
+    if (Object.keys(defaultLimits).length > 0) limit.default = defaultLimits;
+    if (Object.keys(defaultRequests).length > 0) limit.defaultRequest = defaultRequests;
+
+    result.limitRange = {
+      metadata: {
+        name: `${name}-limits`,
+        namespace: name,
+        labels: { ...commonLabels, "app.kubernetes.io/component": "limits" },
+      },
+      spec: {
+        limits: [limit],
+      },
+    };
+  }
+
+  // NetworkPolicy — default-deny ingress and/or egress
+  const hasNetworkPolicy = defaultDenyIngress || defaultDenyEgress;
+  if (hasNetworkPolicy) {
+    const policyTypes: string[] = [];
+    if (defaultDenyIngress) policyTypes.push("Ingress");
+    if (defaultDenyEgress) policyTypes.push("Egress");
+
+    result.networkPolicy = {
+      metadata: {
+        name: `${name}-default-deny`,
+        namespace: name,
+        labels: { ...commonLabels, "app.kubernetes.io/component": "network-policy" },
+      },
+      spec: {
+        podSelector: {},
+        policyTypes,
+      },
+    };
+  }
+
+  return result;
+}

package/src/composites/node-agent.ts

@@ -0,0 +1,224 @@
+/**
+ * NodeAgent composite — DaemonSet + ServiceAccount + ClusterRole + ClusterRoleBinding + optional ConfigMap.
+ *
+ * A higher-level construct for per-node agents (Fluentd, Prometheus Node Exporter,
+ * security scanners) that need cluster-wide RBAC and tolerations.
+ */
+
+export interface NodeAgentProps {
+  /** Agent name — used in metadata and labels. */
+  name: string;
+  /** Container image. */
+  image: string;
+  /** Metrics port (optional). */
+  port?: number;
+  /** Host path mounts. */
+  hostPaths?: Array<{
+    name: string;
+    hostPath: string;
+    mountPath: string;
+    readOnly?: boolean;
+  }>;
+  /** Config data — creates a ConfigMap mounted at /etc/{name}/. */
+  config?: Record<string, string>;
+  /** ClusterRole RBAC rules (required). */
+  rbacRules: Array<{
+    apiGroups: string[];
+    resources: string[];
+    verbs: string[];
+  }>;
+  /** Tolerate all taints so agent runs on every node (default: true). */
+  tolerateAllTaints?: boolean;
+  /** Namespace for namespaced resources (DaemonSet, ServiceAccount, ConfigMap). */
+  namespace?: string;
+  /** Additional labels to apply to all resources. */
+  labels?: Record<string, string>;
+  /** CPU request (default: "50m"). */
+  cpuRequest?: string;
+  /** Memory request (default: "64Mi"). */
+  memoryRequest?: string;
+  /** CPU limit (default: "200m"). */
+  cpuLimit?: string;
+  /** Memory limit (default: "128Mi"). */
+  memoryLimit?: string;
+  /** Environment variables for the container. */
+  env?: Array<{ name: string; value: string }>;
+}
+
+export interface NodeAgentResult {
+  daemonSet: Record<string, unknown>;
+  serviceAccount: Record<string, unknown>;
+  clusterRole: Record<string, unknown>;
+  clusterRoleBinding: Record<string, unknown>;
+  configMap?: Record<string, unknown>;
+}
+
+/**
+ * Create a NodeAgent composite — returns prop objects for
+ * a DaemonSet, ServiceAccount, ClusterRole, ClusterRoleBinding, and optional ConfigMap.
+ *
+ * @example
+ * ```ts
+ * import { NodeAgent } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { daemonSet, serviceAccount, clusterRole, clusterRoleBinding } = NodeAgent({
+ *   name: "log-collector",
+ *   image: "fluentd:v1.16",
+ *   hostPaths: [{ name: "varlog", hostPath: "/var/log", mountPath: "/var/log" }],
+ *   rbacRules: [
+ *     { apiGroups: [""], resources: ["pods", "namespaces"], verbs: ["get", "list", "watch"] },
+ *   ],
+ * });
+ * ```
+ */
+export function NodeAgent(props: NodeAgentProps): NodeAgentResult {
+  const {
+    name,
+    image,
+    port,
+    hostPaths = [],
+    config,
+    rbacRules,
+    tolerateAllTaints = true,
+    namespace,
+    cpuRequest = "50m",
+    memoryRequest = "64Mi",
+    cpuLimit = "200m",
+    memoryLimit = "128Mi",
+    labels: extraLabels = {},
+    env,
+  } = props;
+
+  const saName = `${name}-sa`;
+  const clusterRoleName = `${name}-role`;
+  const bindingName = `${name}-binding`;
+  const configMapName = `${name}-config`;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  // Build volumes and volumeMounts from hostPaths
+  const volumes: Array<Record<string, unknown>> = [];
+  const volumeMounts: Array<Record<string, unknown>> = [];
+
+  for (const hp of hostPaths) {
+    volumes.push({
+      name: hp.name,
+      hostPath: { path: hp.hostPath },
+    });
+    volumeMounts.push({
+      name: hp.name,
+      mountPath: hp.mountPath,
+      readOnly: hp.readOnly !== false,
+    });
+  }
+
+  // ConfigMap volume
+  if (config) {
+    volumes.push({
+      name: "config",
+      configMap: { name: configMapName },
+    });
+    volumeMounts.push({
+      name: "config",
+      mountPath: `/etc/${name}`,
+      readOnly: true,
+    });
+  }
+
+  const container: Record<string, unknown> = {
+    name,
+    image,
+    ...(port && { ports: [{ containerPort: port, name: "metrics" }] }),
+    resources: {
+      requests: { cpu: cpuRequest, memory: memoryRequest },
+      limits: { cpu: cpuLimit, memory: memoryLimit },
+    },
+    ...(env && { env }),
+    ...(volumeMounts.length > 0 && { volumeMounts }),
+  };
+
+  const podSpec: Record<string, unknown> = {
+    serviceAccountName: saName,
+    containers: [container],
+    ...(volumes.length > 0 && { volumes }),
+    ...(tolerateAllTaints && {
+      tolerations: [{ operator: "Exists" }],
+    }),
+  };
+
+  const daemonSetProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "agent" },
+    },
+    spec: {
+      selector: { matchLabels: { "app.kubernetes.io/name": name } },
+      template: {
+        metadata: { labels: { "app.kubernetes.io/name": name, ...extraLabels } },
+        spec: podSpec,
+      },
+    },
+  };
+
+  const serviceAccountProps: Record<string, unknown> = {
+    metadata: {
+      name: saName,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "agent" },
+    },
+  };
+
+  // ClusterRole — cluster-scoped, no namespace
+  const clusterRoleProps: Record<string, unknown> = {
+    metadata: {
+      name: clusterRoleName,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+    },
+    rules: rbacRules,
+  };
+
+  // ClusterRoleBinding — cluster-scoped, no namespace
+  const clusterRoleBindingProps: Record<string, unknown> = {
+    metadata: {
+      name: bindingName,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+    },
+    roleRef: {
+      apiGroup: "rbac.authorization.k8s.io",
+      kind: "ClusterRole",
+      name: clusterRoleName,
+    },
+    subjects: [
+      {
+        kind: "ServiceAccount",
+        name: saName,
+        ...(namespace && { namespace }),
+      },
+    ],
+  };
+
+  const result: NodeAgentResult = {
+    daemonSet: daemonSetProps,
+    serviceAccount: serviceAccountProps,
+    clusterRole: clusterRoleProps,
+    clusterRoleBinding: clusterRoleBindingProps,
+  };
+
+  if (config) {
+    result.configMap = {
+      metadata: {
+        name: configMapName,
+        ...(namespace && { namespace }),
+        labels: { ...commonLabels, "app.kubernetes.io/component": "config" },
+      },
+      data: config,
+    };
+  }
+
+  return result;
+}

package/src/composites/stateful-app.ts

@@ -0,0 +1,134 @@
+/**
+ * StatefulApp composite — StatefulSet + headless Service + PVC template.
+ *
+ * A higher-level construct for deploying stateful applications
+ * like databases, caches, and message queues.
+ */
+
+export interface StatefulAppProps {
+  /** Application name — used in metadata and labels. */
+  name: string;
+  /** Container image (e.g., "postgres:16"). */
+  image: string;
+  /** Container port (default: 5432). */
+  port?: number;
+  /** Number of replicas (default: 1). */
+  replicas?: number;
+  /** Storage size for the PVC (e.g., "10Gi"). */
+  storageSize?: string;
+  /** Storage class name. */
+  storageClassName?: string;
+  /** Volume mount path inside the container (default: "/data"). */
+  mountPath?: string;
+  /** Additional labels to apply to all resources. */
+  labels?: Record<string, string>;
+  /** CPU limit (e.g., "1"). */
+  cpuLimit?: string;
+  /** Memory limit (e.g., "1Gi"). */
+  memoryLimit?: string;
+  /** Namespace for all resources. */
+  namespace?: string;
+  /** Environment variables for the container. */
+  env?: Array<{ name: string; value: string }>;
+}
+
+export interface StatefulAppResult {
+  statefulSet: Record<string, unknown>;
+  service: Record<string, unknown>;
+}
+
+/**
+ * Create a StatefulApp composite — returns prop objects for
+ * a StatefulSet and headless Service.
+ *
+ * @example
+ * ```ts
+ * import { StatefulApp } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { statefulSet, service } = StatefulApp({
+ *   name: "postgres",
+ *   image: "postgres:16",
+ *   port: 5432,
+ *   storageSize: "20Gi",
+ *   env: [{ name: "POSTGRES_PASSWORD", value: "changeme" }],
+ * });
+ * ```
+ */
+export function StatefulApp(props: StatefulAppProps): StatefulAppResult {
+  const {
+    name,
+    image,
+    port = 5432,
+    replicas = 1,
+    storageSize = "10Gi",
+    storageClassName,
+    mountPath = "/data",
+    labels: extraLabels = {},
+    cpuLimit = "1",
+    memoryLimit = "1Gi",
+    namespace,
+    env,
+  } = props;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  const statefulSetProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "database" },
+    },
+    spec: {
+      serviceName: name,
+      replicas,
+      selector: { matchLabels: { "app.kubernetes.io/name": name } },
+      template: {
+        metadata: { labels: { "app.kubernetes.io/name": name, ...extraLabels } },
+        spec: {
+          containers: [
+            {
+              name,
+              image,
+              ports: [{ containerPort: port, name: "app" }],
+              resources: {
+                limits: { cpu: cpuLimit, memory: memoryLimit },
+              },
+              volumeMounts: [{ name: "data", mountPath }],
+              ...(env && { env }),
+            },
+          ],
+        },
+      },
+      volumeClaimTemplates: [
+        {
+          metadata: { name: "data" },
+          spec: {
+            accessModes: ["ReadWriteOnce"],
+            ...(storageClassName && { storageClassName }),
+            resources: { requests: { storage: storageSize } },
+          },
+        },
+      ],
+    },
+  };
+
+  // Headless service (clusterIP: None) for StatefulSet DNS
+  const serviceProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "database" },
+    },
+    spec: {
+      selector: { "app.kubernetes.io/name": name },
+      ports: [{ port, targetPort: port, protocol: "TCP", name: "app" }],
+      clusterIP: "None",
+    },
+  };
+
+  return { statefulSet: statefulSetProps, service: serviceProps };
+}