@intentius/chant-lexicon-k8s 0.124.30 → 0.124.32

package/dist/composites/monitored-service.js

@@ -0,0 +1,152 @@
+/**
+ * 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.
+ *
+ * Rules come in two forms. `ruleGroups` takes `RuleGroup`s from the
+ * prometheus lexicon (`@intentius/chant-lexicon-prometheus`), typed and
+ * checked there, and rendered here exactly as they would be in a rule file.
+ * `alertRules` is the older shorthand for one group of alerts and still works.
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { ruleGroupConfig } from "@intentius/chant-lexicon-prometheus";
+import { Deployment, Service, ServiceMonitor, PrometheusRule } from "../generated/index.js";
+/**
+ * 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" },
+ *   ],
+ * });
+ *
+ * // Or with typed rule groups from the prometheus lexicon:
+ * import { RuleGroup } from "@intentius/chant-lexicon-prometheus";
+ * const apiRules = new RuleGroup({
+ *   name: "api",
+ *   rules: [{ alert: "ApiDown", expr: 'up{job="api"} == 0', for: "5m", labels: { severity: "page" } }],
+ * });
+ * MonitoredService({ name: "api", image: "api:1.0", ruleGroups: [apiRules] });
+ * ```
+ */
+export const MonitoredService = Composite((props) => {
+    const { name, image, port = 80, metricsPort = 9090, metricsPath = "/metrics", scrapeInterval = "30s", alertRules, ruleGroups, replicas = 2, labels: extraLabels = {}, cpuLimit = "500m", memoryLimit = "256Mi", cpuRequest = "100m", memoryRequest = "128Mi", namespace, env, securityContext, defaults: defs, } = props;
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        ...extraLabels,
+    };
+    const ports = [
+        { containerPort: port, name: "http" },
+    ];
+    if (metricsPort !== port) {
+        ports.push({ containerPort: metricsPort, name: "metrics" });
+    }
+    const deployment = new Deployment(mergeDefaults({
+        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 }),
+                        },
+                    ],
+                },
+            },
+        },
+    }, defs?.deployment));
+    const servicePorts = [
+        { port: 80, targetPort: port, protocol: "TCP", name: "http" },
+    ];
+    if (metricsPort !== port) {
+        servicePorts.push({ port: metricsPort, targetPort: metricsPort, protocol: "TCP", name: "metrics" });
+    }
+    const service = new Service(mergeDefaults({
+        metadata: {
+            name,
+            ...(namespace && { namespace }),
+            labels: { ...commonLabels, "app.kubernetes.io/component": "server" },
+        },
+        spec: {
+            selector: { "app.kubernetes.io/name": name },
+            ports: servicePorts,
+            type: "ClusterIP",
+        },
+    }, defs?.service));
+    const serviceMonitor = new ServiceMonitor(mergeDefaults({
+        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,
+                },
+            ],
+        },
+    }, defs?.serviceMonitor));
+    const result = { deployment, service, serviceMonitor };
+    const groups = [];
+    if (alertRules && alertRules.length > 0) {
+        groups.push({
+            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 }),
+            })),
+        });
+    }
+    for (const group of ruleGroups ?? []) {
+        groups.push(ruleGroupConfig(group));
+    }
+    if (groups.length > 0) {
+        result.prometheusRule = new PrometheusRule(mergeDefaults({
+            metadata: {
+                name: `${name}-alerts`,
+                ...(namespace && { namespace }),
+                labels: { ...commonLabels, "app.kubernetes.io/component": "monitoring" },
+            },
+            spec: { groups },
+        }, defs?.prometheusRule));
+    }
+    return result;
+}, "MonitoredService");

package/dist/composites/namespace-env.js

