@intentius/chant-lexicon-k8s 0.0.13 → 0.0.15

package/src/composites/azure-disk-storage-class.ts

@@ -0,0 +1,82 @@
+/**
+ * AzureDiskStorageClass composite — StorageClass for Azure Disk CSI driver.
+ *
+ * @aks Creates a StorageClass with the `disk.csi.azure.com` provisioner.
+ */
+
+export interface AzureDiskStorageClassProps {
+  /** StorageClass name. */
+  name: string;
+  /** Azure Disk SKU name (default: "Premium_LRS"). */
+  skuName?: string;
+  /** OS disk caching mode (default: "ReadOnly"). */
+  cachingMode?: string;
+  /** Network access policy (default: "AllowAll"). */
+  networkAccessPolicy?: string;
+  /** Reclaim policy (default: "Delete"). */
+  reclaimPolicy?: string;
+  /** Volume binding mode (default: "WaitForFirstConsumer"). */
+  volumeBindingMode?: string;
+  /** Allow volume expansion (default: true). */
+  allowVolumeExpansion?: boolean;
+  /** Additional labels. */
+  labels?: Record<string, string>;
+}
+
+export interface AzureDiskStorageClassResult {
+  storageClass: Record<string, unknown>;
+}
+
+/**
+ * Create an AzureDiskStorageClass composite — returns prop objects for
+ * a StorageClass with the Azure Disk CSI provisioner.
+ *
+ * @aks
+ * @example
+ * ```ts
+ * import { AzureDiskStorageClass } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { storageClass } = AzureDiskStorageClass({
+ *   name: "premium-disk",
+ *   skuName: "Premium_LRS",
+ * });
+ * ```
+ */
+export function AzureDiskStorageClass(props: AzureDiskStorageClassProps): AzureDiskStorageClassResult {
+  const {
+    name,
+    skuName = "Premium_LRS",
+    cachingMode = "ReadOnly",
+    networkAccessPolicy = "AllowAll",
+    reclaimPolicy = "Delete",
+    volumeBindingMode = "WaitForFirstConsumer",
+    allowVolumeExpansion = true,
+    labels: extraLabels = {},
+  } = props;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  const parameters: Record<string, string> = {
+    skuName,
+    cachingMode,
+    networkAccessPolicy,
+  };
+
+  const storageClassProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "storage" },
+    },
+    provisioner: "disk.csi.azure.com",
+    parameters,
+    reclaimPolicy,
+    volumeBindingMode,
+    allowVolumeExpansion,
+  };
+
+  return { storageClass: storageClassProps };
+}

package/src/composites/azure-file-storage-class.ts

@@ -0,0 +1,77 @@
+/**
+ * AzureFileStorageClass composite — StorageClass for Azure Files CSI driver.
+ *
+ * @aks Creates a StorageClass with the `file.csi.azure.com` provisioner.
+ * Azure Files provides ReadWriteMany access mode (shared across pods/nodes).
+ */
+
+export interface AzureFileStorageClassProps {
+  /** StorageClass name. */
+  name: string;
+  /** Azure Files SKU name (default: "Premium_LRS"). */
+  skuName?: string;
+  /** Protocol for Azure Files (default: "smb"). */
+  protocol?: string;
+  /** Specific Azure file share name (optional; dynamically provisioned if omitted). */
+  shareName?: string;
+  /** Reclaim policy (default: "Delete"). */
+  reclaimPolicy?: string;
+  /** Additional labels. */
+  labels?: Record<string, string>;
+}
+
+export interface AzureFileStorageClassResult {
+  storageClass: Record<string, unknown>;
+}
+
+/**
+ * Create an AzureFileStorageClass composite — returns prop objects for
+ * a StorageClass with the Azure Files CSI provisioner.
+ *
+ * @aks
+ * @example
+ * ```ts
+ * import { AzureFileStorageClass } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { storageClass } = AzureFileStorageClass({
+ *   name: "azure-files-shared",
+ *   skuName: "Premium_LRS",
+ *   protocol: "nfs",
+ * });
+ * ```
+ */
+export function AzureFileStorageClass(props: AzureFileStorageClassProps): AzureFileStorageClassResult {
+  const {
+    name,
+    skuName = "Premium_LRS",
+    protocol = "smb",
+    shareName,
+    reclaimPolicy = "Delete",
+    labels: extraLabels = {},
+  } = props;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  const parameters: Record<string, string> = {
+    skuName,
+    protocol,
+  };
+
+  if (shareName) parameters.shareName = shareName;
+
+  const storageClassProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "storage" },
+    },
+    provisioner: "file.csi.azure.com",
+    parameters,
+    reclaimPolicy,
+  };
+
+  return { storageClass: storageClassProps };
+}

