@intentius/chant-lexicon-k8s 0.0.13 → 0.0.15

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;
+}

package/src/composites/security-context.ts

@@ -0,0 +1,10 @@
+/** Container-level security context — covers PSS restricted requirements. */
+export interface ContainerSecurityContext {
+  runAsNonRoot?: boolean;
+  readOnlyRootFilesystem?: boolean;
+  runAsUser?: number;
+  runAsGroup?: number;
+  allowPrivilegeEscalation?: boolean;
+  capabilities?: { add?: string[]; drop?: string[] };
+  seccompProfile?: { type: string; localhostProfile?: string };
+}

package/src/composites/sidecar-app.ts

@@ -0,0 +1,207 @@
+/**
+ * SidecarApp composite — multi-container Deployment + Service.
+ *
+ * Sidecar and init container patterns (envoy proxy, log forwarder,
+ * DB migration init). Supports shared volumes between containers.
+ */
+
+import type { ContainerSecurityContext } from "./security-context";
+
+export interface SidecarContainer {
+  /** Sidecar container name. */
+  name: string;
+  /** Container image. */
+  image: string;
+  /** Container ports. */
+  ports?: Array<{ containerPort: number; name?: string }>;
+  /** Resource limits and requests. */
+  resources?: {
+    limits?: { cpu?: string; memory?: string };
+    requests?: { cpu?: string; memory?: string };
+  };
+  /** Environment variables. */
+  env?: Array<{ name: string; value: string }>;
+}
+
+export interface InitContainer {
+  /** Init container name. */
+  name: string;
+  /** Container image. */
+  image: string;
+  /** Command to run. */
+  command?: string[];
+  /** Arguments to the command. */
+  args?: string[];
+}
+
+export interface SharedVolume {
+  /** Volume name. */
+  name: string;
+  /** Use emptyDir (default). */
+  emptyDir?: Record<string, unknown>;
+  /** Use a ConfigMap by name. */
+  configMapName?: string;
+}
+
+export interface SidecarAppProps {
+  /** Application name — used in metadata and labels. */
+  name: string;
+  /** Primary container image. */
+  image: string;
+  /** Primary container port (default: 80). */
+  port?: number;
+  /** Number of replicas (default: 2). */
+  replicas?: number;
+  /** Sidecar containers. */
+  sidecars: SidecarContainer[];
+  /** Init containers (run before main containers). */
+  initContainers?: InitContainer[];
+  /** Shared volumes between containers. */
+  sharedVolumes?: SharedVolume[];
+  /** Additional labels to apply to all resources. */
+  labels?: Record<string, string>;
+  /** CPU limit for the primary container (default: "500m"). */
+  cpuLimit?: string;
+  /** Memory limit for the primary container (default: "256Mi"). */
+  memoryLimit?: string;
+  /** CPU request for the primary container (default: "100m"). */
+  cpuRequest?: string;
+  /** Memory request for the primary container (default: "128Mi"). */
+  memoryRequest?: string;
+  /** Namespace for all resources. */
+  namespace?: string;
+  /** Environment variables for the primary container. */
+  env?: Array<{ name: string; value: string }>;
+  /** Container security context for the primary container (supports PSS restricted fields). */
+  securityContext?: ContainerSecurityContext;
+}
+
+export interface SidecarAppResult {
+  deployment: Record<string, unknown>;
+  service: Record<string, unknown>;
+}
+
+/**
+ * Create a SidecarApp composite — returns prop objects for
+ * a multi-container Deployment and Service.
+ *
+ * @example
+ * ```ts
+ * import { SidecarApp } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { deployment, service } = SidecarApp({
+ *   name: "api",
+ *   image: "api:1.0",
+ *   port: 8080,
+ *   sidecars: [
+ *     { name: "envoy", image: "envoyproxy/envoy:v1.28", ports: [{ containerPort: 9901 }] },
+ *   ],
+ *   initContainers: [
+ *     { name: "migrate", image: "api:1.0", command: ["python", "manage.py", "migrate"] },
+ *   ],
+ *   sharedVolumes: [{ name: "tmp", emptyDir: {} }],
+ * });
+ * ```
+ */
+export function SidecarApp(props: SidecarAppProps): SidecarAppResult {
+  const {
+    name,
+    image,
+    port = 80,
+    replicas = 2,
+    sidecars,
+    initContainers,
+    sharedVolumes,
+    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,
+  };
+
+  // Primary container
+  const primaryContainer: Record<string, unknown> = {
+    name,
+    image,
+    ports: [{ containerPort: port, name: "http" }],
+    resources: {
+      limits: { cpu: cpuLimit, memory: memoryLimit },
+      requests: { cpu: cpuRequest, memory: memoryRequest },
+    },
+    ...(env && { env }),
+    ...(securityContext && { securityContext }),
+  };
+
+  // Sidecar containers
+  const sidecarContainers = sidecars.map((sc) => ({
+    name: sc.name,
+    image: sc.image,
+    ...(sc.ports && { ports: sc.ports }),
+    ...(sc.resources && { resources: sc.resources }),
+    ...(sc.env && { env: sc.env }),
+  }));
+
+  // Build volumes from sharedVolumes
+  const volumes: Array<Record<string, unknown>> | undefined = sharedVolumes?.map((sv) => {
+    if (sv.configMapName) {
+      return { name: sv.name, configMap: { name: sv.configMapName } };
+    }
+    return { name: sv.name, emptyDir: sv.emptyDir ?? {} };
+  });
+
+  const podSpec: Record<string, unknown> = {
+    containers: [primaryContainer, ...sidecarContainers],
+    ...(initContainers && {
+      initContainers: initContainers.map((ic) => ({
+        name: ic.name,
+        image: ic.image,
+        ...(ic.command && { command: ic.command }),
+        ...(ic.args && { args: ic.args }),
+      })),
+    }),
+    ...(volumes && volumes.length > 0 && { volumes }),
+  };
+
+  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: podSpec,
+      },
+    },
+  };
+
+  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",
+    },
+  };
+
+  return {
+    deployment: deploymentProps,
+    service: serviceProps,
+  };
+}