@@ -0,0 +1,114 @@
+/**
+ * NamespaceEnv composite — Namespace + optional ResourceQuota + LimitRange + NetworkPolicy.
+ *
+ * A higher-level construct for multi-tenant namespace provisioning with
+ * resource guardrails and network isolation.
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Namespace, ResourceQuota, LimitRange, NetworkPolicy } from "../generated/index.js";
+/**
+ * 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 const NamespaceEnv = Composite((props) => {
+    const { name, cpuQuota, memoryQuota, maxPods, defaultCpuRequest, defaultMemoryRequest, defaultCpuLimit, defaultMemoryLimit, defaultDenyIngress = true, defaultDenyEgress = false, labels: extraLabels = {}, defaults: defs, } = props;
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        ...extraLabels,
+    };
+    const namespace = new Namespace(mergeDefaults({
+        metadata: {
+            name,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "namespace" },
+        },
+    }, defs?.namespace));
+    const result = { namespace };
+    // ResourceQuota — only if at least one quota prop is set
+    const hasQuota = cpuQuota || memoryQuota || maxPods !== undefined;
+    if (hasQuota) {
+        const hard = {};
+        if (cpuQuota)
+            hard["limits.cpu"] = cpuQuota;
+        if (memoryQuota)
+            hard["limits.memory"] = memoryQuota;
+        if (maxPods !== undefined)
+            hard.pods = String(maxPods);
+        result.resourceQuota = new ResourceQuota(mergeDefaults({
+            metadata: {
+                name: `${name}-quota`,
+                namespace: name,
+                labels: { ...commonLabels, "app.kubernetes.io/component": "quota" },
+            },
+            spec: { hard },
+        }, defs?.resourceQuota));
+    }
+    // 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 = {};
+        const defaultRequests = {};
+        if (defaultCpuLimit)
+            defaultLimits.cpu = defaultCpuLimit;
+        if (defaultMemoryLimit)
+            defaultLimits.memory = defaultMemoryLimit;
+        if (defaultCpuRequest)
+            defaultRequests.cpu = defaultCpuRequest;
+        if (defaultMemoryRequest)
+            defaultRequests.memory = defaultMemoryRequest;
+        const limit = { type: "Container" };
+        if (Object.keys(defaultLimits).length > 0)
+            limit.default = defaultLimits;
+        if (Object.keys(defaultRequests).length > 0)
+            limit.defaultRequest = defaultRequests;
+        result.limitRange = new LimitRange(mergeDefaults({
+            metadata: {
+                name: `${name}-limits`,
+                namespace: name,
+                labels: { ...commonLabels, "app.kubernetes.io/component": "limits" },
+            },
+            spec: {
+                limits: [limit],
+            },
+        }, defs?.limitRange));
+    }
+    // NetworkPolicy — default-deny ingress and/or egress
+    const hasNetworkPolicy = defaultDenyIngress || defaultDenyEgress;
+    if (hasNetworkPolicy) {
+        const policyTypes = [];
+        if (defaultDenyIngress)
+            policyTypes.push("Ingress");
+        if (defaultDenyEgress)
+            policyTypes.push("Egress");
+        result.networkPolicy = new NetworkPolicy(mergeDefaults({
+            metadata: {
+                name: `${name}-default-deny`,
+                namespace: name,
+                labels: { ...commonLabels, "app.kubernetes.io/component": "network-policy" },
+            },
+            spec: {
+                podSelector: {},
+                policyTypes,
+            },
+        }, defs?.networkPolicy));
+    }
+    return result;
+}, "NamespaceEnv");

package/dist/composites/network-isolated-app.js

@@ -0,0 +1,124 @@
+/**
+ * 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 { Composite, mergeDefaults } from "@intentius/chant";
+import { Deployment, Service, NetworkPolicy } from "../generated/index.js";
+/**
+ * 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 const NetworkIsolatedApp = Composite((props) => {
+    const { name, image, port = 80, replicas = 2, allowIngressFrom, allowEgressTo, labels: extraLabels = {}, cpuLimit = "500m", memoryLimit = "256Mi", cpuRequest = "100m", memoryRequest = "128Mi", namespace, env, securityContext, defaults: defs, } = props;
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        ...extraLabels,
+    };
+    const deployment = new Deployment(mergeDefaults({
+        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 }),
+                        },
+                    ],
+                },
+            },
+        },
+    }, defs?.deployment));
+    const service = new Service(mergeDefaults({
+        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",
+        },
+    }, defs?.service));
+    // Build network policy
+    const policyTypes = [];
+    const policySpec = {
+        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 networkPolicy = new NetworkPolicy(mergeDefaults({
+        metadata: {
+            name: `${name}-policy`,
+            ...(namespace && { namespace }),
+            labels: { ...commonLabels, "app.kubernetes.io/component": "network-policy" },
+        },
+        spec: policySpec,
+    }, defs?.networkPolicy));
+    return { deployment, service, networkPolicy };
+}, "NetworkIsolatedApp");

package/dist/composites/node-agent.js

@@ -0,0 +1,149 @@
+/**
+ * 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.
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { DaemonSet, ServiceAccount, ClusterRole, ClusterRoleBinding, ConfigMap } from "../generated/index.js";
+/**
+ * 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 const NodeAgent = Composite((props) => {
+    const { name, image, port, hostPaths = [], config, rbacRules, tolerateAllTaints = true, namespace, cpuRequest = "50m", memoryRequest = "64Mi", cpuLimit = "200m", memoryLimit = "128Mi", labels: extraLabels = {}, env, securityContext, defaults: defs, } = props;
+    const saName = `${name}-sa`;
+    const clusterRoleName = `${name}-role`;
+    const bindingName = `${name}-binding`;
+    const configMapName = `${name}-config`;
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        ...extraLabels,
+    };
+    // Build volumes and volumeMounts from hostPaths
+    const volumes = [];
+    const volumeMounts = [];
+    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 = {
+        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 }),
+        ...(securityContext && { securityContext }),
+    };
+    const podSpec = {
+        serviceAccountName: saName,
+        containers: [container],
+        ...(volumes.length > 0 && { volumes }),
+        ...(tolerateAllTaints && {
+            tolerations: [{ operator: "Exists" }],
+        }),
+    };
+    const daemonSet = new DaemonSet(mergeDefaults({
+        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,
+            },
+        },
+    }, defs?.daemonSet));
+    const serviceAccount = new ServiceAccount(mergeDefaults({
+        metadata: {
+            name: saName,
+            ...(namespace && { namespace }),
+            labels: { ...commonLabels, "app.kubernetes.io/component": "agent" },
+        },
+    }, defs?.serviceAccount));
+    // ClusterRole — cluster-scoped, no namespace
+    const clusterRole = new ClusterRole(mergeDefaults({
+        metadata: {
+            name: clusterRoleName,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+        },
+        rules: rbacRules,
+    }, defs?.clusterRole));
+    // ClusterRoleBinding — cluster-scoped, no namespace
+    const clusterRoleBinding = new ClusterRoleBinding(mergeDefaults({
+        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 }),
+            },
+        ],
+    }, defs?.clusterRoleBinding));
+    const result = {
+        daemonSet,
+        serviceAccount,
+        clusterRole,
+        clusterRoleBinding,
+    };
+    if (config) {
+        result.configMap = new ConfigMap(mergeDefaults({
+            metadata: {
+                name: configMapName,
+                ...(namespace && { namespace }),
+                labels: { ...commonLabels, "app.kubernetes.io/component": "config" },
+            },
+            data: config,
+        }, defs?.configMap));
+    }
+    return result;
+}, "NodeAgent");