@intentius/chant-lexicon-k8s 0.0.13 → 0.0.15

package/src/composites/metrics-server.ts

@@ -0,0 +1,224 @@
+/**
+ * MetricsServer composite — Deployment + Service + ServiceAccount + RBAC + APIService.
+ *
+ * Deploys metrics-server for HPA pod CPU/memory metrics. metrics-server is not an
+ * EKS managed addon — it needs K8s workloads. Uses in-cluster RBAC only (no IRSA).
+ */
+
+export interface MetricsServerProps {
+  /** Agent name (default: "metrics-server"). */
+  name?: string;
+  /** Container image (default: "registry.k8s.io/metrics-server/metrics-server:v0.7.2"). */
+  image?: string;
+  /** Replicas (default: 1). */
+  replicas?: number;
+  /** Namespace (default: "kube-system"). */
+  namespace?: string;
+  /** Additional labels. */
+  labels?: Record<string, string>;
+}
+
+export interface MetricsServerResult {
+  deployment: Record<string, unknown>;
+  service: Record<string, unknown>;
+  serviceAccount: Record<string, unknown>;
+  clusterRole: Record<string, unknown>;
+  clusterRoleBinding: Record<string, unknown>;
+  /** ClusterRole for aggregated API access. */
+  aggregatedClusterRole: Record<string, unknown>;
+  /** Binding for aggregated API auth-delegator. */
+  authDelegatorBinding: Record<string, unknown>;
+  /** APIService registration for v1beta1.metrics.k8s.io. */
+  apiService: Record<string, unknown>;
+}
+
+/**
+ * Create a MetricsServer composite — returns prop objects for a Deployment,
+ * Service, ServiceAccount, ClusterRoles, ClusterRoleBindings, and APIService.
+ *
+ * @example
+ * ```ts
+ * import { MetricsServer } from "@intentius/chant-lexicon-k8s";
+ *
+ * const ms = MetricsServer({});
+ * ```
+ */
+export function MetricsServer(props: MetricsServerProps): MetricsServerResult {
+  const {
+    name = "metrics-server",
+    image = "registry.k8s.io/metrics-server/metrics-server:v0.7.2",
+    replicas = 1,
+    namespace = "kube-system",
+    labels: extraLabels = {},
+  } = props;
+
+  const saName = `${name}-sa`;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  const deployment: Record<string, unknown> = {
+    metadata: {
+      name,
+      namespace,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "metrics" },
+    },
+    spec: {
+      replicas,
+      selector: { matchLabels: { "app.kubernetes.io/name": name } },
+      template: {
+        metadata: { labels: { "app.kubernetes.io/name": name, ...extraLabels } },
+        spec: {
+          serviceAccountName: saName,
+          containers: [
+            {
+              name,
+              image,
+              args: [
+                "--cert-dir=/tmp",
+                "--secure-port=10250",
+                "--kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname",
+                "--kubelet-use-node-status-port",
+                "--metric-resolution=15s",
+              ],
+              ports: [{ containerPort: 10250, name: "https", protocol: "TCP" }],
+              resources: {
+                requests: { cpu: "100m", memory: "200Mi" },
+                limits: { cpu: "100m", memory: "200Mi" },
+              },
+              livenessProbe: {
+                httpGet: { path: "/livez", port: 10250, scheme: "HTTPS" },
+                initialDelaySeconds: 0,
+                periodSeconds: 10,
+                failureThreshold: 3,
+              },
+              readinessProbe: {
+                httpGet: { path: "/readyz", port: 10250, scheme: "HTTPS" },
+                initialDelaySeconds: 20,
+                periodSeconds: 10,
+                failureThreshold: 3,
+              },
+              securityContext: {
+                runAsNonRoot: true,
+                readOnlyRootFilesystem: true,
+                allowPrivilegeEscalation: false,
+              },
+              volumeMounts: [{ name: "tmp-dir", mountPath: "/tmp" }],
+            },
+          ],
+          volumes: [{ name: "tmp-dir", emptyDir: {} }],
+          priorityClassName: "system-cluster-critical",
+        },
+      },
+    },
+  };
+
+  const service: Record<string, unknown> = {
+    metadata: {
+      name,
+      namespace,
+      labels: {
+        ...commonLabels,
+        "app.kubernetes.io/component": "metrics",
+        "kubernetes.io/cluster-service": "true",
+        "kubernetes.io/name": "Metrics-server",
+      },
+    },
+    spec: {
+      selector: { "app.kubernetes.io/name": name },
+      ports: [{ port: 443, targetPort: 10250, protocol: "TCP", name: "https" }],
+    },
+  };
+
+  const serviceAccount: Record<string, unknown> = {
+    metadata: {
+      name: saName,
+      namespace,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "metrics" },
+    },
+  };
+
+  const clusterRole: Record<string, unknown> = {
+    metadata: {
+      name: `system:${name}`,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+    },
+    rules: [
+      { apiGroups: [""], resources: ["pods", "nodes", "namespaces", "configmaps"], verbs: ["get", "list", "watch"] },
+      { apiGroups: [""], resources: ["nodes/metrics", "nodes/stats"], verbs: ["get"] },
+    ],
+  };
+
+  const clusterRoleBinding: Record<string, unknown> = {
+    metadata: {
+      name: `system:${name}`,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+    },
+    roleRef: {
+      apiGroup: "rbac.authorization.k8s.io",
+      kind: "ClusterRole",
+      name: `system:${name}`,
+    },
+    subjects: [{ kind: "ServiceAccount", name: saName, namespace }],
+  };
+
+  const aggregatedClusterRole: Record<string, unknown> = {
+    metadata: {
+      name: `system:${name}-aggregated-reader`,
+      labels: {
+        ...commonLabels,
+        "app.kubernetes.io/component": "rbac",
+        "rbac.authorization.k8s.io/aggregate-to-admin": "true",
+        "rbac.authorization.k8s.io/aggregate-to-edit": "true",
+        "rbac.authorization.k8s.io/aggregate-to-view": "true",
+      },
+    },
+    rules: [
+      { apiGroups: ["metrics.k8s.io"], resources: ["pods", "nodes"], verbs: ["get", "list", "watch"] },
+    ],
+  };
+
+  const authDelegatorBinding: Record<string, unknown> = {
+    metadata: {
+      name: `${name}:system:auth-delegator`,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+    },
+    roleRef: {
+      apiGroup: "rbac.authorization.k8s.io",
+      kind: "ClusterRole",
+      name: "system:auth-delegator",
+    },
+    subjects: [{ kind: "ServiceAccount", name: saName, namespace }],
+  };
+
+  const apiService: Record<string, unknown> = {
+    apiVersion: "apiregistration.k8s.io/v1",
+    kind: "APIService",
+    metadata: {
+      name: "v1beta1.metrics.k8s.io",
+      labels: { ...commonLabels, "app.kubernetes.io/component": "metrics" },
+    },
+    spec: {
+      service: { name, namespace },
+      group: "metrics.k8s.io",
+      version: "v1beta1",
+      insecureSkipTLSVerify: true,
+      groupPriorityMinimum: 100,
+      versionPriority: 100,
+    },
+  };
+
+  return {
+    deployment,
+    service,
+    serviceAccount,
+    clusterRole,
+    clusterRoleBinding,
+    aggregatedClusterRole,
+    authDelegatorBinding,
+    apiService,
+  };
+}