package/src/composites/azure-monitor-collector.ts

@@ -0,0 +1,232 @@
+/**
+ * AzureMonitorCollector composite — DaemonSet + RBAC + ConfigMap for Azure Monitor / OTel collector.
+ *
+ * @aks Azure Monitor agent with OpenTelemetry collector config for
+ * Log Analytics workspace integration on AKS clusters.
+ */
+
+export interface AzureMonitorCollectorProps {
+  /** Azure Log Analytics workspace ID. */
+  workspaceId: string;
+  /** AKS cluster name. */
+  clusterName: string;
+  /** Agent name (default: "azure-monitor-collector"). */
+  name?: string;
+  /** Collector image (default: "mcr.microsoft.com/azuremonitor/containerinsights/ciprod:latest"). */
+  image?: string;
+  /** Namespace (default: "azure-monitor"). */
+  namespace?: string;
+  /** Additional labels. */
+  labels?: Record<string, string>;
+  /** CPU request (default: "100m"). */
+  cpuRequest?: string;
+  /** Memory request (default: "256Mi"). */
+  memoryRequest?: string;
+  /** CPU limit (default: "500m"). */
+  cpuLimit?: string;
+  /** Memory limit (default: "512Mi"). */
+  memoryLimit?: string;
+  /** Azure AD client ID for Workload Identity (adds azure.workload.identity annotations to ServiceAccount). */
+  clientId?: string;
+}
+
+export interface AzureMonitorCollectorResult {
+  daemonSet: Record<string, unknown>;
+  serviceAccount: Record<string, unknown>;
+  clusterRole: Record<string, unknown>;
+  clusterRoleBinding: Record<string, unknown>;
+  configMap: Record<string, unknown>;
+}
+
+/**
+ * Create an AzureMonitorCollector composite — returns prop objects for
+ * a DaemonSet, ServiceAccount, ClusterRole, ClusterRoleBinding, and ConfigMap.
+ *
+ * @aks
+ * @example
+ * ```ts
+ * import { AzureMonitorCollector } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { daemonSet, serviceAccount, clusterRole, clusterRoleBinding, configMap } = AzureMonitorCollector({
+ *   workspaceId: "00000000-0000-0000-0000-000000000000",
+ *   clusterName: "my-aks-cluster",
+ * });
+ * ```
+ */
+export function AzureMonitorCollector(props: AzureMonitorCollectorProps): AzureMonitorCollectorResult {
+  const {
+    workspaceId,
+    clusterName,
+    name = "azure-monitor-collector",
+    image = "mcr.microsoft.com/azuremonitor/containerinsights/ciprod:latest",
+    namespace = "azure-monitor",
+    labels: extraLabels = {},
+    cpuRequest = "100m",
+    memoryRequest = "256Mi",
+    cpuLimit = "500m",
+    memoryLimit = "512Mi",
+    clientId,
+  } = 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 OTel collector config YAML for Azure Monitor
+  const collectorConfig = `receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+      http:
+        endpoint: 0.0.0.0:4318
+
+processors:
+  batch:
+    timeout: 30s
+    send_batch_size: 8192
+
+exporters:
+  azuremonitor:
+    connection_string: InstrumentationKey=\${APPINSIGHTS_INSTRUMENTATIONKEY}
+    endpoint: https://dc.services.visualstudio.com/v2/track
+  azuremonitor/logs:
+    workspace_id: ${workspaceId}
+    cluster_name: ${clusterName}
+
+service:
+  pipelines:
+    metrics:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [azuremonitor]
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [azuremonitor]
+    logs:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [azuremonitor/logs]
+`;
+
+  const container: Record<string, unknown> = {
+    name,
+    image,
+    ports: [
+      { containerPort: 4317, name: "otlp-grpc" },
+      { containerPort: 4318, name: "otlp-http" },
+    ],
+    env: [
+      { name: "AKS_CLUSTER_NAME", value: clusterName },
+      { name: "WORKSPACE_ID", value: workspaceId },
+    ],
+    resources: {
+      requests: { cpu: cpuRequest, memory: memoryRequest },
+      limits: { cpu: cpuLimit, memory: memoryLimit },
+    },
+    volumeMounts: [
+      { name: "config", mountPath: "/etc/otel", readOnly: true },
+    ],
+  };
+
+  const daemonSetProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      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: {
+          serviceAccountName: saName,
+          containers: [container],
+          volumes: [
+            { name: "config", configMap: { name: configMapName } },
+          ],
+          tolerations: [{ operator: "Exists" }],
+        },
+      },
+    },
+  };
+
+  const saLabels: Record<string, string> = {
+    ...commonLabels,
+    "app.kubernetes.io/component": "agent",
+  };
+
+  if (clientId) {
+    saLabels["azure.workload.identity/use"] = "true";
+  }
+
+  const serviceAccountProps: Record<string, unknown> = {
+    metadata: {
+      name: saName,
+      namespace,
+      labels: saLabels,
+      ...(clientId ? { annotations: { "azure.workload.identity/client-id": clientId } } : {}),
+    },
+  };
+
+  const clusterRoleProps: Record<string, unknown> = {
+    metadata: {
+      name: clusterRoleName,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+    },
+    rules: [
+      { apiGroups: [""], resources: ["pods", "nodes", "endpoints"], verbs: ["get", "list", "watch"] },
+      { apiGroups: ["apps"], resources: ["replicasets"], verbs: ["get", "list", "watch"] },
+      { apiGroups: ["batch"], resources: ["jobs"], verbs: ["get", "list", "watch"] },
+      { apiGroups: [""], resources: ["nodes/proxy"], verbs: ["get"] },
+      { apiGroups: [""], resources: ["nodes/stats", "configmaps", "events"], verbs: ["create", "get"] },
+      { apiGroups: [""], resources: ["configmaps"], verbs: ["get", "update", "create"], resourceNames: ["otel-container-insight-clusterleader"] },
+    ],
+  };
+
+  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,
+      },
+    ],
+  };
+
+  const configMapProps: Record<string, unknown> = {
+    metadata: {
+      name: configMapName,
+      namespace,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "config" },
+    },
+    data: {
+      "config.yaml": collectorConfig,
+    },
+  };
+
+  return {
+    daemonSet: daemonSetProps,
+    serviceAccount: serviceAccountProps,
+    clusterRole: clusterRoleProps,
+    clusterRoleBinding: clusterRoleBindingProps,
+    configMap: configMapProps,
+  };
+}

