@intentius/chant-lexicon-k8s 0.0.12 → 0.0.14

package/src/composites/monitored-service.ts

@@ -0,0 +1,215 @@
+/**
+ * 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.
+ */
+
+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 }>;
+}
+
+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,
+  } = 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 }),
+            },
+          ],
+        },
+      },
+    },
+  };
+
+  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,196 @@
+/**
+ * NetworkIsolatedApp composite — Deployment + Service + NetworkPolicy.
+ *
+ * Per-app allow rules beyond NamespaceEnv's default-deny.
+ * Creates fine-grained ingress/egress policies for a single application.
+ */
+
+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 }>;
+}
+
+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,
+  } = 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 }),
+            },
+          ],
+        },
+      },
+    },
+  };
+
+  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/secure-ingress.ts

@@ -0,0 +1,149 @@
+/**
+ * SecureIngress composite — Ingress + optional cert-manager Certificate.
+ *
+ * A standalone Ingress with TLS via cert-manager, supporting
+ * multiple hosts and paths (unlike the single-path Ingress in WebApp).
+ */
+
+export interface SecureIngressHost {
+  /** Hostname (e.g., "api.example.com"). */
+  hostname: string;
+  /** Path rules for this host. */
+  paths: Array<{
+    path: string;
+    pathType?: string;
+    serviceName: string;
+    servicePort: number;
+  }>;
+}
+
+export interface SecureIngressProps {
+  /** Ingress name — used in metadata and labels. */
+  name: string;
+  /** Host definitions with paths. */
+  hosts: SecureIngressHost[];
+  /** cert-manager ClusterIssuer name — if set, creates a Certificate resource. */
+  clusterIssuer?: string;
+  /** Ingress class name (e.g., "nginx"). */
+  ingressClassName?: string;
+  /** Additional annotations on the Ingress. */
+  annotations?: Record<string, string>;
+  /** Additional labels to apply to all resources. */
+  labels?: Record<string, string>;
+  /** Namespace for all resources. */
+  namespace?: string;
+}
+
+export interface SecureIngressResult {
+  ingress: Record<string, unknown>;
+  certificate?: Record<string, unknown>;
+}
+
+/**
+ * Create a SecureIngress composite — returns prop objects for
+ * an Ingress and optional cert-manager Certificate.
+ *
+ * @example
+ * ```ts
+ * import { SecureIngress } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { ingress, certificate } = SecureIngress({
+ *   name: "api-ingress",
+ *   hosts: [
+ *     {
+ *       hostname: "api.example.com",
+ *       paths: [{ path: "/", serviceName: "api", servicePort: 80 }],
+ *     },
+ *   ],
+ *   clusterIssuer: "letsencrypt-prod",
+ *   ingressClassName: "nginx",
+ * });
+ * ```
+ */
+export function SecureIngress(props: SecureIngressProps): SecureIngressResult {
+  const {
+    name,
+    hosts,
+    clusterIssuer,
+    ingressClassName,
+    annotations: extraAnnotations = {},
+    labels: extraLabels = {},
+    namespace,
+  } = props;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  const allHostnames = hosts.map((h) => h.hostname);
+  const secretName = `${name}-tls`;
+
+  const ingressAnnotations: Record<string, string> = {
+    ...extraAnnotations,
+  };
+  if (clusterIssuer) {
+    ingressAnnotations["cert-manager.io/cluster-issuer"] = clusterIssuer;
+  }
+
+  const ingressRules = hosts.map((host) => ({
+    host: host.hostname,
+    http: {
+      paths: host.paths.map((p) => ({
+        path: p.path,
+        pathType: p.pathType ?? "Prefix",
+        backend: {
+          service: { name: p.serviceName, port: { number: p.servicePort } },
+        },
+      })),
+    },
+  }));
+
+  const hasAnnotations = Object.keys(ingressAnnotations).length > 0;
+
+  const ingressProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "ingress" },
+      ...(hasAnnotations && { annotations: ingressAnnotations }),
+    },
+    spec: {
+      ...(ingressClassName && { ingressClassName }),
+      rules: ingressRules,
+      ...(clusterIssuer && {
+        tls: [
+          {
+            hosts: allHostnames,
+            secretName,
+          },
+        ],
+      }),
+    },
+  };
+
+  const result: SecureIngressResult = {
+    ingress: ingressProps,
+  };
+
+  if (clusterIssuer) {
+    result.certificate = {
+      metadata: {
+        name: secretName,
+        ...(namespace && { namespace }),
+        labels: { ...commonLabels, "app.kubernetes.io/component": "certificate" },
+      },
+      spec: {
+        secretName,
+        issuerRef: {
+          name: clusterIssuer,
+          kind: "ClusterIssuer",
+        },
+        dnsNames: allHostnames,
+      },
+    };
+  }
+
+  return result;
+}