package/src/composites/monitored-service.ts

@@ -0,0 +1,221 @@
+/**
+ * MonitoredService composite — Deployment + Service + ServiceMonitor + optional PrometheusRule.
+ *
+ * Observability pattern. ServiceMonitor and PrometheusRule are CRDs
+ * from the Prometheus Operator (monitoring.coreos.com/v1), returned
+ * as raw objects that can be serialized alongside native K8s resources.
+ */
+
+import type { ContainerSecurityContext } from "./security-context";
+
+export interface AlertRule {
+  /** Alert name. */
+  name: string;
+  /** PromQL expression. */
+  expr: string;
+  /** Duration before firing (e.g., "5m"). */
+  for?: string;
+  /** Severity label (e.g., "warning", "critical"). */
+  severity?: string;
+  /** Additional annotations (summary, description). */
+  annotations?: Record<string, string>;
+}
+
+export interface MonitoredServiceProps {
+  /** Application name — used in metadata and labels. */
+  name: string;
+  /** Container image. */
+  image: string;
+  /** Application container port (default: 80). */
+  port?: number;
+  /** Metrics port (default: 9090). */
+  metricsPort?: number;
+  /** Metrics path (default: "/metrics"). */
+  metricsPath?: string;
+  /** Scrape interval (default: "30s"). */
+  scrapeInterval?: string;
+  /** Alert rules — if provided, creates a PrometheusRule. */
+  alertRules?: AlertRule[];
+  /** Number of replicas (default: 2). */
+  replicas?: number;
+  /** Additional labels to apply to all resources. */
+  labels?: Record<string, string>;
+  /** CPU limit (default: "500m"). */
+  cpuLimit?: string;
+  /** Memory limit (default: "256Mi"). */
+  memoryLimit?: string;
+  /** CPU request (default: "100m"). */
+  cpuRequest?: string;
+  /** Memory request (default: "128Mi"). */
+  memoryRequest?: string;
+  /** Namespace for all resources. */
+  namespace?: string;
+  /** Environment variables for the container. */
+  env?: Array<{ name: string; value: string }>;
+  /** Container security context (supports PSS restricted fields). */
+  securityContext?: ContainerSecurityContext;
+}
+
+export interface MonitoredServiceResult {
+  deployment: Record<string, unknown>;
+  service: Record<string, unknown>;
+  serviceMonitor: Record<string, unknown>;
+  prometheusRule?: Record<string, unknown>;
+}
+
+/**
+ * Create a MonitoredService composite — returns prop objects for
+ * a Deployment, Service, ServiceMonitor, and optional PrometheusRule.
+ *
+ * @example
+ * ```ts
+ * import { MonitoredService } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { deployment, service, serviceMonitor, prometheusRule } = MonitoredService({
+ *   name: "api",
+ *   image: "api:1.0",
+ *   port: 8080,
+ *   metricsPort: 9090,
+ *   alertRules: [
+ *     { name: "HighErrorRate", expr: 'rate(http_errors_total[5m]) > 0.1', for: "5m", severity: "critical" },
+ *   ],
+ * });
+ * ```
+ */
+export function MonitoredService(props: MonitoredServiceProps): MonitoredServiceResult {
+  const {
+    name,
+    image,
+    port = 80,
+    metricsPort = 9090,
+    metricsPath = "/metrics",
+    scrapeInterval = "30s",
+    alertRules,
+    replicas = 2,
+    labels: extraLabels = {},
+    cpuLimit = "500m",
+    memoryLimit = "256Mi",
+    cpuRequest = "100m",
+    memoryRequest = "128Mi",
+    namespace,
+    env,
+    securityContext,
+  } = props;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  const ports: Array<Record<string, unknown>> = [
+    { containerPort: port, name: "http" },
+  ];
+  if (metricsPort !== port) {
+    ports.push({ containerPort: metricsPort, name: "metrics" });
+  }
+
+  const deploymentProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "server" },
+    },
+    spec: {
+      replicas,
+      selector: { matchLabels: { "app.kubernetes.io/name": name } },
+      template: {
+        metadata: { labels: { "app.kubernetes.io/name": name, ...extraLabels } },
+        spec: {
+          containers: [
+            {
+              name,
+              image,
+              ports,
+              resources: {
+                limits: { cpu: cpuLimit, memory: memoryLimit },
+                requests: { cpu: cpuRequest, memory: memoryRequest },
+              },
+              ...(env && { env }),
+              ...(securityContext && { securityContext }),
+            },
+          ],
+        },
+      },
+    },
+  };
+
+  const servicePorts: Array<Record<string, unknown>> = [
+    { port: 80, targetPort: port, protocol: "TCP", name: "http" },
+  ];
+  if (metricsPort !== port) {
+    servicePorts.push({ port: metricsPort, targetPort: metricsPort, protocol: "TCP", name: "metrics" });
+  }
+
+  const serviceProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "server" },
+    },
+    spec: {
+      selector: { "app.kubernetes.io/name": name },
+      ports: servicePorts,
+      type: "ClusterIP",
+    },
+  };
+
+  const serviceMonitorProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "monitoring" },
+    },
+    spec: {
+      selector: {
+        matchLabels: { "app.kubernetes.io/name": name },
+      },
+      endpoints: [
+        {
+          port: "metrics",
+          path: metricsPath,
+          interval: scrapeInterval,
+        },
+      ],
+    },
+  };
+
+  const result: MonitoredServiceResult = {
+    deployment: deploymentProps,
+    service: serviceProps,
+    serviceMonitor: serviceMonitorProps,
+  };
+
+  if (alertRules && alertRules.length > 0) {
+    result.prometheusRule = {
+      metadata: {
+        name: `${name}-alerts`,
+        ...(namespace && { namespace }),
+        labels: { ...commonLabels, "app.kubernetes.io/component": "monitoring" },
+      },
+      spec: {
+        groups: [
+          {
+            name: `${name}.rules`,
+            rules: alertRules.map((rule) => ({
+              alert: rule.name,
+              expr: rule.expr,
+              ...(rule.for && { for: rule.for }),
+              labels: {
+                ...(rule.severity && { severity: rule.severity }),
+              },
+              ...(rule.annotations && { annotations: rule.annotations }),
+            })),
+          },
+        ],
+      },
+    };
+  }
+
+  return result;
+}