package/src/composites/batch-job.ts

@@ -0,0 +1,221 @@
+/**
+ * BatchJob composite — Job + optional RBAC (ServiceAccount + Role + RoleBinding).
+ *
+ * A higher-level construct for one-shot batch jobs (data migrations,
+ * seed tasks, backups). For scheduled workloads, use CronWorkload instead.
+ */
+
+import type { ContainerSecurityContext } from "./security-context";
+
+/** Parse a K8s memory string (e.g. "256Mi", "1Gi") to bytes for comparison. */
+function parseMemoryBytes(mem: string): number {
+  const match = mem.match(/^(\d+(?:\.\d+)?)\s*(Ki|Mi|Gi|Ti|k|M|G|T|[eE]\d+)?$/);
+  if (!match) return 0;
+  const value = parseFloat(match[1]);
+  const unit = match[2] ?? "";
+  const multipliers: Record<string, number> = {
+    "": 1, Ki: 1024, Mi: 1024 ** 2, Gi: 1024 ** 3, Ti: 1024 ** 4,
+    k: 1e3, M: 1e6, G: 1e9, T: 1e12,
+  };
+  if (unit.startsWith("e") || unit.startsWith("E")) return value * 10 ** parseInt(unit.slice(1));
+  return value * (multipliers[unit] ?? 1);
+}
+
+/** Parse a K8s CPU string (e.g. "500m", "1") to millicores for comparison. */
+function parseCpuMillis(cpu: string): number {
+  if (cpu.endsWith("m")) return parseFloat(cpu.slice(0, -1));
+  return parseFloat(cpu) * 1000;
+}
+
+export interface BatchJobProps {
+  /** Job name — used in metadata and labels. */
+  name: string;
+  /** Container image. */
+  image: string;
+  /** Command to run in the container. */
+  command?: string[];
+  /** Arguments to the command. */
+  args?: string[];
+  /** Number of retries before marking the job as failed (default: 6). */
+  backoffLimit?: number;
+  /** Seconds after completion before the job is eligible for GC. */
+  ttlSecondsAfterFinished?: number;
+  /** Number of completions required (default: 1). */
+  completions?: number;
+  /** Number of pods running in parallel (default: 1). */
+  parallelism?: number;
+  /** Restart policy (default: "OnFailure"). */
+  restartPolicy?: string;
+  /** RBAC rules for the service account. Omit for defaults; pass [] to skip RBAC entirely. */
+  rbacRules?: Array<{
+    apiGroups: string[];
+    resources: string[];
+    verbs: string[];
+  }>;
+  /** Additional labels to apply to all resources. */
+  labels?: Record<string, string>;
+  /** Namespace for all resources. */
+  namespace?: string;
+  /** CPU request (default: "100m"). */
+  cpuRequest?: string;
+  /** Memory request (default: "128Mi"). */
+  memoryRequest?: string;
+  /** CPU limit (default: "500m"). */
+  cpuLimit?: string;
+  /** Memory limit (default: "256Mi"). */
+  memoryLimit?: string;
+  /** Environment variables for the container. */
+  env?: Array<{ name: string; value: string }>;
+  /** Container security context (supports PSS restricted fields). */
+  securityContext?: ContainerSecurityContext;
+}
+
+export interface BatchJobResult {
+  job: Record<string, unknown>;
+  serviceAccount?: Record<string, unknown>;
+  role?: Record<string, unknown>;
+  roleBinding?: Record<string, unknown>;
+}
+
+/**
+ * Create a BatchJob composite — returns prop objects for
+ * a Job, and optional ServiceAccount, Role, and RoleBinding.
+ *
+ * @example
+ * ```ts
+ * import { BatchJob } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { job, serviceAccount, role, roleBinding } = BatchJob({
+ *   name: "db-migrate",
+ *   image: "migrate:1.0",
+ *   command: ["python", "manage.py", "migrate"],
+ *   backoffLimit: 3,
+ *   ttlSecondsAfterFinished: 3600,
+ * });
+ * ```
+ */
+export function BatchJob(props: BatchJobProps): BatchJobResult {
+  const {
+    name,
+    image,
+    command,
+    args,
+    backoffLimit = 6,
+    ttlSecondsAfterFinished,
+    completions = 1,
+    parallelism = 1,
+    restartPolicy = "OnFailure",
+    rbacRules,
+    labels: extraLabels = {},
+    namespace,
+    cpuRequest = "100m",
+    memoryRequest: rawMemoryRequest = "128Mi",
+    cpuLimit: rawCpuLimit = "500m",
+    memoryLimit: rawMemoryLimit = "256Mi",
+    env,
+    securityContext,
+  } = props;
+
+  // Ensure limits >= requests (K8s rejects pods where request > limit).
+  const memoryRequest = rawMemoryRequest;
+  const memoryLimit = parseMemoryBytes(rawMemoryRequest) > parseMemoryBytes(rawMemoryLimit)
+    ? rawMemoryRequest : rawMemoryLimit;
+  const cpuLimit = parseCpuMillis(cpuRequest) > parseCpuMillis(rawCpuLimit)
+    ? cpuRequest : rawCpuLimit;
+
+  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,
+  };
+
+  // undefined → default RBAC rules; explicit [] → no RBAC resources
+  const createRbac = rbacRules === undefined || rbacRules.length > 0;
+  const effectiveRbacRules = rbacRules === undefined
+    ? [{ apiGroups: [""], resources: ["pods"], verbs: ["get", "list"] }]
+    : rbacRules;
+
+  const container: Record<string, unknown> = {
+    name,
+    image,
+    ...(command && { command }),
+    ...(args && { args }),
+    resources: {
+      limits: { cpu: cpuLimit, memory: memoryLimit },
+      requests: { cpu: cpuRequest, memory: memoryRequest },
+    },
+    ...(env && { env }),
+    ...(securityContext && { securityContext }),
+  };
+
+  const jobProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "batch" },
+    },
+    spec: {
+      backoffLimit,
+      completions,
+      parallelism,
+      ...(ttlSecondsAfterFinished !== undefined && { ttlSecondsAfterFinished }),
+      template: {
+        metadata: { labels: { "app.kubernetes.io/name": name, ...extraLabels } },
+        spec: {
+          ...(createRbac && { serviceAccountName: saName }),
+          restartPolicy,
+          containers: [container],
+        },
+      },
+    },
+  };
+
+  const result: BatchJobResult = {
+    job: jobProps,
+  };
+
+  if (createRbac) {
+    result.serviceAccount = {
+      metadata: {
+        name: saName,
+        ...(namespace && { namespace }),
+        labels: { ...commonLabels, "app.kubernetes.io/component": "batch" },
+      },
+    };
+
+    result.role = {
+      metadata: {
+        name: roleName,
+        ...(namespace && { namespace }),
+        labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+      },
+      rules: effectiveRbacRules,
+    };
+
+    result.roleBinding = {
+      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 result;
+}