package/src/composites/stateful-app.ts

@@ -5,6 +5,8 @@
  * like databases, caches, and message queues.
  */
 
+import type { ContainerSecurityContext } from "./security-context";
+
 export interface StatefulAppProps {
   /** Application name — used in metadata and labels. */
   name: string;
@@ -20,6 +22,21 @@ export interface StatefulAppProps {
   storageClassName?: string;
   /** Volume mount path inside the container (default: "/data"). */
   mountPath?: string;
+  /** PodDisruptionBudget minAvailable — if set, creates a PDB. */
+  minAvailable?: number | string;
+  /** Init containers (e.g., schema migrations, permission setup). */
+  initContainers?: Array<{
+    name: string;
+    image: string;
+    command?: string[];
+    args?: string[];
+  }>;
+  /** Container security context (supports PSS restricted fields). */
+  securityContext?: ContainerSecurityContext;
+  /** Termination grace period in seconds. */
+  terminationGracePeriodSeconds?: number;
+  /** Priority class name for pod scheduling. */
+  priorityClassName?: string;
   /** Additional labels to apply to all resources. */
   labels?: Record<string, string>;
   /** CPU limit (e.g., "1"). */
@@ -35,6 +52,7 @@ export interface StatefulAppProps {
 export interface StatefulAppResult {
   statefulSet: Record<string, unknown>;
   service: Record<string, unknown>;
+  pdb?: Record<string, unknown>;
 }
 
 /**
@@ -63,6 +81,11 @@ export function StatefulApp(props: StatefulAppProps): StatefulAppResult {
     storageSize = "10Gi",
     storageClassName,
     mountPath = "/data",
+    minAvailable,
+    initContainers,
+    securityContext,
+    terminationGracePeriodSeconds,
+    priorityClassName,
     labels: extraLabels = {},
     cpuLimit = "1",
     memoryLimit = "1Gi",
@@ -76,6 +99,32 @@ export function StatefulApp(props: StatefulAppProps): StatefulAppResult {
     ...extraLabels,
   };
 
+  const container: Record<string, unknown> = {
+    name,
+    image,
+    ports: [{ containerPort: port, name: "app" }],
+    resources: {
+      limits: { cpu: cpuLimit, memory: memoryLimit },
+    },
+    volumeMounts: [{ name: "data", mountPath }],
+    ...(env && { env }),
+    ...(securityContext && { securityContext }),
+  };
+
+  const podSpec: Record<string, unknown> = {
+    containers: [container],
+    ...(initContainers && {
+      initContainers: initContainers.map((ic) => ({
+        name: ic.name,
+        image: ic.image,
+        ...(ic.command && { command: ic.command }),
+        ...(ic.args && { args: ic.args }),
+      })),
+    }),
+    ...(terminationGracePeriodSeconds !== undefined && { terminationGracePeriodSeconds }),
+    ...(priorityClassName && { priorityClassName }),
+  };
+
   const statefulSetProps: Record<string, unknown> = {
     metadata: {
       name,
@@ -88,20 +137,7 @@ export function StatefulApp(props: StatefulAppProps): StatefulAppResult {
       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 }),
-            },
-          ],
-        },
+        spec: podSpec,
       },
       volumeClaimTemplates: [
         {
@@ -130,5 +166,21 @@ export function StatefulApp(props: StatefulAppProps): StatefulAppResult {
     },
   };
 
-  return { statefulSet: statefulSetProps, service: serviceProps };
+  const result: StatefulAppResult = { statefulSet: statefulSetProps, service: serviceProps };
+
+  if (minAvailable !== undefined) {
+    result.pdb = {
+      metadata: {
+        name,
+        ...(namespace && { namespace }),
+        labels: { ...commonLabels, "app.kubernetes.io/component": "disruption-budget" },
+      },
+      spec: {
+        minAvailable,
+        selector: { matchLabels: { "app.kubernetes.io/name": name } },
+      },
+    };
+  }
+
+  return result;
 }

package/src/composites/web-app.ts

@@ -5,6 +5,8 @@
  * with common defaults (health probes, resource limits, labels).
  */
 
+import type { ContainerSecurityContext } from "./security-context";
+
 export interface WebAppProps {
   /** Application name — used in metadata and labels. */
   name: string;
@@ -18,6 +20,28 @@ export interface WebAppProps {
   ingressHost?: string;
   /** Ingress TLS secret name — if set, enables TLS on the Ingress. */
   ingressTlsSecret?: string;
+  /** Multi-path ingress rules — overrides the default single "/" path. */
+  ingressPaths?: Array<{
+    path: string;
+    pathType?: string;
+    serviceName?: string;
+    servicePort?: number;
+  }>;
+  /** PodDisruptionBudget minAvailable — if set, creates a PDB. */
+  minAvailable?: number | string;
+  /** Init containers (e.g., migrations, cert setup). */
+  initContainers?: Array<{
+    name: string;
+    image: string;
+    command?: string[];
+    args?: string[];
+  }>;
+  /** Container security context (supports PSS restricted fields). */
+  securityContext?: ContainerSecurityContext;
+  /** Termination grace period in seconds. */
+  terminationGracePeriodSeconds?: number;
+  /** Priority class name for pod scheduling. */
+  priorityClassName?: string;
   /** Additional labels to apply to all resources. */
   labels?: Record<string, string>;
   /** CPU limit (e.g., "500m"). */
@@ -38,6 +62,7 @@ export interface WebAppResult {
   deployment: Record<string, unknown>;
   service: Record<string, unknown>;
   ingress?: Record<string, unknown>;
+  pdb?: Record<string, unknown>;
 }
 
 /**
@@ -72,6 +97,11 @@ export function WebApp(props: WebAppProps): WebAppResult {
     memoryRequest = "128Mi",
     namespace,
     env,
+    initContainers,
+    securityContext,
+    terminationGracePeriodSeconds,
+    priorityClassName,
+    minAvailable,
   } = props;
 
   const commonLabels: Record<string, string> = {
@@ -80,6 +110,42 @@ export function WebApp(props: WebAppProps): WebAppResult {
     ...extraLabels,
   };
 
+  const container: Record<string, unknown> = {
+    name,
+    image,
+    ports: [{ containerPort: port, name: "http" }],
+    resources: {
+      limits: { cpu: cpuLimit, memory: memoryLimit },
+      requests: { cpu: cpuRequest, memory: memoryRequest },
+    },
+    livenessProbe: {
+      httpGet: { path: "/", port },
+      initialDelaySeconds: 10,
+      periodSeconds: 10,
+    },
+    readinessProbe: {
+      httpGet: { path: "/", port },
+      initialDelaySeconds: 5,
+      periodSeconds: 5,
+    },
+    ...(env && { env }),
+    ...(securityContext && { securityContext }),
+  };
+
+  const podSpec: Record<string, unknown> = {
+    containers: [container],
+    ...(initContainers && {
+      initContainers: initContainers.map((ic) => ({
+        name: ic.name,
+        image: ic.image,
+        ...(ic.command && { command: ic.command }),
+        ...(ic.args && { args: ic.args }),
+      })),
+    }),
+    ...(terminationGracePeriodSeconds !== undefined && { terminationGracePeriodSeconds }),
+    ...(priorityClassName && { priorityClassName }),
+  };
+
   // We return plain objects that users pass to constructors.
   // The actual resource instantiation happens in user code with the generated classes.
   const deploymentProps: Record<string, unknown> = {
@@ -93,30 +159,7 @@ export function WebApp(props: WebAppProps): WebAppResult {
       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 },
-              },
-              livenessProbe: {
-                httpGet: { path: "/", port },
-                initialDelaySeconds: 10,
-                periodSeconds: 10,
-              },
-              readinessProbe: {
-                httpGet: { path: "/", port },
-                initialDelaySeconds: 5,
-                periodSeconds: 5,
-              },
-              ...(env && { env }),
-            },
-          ],
-        },
+        spec: podSpec,
       },
     },
   };
@@ -140,6 +183,28 @@ export function WebApp(props: WebAppProps): WebAppResult {
   };
 
   if (props.ingressHost) {
+    // Build paths — use ingressPaths if provided, otherwise default single "/"
+    const paths = props.ingressPaths
+      ? props.ingressPaths.map((p) => ({
+          path: p.path,
+          pathType: p.pathType ?? "Prefix",
+          backend: {
+            service: {
+              name: p.serviceName ?? name,
+              port: { number: p.servicePort ?? 80 },
+            },
+          },
+        }))
+      : [
+          {
+            path: "/",
+            pathType: "Prefix",
+            backend: {
+              service: { name, port: { number: 80 } },
+            },
+          },
+        ];
+
     const ingressProps: Record<string, unknown> = {
       metadata: {
         name,
@@ -150,17 +215,7 @@ export function WebApp(props: WebAppProps): WebAppResult {
         rules: [
           {
             host: props.ingressHost,
-            http: {
-              paths: [
-                {
-                  path: "/",
-                  pathType: "Prefix",
-                  backend: {
-                    service: { name, port: { number: 80 } },
-                  },
-                },
-              ],
-            },
+            http: { paths },
           },
         ],
         ...(props.ingressTlsSecret && {
@@ -176,5 +231,19 @@ export function WebApp(props: WebAppProps): WebAppResult {
     result.ingress = ingressProps;
   }
 
+  if (minAvailable !== undefined) {
+    result.pdb = {
+      metadata: {
+        name,
+        ...(namespace && { namespace }),
+        labels: { ...commonLabels, "app.kubernetes.io/component": "disruption-budget" },
+      },
+      spec: {
+        minAvailable,
+        selector: { matchLabels: { "app.kubernetes.io/name": name } },
+      },
+    };
+  }
+
   return result;
 }