package/src/composites/network-isolated-app.ts

@@ -0,0 +1,202 @@
+/**
+ * NetworkIsolatedApp composite — Deployment + Service + NetworkPolicy.
+ *
+ * Per-app allow rules beyond NamespaceEnv's default-deny.
+ * Creates fine-grained ingress/egress policies for a single application.
+ */
+
+import type { ContainerSecurityContext } from "./security-context";
+
+export interface NetworkPolicyPeer {
+  /** Pod selector for the peer. */
+  podSelector?: Record<string, string>;
+  /** Namespace selector for the peer. */
+  namespaceSelector?: Record<string, string>;
+}
+
+export interface NetworkPolicyEgressPeer extends NetworkPolicyPeer {
+  /** Allowed ports for egress. */
+  ports?: Array<{ port: number; protocol?: string }>;
+}
+
+export interface NetworkIsolatedAppProps {
+  /** Application name — used in metadata and labels. */
+  name: string;
+  /** Container image. */
+  image: string;
+  /** Container port (default: 80). */
+  port?: number;
+  /** Number of replicas (default: 2). */
+  replicas?: number;
+  /** Allowed ingress sources. */
+  allowIngressFrom?: NetworkPolicyPeer[];
+  /** Allowed egress destinations. */
+  allowEgressTo?: NetworkPolicyEgressPeer[];
+  /** Additional labels to apply to all resources. */
+  labels?: Record<string, string>;
+  /** CPU limit (default: "500m"). */
+  cpuLimit?: string;
+  /** Memory limit (default: "256Mi"). */
+  memoryLimit?: string;
+  /** CPU request (default: "100m"). */
+  cpuRequest?: string;
+  /** Memory request (default: "128Mi"). */
+  memoryRequest?: string;
+  /** Namespace for all resources. */
+  namespace?: string;
+  /** Environment variables for the container. */
+  env?: Array<{ name: string; value: string }>;
+  /** Container security context (supports PSS restricted fields). */
+  securityContext?: ContainerSecurityContext;
+}
+
+export interface NetworkIsolatedAppResult {
+  deployment: Record<string, unknown>;
+  service: Record<string, unknown>;
+  networkPolicy: Record<string, unknown>;
+}
+
+/**
+ * Create a NetworkIsolatedApp composite — returns prop objects for
+ * a Deployment, Service, and NetworkPolicy.
+ *
+ * @example
+ * ```ts
+ * import { NetworkIsolatedApp } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { deployment, service, networkPolicy } = NetworkIsolatedApp({
+ *   name: "api",
+ *   image: "api:1.0",
+ *   port: 8080,
+ *   allowIngressFrom: [
+ *     { podSelector: { "app.kubernetes.io/name": "frontend" } },
+ *   ],
+ *   allowEgressTo: [
+ *     { podSelector: { "app.kubernetes.io/name": "postgres" }, ports: [{ port: 5432 }] },
+ *   ],
+ * });
+ * ```
+ */
+export function NetworkIsolatedApp(props: NetworkIsolatedAppProps): NetworkIsolatedAppResult {
+  const {
+    name,
+    image,
+    port = 80,
+    replicas = 2,
+    allowIngressFrom,
+    allowEgressTo,
+    labels: extraLabels = {},
+    cpuLimit = "500m",
+    memoryLimit = "256Mi",
+    cpuRequest = "100m",
+    memoryRequest = "128Mi",
+    namespace,
+    env,
+    securityContext,
+  } = props;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  const deploymentProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "server" },
+    },
+    spec: {
+      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: "http" }],
+              resources: {
+                limits: { cpu: cpuLimit, memory: memoryLimit },
+                requests: { cpu: cpuRequest, memory: memoryRequest },
+              },
+              ...(env && { env }),
+              ...(securityContext && { securityContext }),
+            },
+          ],
+        },
+      },
+    },
+  };
+
+  const serviceProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "server" },
+    },
+    spec: {
+      selector: { "app.kubernetes.io/name": name },
+      ports: [{ port: 80, targetPort: port, protocol: "TCP", name: "http" }],
+      type: "ClusterIP",
+    },
+  };
+
+  // Build network policy
+  const policyTypes: string[] = [];
+  const policySpec: Record<string, unknown> = {
+    podSelector: { matchLabels: { "app.kubernetes.io/name": name } },
+  };
+
+  if (allowIngressFrom) {
+    policyTypes.push("Ingress");
+    policySpec.ingress = [
+      {
+        from: allowIngressFrom.map((peer) => ({
+          ...(peer.podSelector && { podSelector: { matchLabels: peer.podSelector } }),
+          ...(peer.namespaceSelector && { namespaceSelector: { matchLabels: peer.namespaceSelector } }),
+        })),
+        ports: [{ port, protocol: "TCP" }],
+      },
+    ];
+  }
+
+  if (allowEgressTo) {
+    policyTypes.push("Egress");
+    policySpec.egress = allowEgressTo.map((peer) => ({
+      to: [
+        {
+          ...(peer.podSelector && { podSelector: { matchLabels: peer.podSelector } }),
+          ...(peer.namespaceSelector && { namespaceSelector: { matchLabels: peer.namespaceSelector } }),
+        },
+      ],
+      ...(peer.ports && {
+        ports: peer.ports.map((p) => ({
+          port: p.port,
+          protocol: p.protocol ?? "TCP",
+        })),
+      }),
+    }));
+  }
+
+  if (policyTypes.length > 0) {
+    policySpec.policyTypes = policyTypes;
+  }
+
+  const networkPolicyProps: Record<string, unknown> = {
+    metadata: {
+      name: `${name}-policy`,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "network-policy" },
+    },
+    spec: policySpec,
+  };
+
+  return {
+    deployment: deploymentProps,
+    service: serviceProps,
+    networkPolicy: networkPolicyProps,
+  };
+}

package/src/composites/node-agent.ts

@@ -5,6 +5,8 @@
  * security scanners) that need cluster-wide RBAC and tolerations.
  */
 
+import type { ContainerSecurityContext } from "./security-context";
+
 export interface NodeAgentProps {
   /** Agent name — used in metadata and labels. */
   name: string;
@@ -43,6 +45,8 @@ export interface NodeAgentProps {
   memoryLimit?: string;
   /** Environment variables for the container. */
   env?: Array<{ name: string; value: string }>;
+  /** Container security context (supports PSS restricted fields). */
+  securityContext?: ContainerSecurityContext;
 }
 
 export interface NodeAgentResult {
@@ -87,6 +91,7 @@ export function NodeAgent(props: NodeAgentProps): NodeAgentResult {
     memoryLimit = "128Mi",
     labels: extraLabels = {},
     env,
+    securityContext,
   } = props;
 
   const saName = `${name}-sa`;
@@ -139,6 +144,7 @@ export function NodeAgent(props: NodeAgentProps): NodeAgentResult {
     },
     ...(env && { env }),
     ...(volumeMounts.length > 0 && { volumeMounts }),
+    ...(securityContext && { securityContext }),
   };
 
   const podSpec: Record<string, unknown> = {