timonel 2.2.0 → 2.3.0

package/dist/lib/Rutter.js

@@ -1,11 +1,44 @@
+/**
+ * @fileoverview Rutter - Main class for building Kubernetes manifests and Helm charts
+ * @since 1.0.0
+ */
 import { App, Chart, Testing, ApiObject } from 'cdk8s';
 import YAML from 'yaml';
 import { include, helm } from './helm.js';
 import { HelmChartWriter } from './HelmChartWriter.js';
+import { SecurityUtils } from './security.js';
 /**
- * Rutter builds Kubernetes manifests using cdk8s and writes a Helm chart.
+ * Rutter - Main class for building Kubernetes manifests and Helm charts
+ *
+ * Rutter (maritime pilot) guides the generation of Kubernetes resources
+ * using cdk8s and outputs complete Helm charts with proper templating.
+ *
+ * @class Rutter
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const rutter = new Rutter({
+ *   meta: { name: 'my-app', version: '1.0.0' },
+ *   defaultValues: { replicas: 3 }
+ * });
+ *
+ * rutter.addDeployment({
+ *   name: 'web',
+ *   image: 'nginx:1.21',
+ *   replicas: 3
+ * });
+ *
+ * rutter.write('./charts/my-app');
+ * ```
  */
 export class Rutter {
+    /**
+     * Creates a new Rutter instance
+     *
+     * @param {RutterProps} props - Configuration properties
+     * @since 1.0.0
+     */
     constructor(props) {
         this.assets = [];
         this.valueOverrides = {};
@@ -14,7 +47,21 @@ export class Rutter {
         this.chart = new Chart(this.app, props.manifestName ?? props.meta.name);
     }
     /**
-     * Set dynamic value overrides (from --set flags)
+     * Sets dynamic value overrides for Helm values
+     *
+     * Used by CLI --set flags to override default values at runtime.
+     *
+     * @param {Record<string, string>} overrides - Key-value pairs to override
+     *
+     * @example
+     * ```typescript
+     * rutter.setValues({
+     *   'image.tag': 'v2.0.0',
+     *   'replicas': '5'
+     * });
+     * ```
+     *
+     * @since 1.0.0
      */
     setValues(overrides) {
         this.valueOverrides = { ...this.valueOverrides, ...overrides };
@@ -55,11 +102,32 @@ export class Rutter {
         try {
             return JSON.parse(value);
         }
-        catch {
+        catch (error) {
+            // Log parsing error for debugging purposes
+            console.debug(`Failed to parse value as JSON: ${value}`, error);
             // If not valid JSON, treat as string
             return value;
         }
     }
+    /**
+     * Adds a Kubernetes Deployment to the chart
+     *
+     * @param {DeploymentSpec} spec - Deployment specification
+     * @returns {ApiObject} The created Deployment object
+     *
+     * @example
+     * ```typescript
+     * rutter.addDeployment({
+     *   name: 'web-app',
+     *   image: 'nginx:1.21',
+     *   replicas: 3,
+     *   containerPort: 80,
+     *   env: { NODE_ENV: 'production' }
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
     addDeployment(spec) {
         const match = spec.matchLabels ?? {
             [Rutter.LABEL_NAME]: include(Rutter.HELPER_NAME),
@@ -133,6 +201,23 @@ export class Rutter {
         this.capture(dep, `${spec.name}-deployment`);
         return dep;
     }
+    /**
+     * Adds a Kubernetes Service to the chart
+     *
+     * @param {ServiceSpec} spec - Service specification
+     * @returns {ApiObject} The created Service object
+     *
+     * @example
+     * ```typescript
+     * rutter.addService({
+     *   name: 'web-service',
+     *   ports: [{ port: 80, targetPort: 8080 }],
+     *   type: 'LoadBalancer'
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
     addService(spec) {
         const svc = new ApiObject(this.chart, spec.name, {
             apiVersion: 'v1',
@@ -240,6 +325,24 @@ export class Rutter {
         this.capture(rs, `${spec.name}-replicaset`);
         return rs;
     }
+    /**
+     * Adds a Kubernetes Job to the chart
+     *
+     * @param {JobSpec} spec - Job specification
+     * @returns {ApiObject} The created Job object
+     *
+     * @example
+     * ```typescript
+     * rutter.addJob({
+     *   name: 'data-migration',
+     *   image: 'migrate:latest',
+     *   command: ['./migrate.sh'],
+     *   backoffLimit: 3
+     * });
+     * ```
+     *
+     * @since 2.1.0
+     */
     addJob(spec) {
         // Validate Job specification
         this.validateJobSpec(spec);
@@ -262,6 +365,24 @@ export class Rutter {
         this.capture(job, `${spec.name}-job`);
         return job;
     }
+    /**
+     * Adds a Kubernetes CronJob to the chart
+     *
+     * @param {CronJobSpec} spec - CronJob specification
+     * @returns {ApiObject} The created CronJob object
+     *
+     * @example
+     * ```typescript
+     * rutter.addCronJob({
+     *   name: 'backup-job',
+     *   schedule: '0 2 * * *',
+     *   image: 'backup:latest',
+     *   command: ['./backup.sh']
+     * });
+     * ```
+     *
+     * @since 2.1.0
+     */
     addCronJob(spec) {
         // Validate CronJob specification
         this.validateCronJobSpec(spec);
@@ -284,6 +405,29 @@ export class Rutter {
         this.capture(cronJob, `${spec.name}-cronjob`);
         return cronJob;
     }
+    /**
+     * Adds a Kubernetes Ingress to the chart
+     *
+     * @param {IngressSpec} spec - Ingress specification
+     * @returns {ApiObject} The created Ingress object
+     *
+     * @example
+     * ```typescript
+     * rutter.addIngress({
+     *   name: 'web-ingress',
+     *   rules: [{
+     *     host: 'example.com',
+     *     paths: [{
+     *       path: '/',
+     *       pathType: 'Prefix',
+     *       backend: { service: { name: 'web-service', port: { number: 80 } } }
+     *     }]
+     *   }]
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
     addIngress(spec) {
         const ing = new ApiObject(this.chart, spec.name, {
             apiVersion: Rutter.NETWORKING_API_VERSION,
@@ -444,12 +588,31 @@ export class Rutter {
         }
         // Warn about common misconfigurations
         if (storageClassName?.includes('azure-disk') && accessModes.includes('ReadWriteMany')) {
-            console.warn(`PVC ${spec.name}: Azure Disk does not support ReadWriteMany, consider Azure Files`);
+            console.warn(SecurityUtils.sanitizeLogMessage(`PVC ${spec.name}: Azure Disk does not support ReadWriteMany, consider Azure Files`));
         }
         if (storageClassName?.includes('ebs') && accessModes.includes('ReadWriteMany')) {
-            console.warn(`PVC ${spec.name}: EBS does not support ReadWriteMany, consider EFS`);
+            console.warn(SecurityUtils.sanitizeLogMessage(`PVC ${spec.name}: EBS does not support ReadWriteMany, consider EFS`));
         }
     }
+    /**
+     * Adds a Kubernetes ConfigMap to the chart
+     *
+     * @param {ConfigMapSpec} spec - ConfigMap specification
+     * @returns {ApiObject} The created ConfigMap object
+     *
+     * @example
+     * ```typescript
+     * rutter.addConfigMap({
+     *   name: 'app-config',
+     *   data: {
+     *     'config.yaml': 'key: value',
+     *     'app.properties': 'debug=true'
+     *   }
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
     addConfigMap(spec) {
         const cm = new ApiObject(this.chart, spec.name, {
             apiVersion: 'v1',
@@ -466,6 +629,25 @@ export class Rutter {
         this.capture(cm, `${spec.name}-configmap`);
         return cm;
     }
+    /**
+     * Adds a Kubernetes Secret to the chart
+     *
+     * @param {SecretSpec} spec - Secret specification
+     * @returns {ApiObject} The created Secret object
+     *
+     * @example
+     * ```typescript
+     * rutter.addSecret({
+     *   name: 'app-secrets',
+     *   stringData: {
+     *     'username': 'admin',
+     *     'password': 'secret123'
+     *   }
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
     addSecret(spec) {
         const sec = new ApiObject(this.chart, spec.name, {
             apiVersion: 'v1',
@@ -483,6 +665,23 @@ export class Rutter {
         this.capture(sec, `${spec.name}-secret`);
         return sec;
     }
+    /**
+     * Adds a Kubernetes ServiceAccount to the chart
+     *
+     * @param {ServiceAccountSpec} spec - ServiceAccount specification
+     * @returns {ApiObject} The created ServiceAccount object
+     *
+     * @example
+     * ```typescript
+     * rutter.addServiceAccount({
+     *   name: 'app-sa',
+     *   awsRoleArn: 'arn:aws:iam::123456789012:role/MyRole',
+     *   automountServiceAccountToken: true
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
     addServiceAccount(spec) {
         const annotations = this.buildServiceAccountAnnotations(spec);
         const sa = new ApiObject(this.chart, spec.name, {
@@ -539,6 +738,28 @@ export class Rutter {
             annotations['iam.gke.io/gcp-service-account'] = spec.gcpServiceAccountEmail;
         }
     }
+    /**
+     * Adds a Kubernetes HorizontalPodAutoscaler to the chart
+     *
+     * @param {HorizontalPodAutoscalerSpec} spec - HPA specification
+     * @returns {ApiObject} The created HPA object
+     *
+     * @example
+     * ```typescript
+     * rutter.addHorizontalPodAutoscaler({
+     *   name: 'web-hpa',
+     *   scaleTargetRef: {
+     *     apiVersion: 'apps/v1',
+     *     kind: 'Deployment',
+     *     name: 'web-app'
+     *   },
+     *   minReplicas: 2,
+     *   maxReplicas: 10
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
     addHorizontalPodAutoscaler(spec) {
         // Default metrics if none provided (CPU utilization at 80%)
         const defaultMetrics = [
@@ -705,8 +926,12 @@ export class Rutter {
         if (spec.subPath) {
             volumeAttributes['subPath'] = spec.subPath;
         }
-        if (Object.keys(volumeAttributes).length > 0) {
-            csiSpec['volumeAttributes'] = volumeAttributes;
+        // Only add volumeAttributes if it has properties (more efficient than Object.keys().length)
+        for (const key in volumeAttributes) {
+            if (Object.prototype.hasOwnProperty.call(volumeAttributes, key)) {
+                csiSpec['volumeAttributes'] = volumeAttributes;
+                break;
+            }
         }
         const pv = new ApiObject(this.chart, spec.name, {
             apiVersion: 'v1',
@@ -2017,13 +2242,513 @@ export class Rutter {
         return 'resource';
     }
     /**
-     * Add a raw CRD manifest to the chart (written under crds/).
+     * Adds a raw CRD manifest to the chart
+     *
+     * @param {string} yaml - YAML content of the CRD
+     * @param {string} [id='crd'] - Asset identifier
+     *
+     * @example
+     * ```typescript
+     * const crdYaml = `
+     * apiVersion: apiextensions.k8s.io/v1
+     * kind: CustomResourceDefinition
+     * metadata:
+     *   name: myresources.example.com
+     * `;
+     * rutter.addCrd(crdYaml, 'myresource-crd');
+     * ```
+     *
+     * @since 1.0.0
      */
     addCrd(yaml, id = 'crd') {
         this.assets.push({ id, yaml, target: 'crds' });
     }
     /**
-     * Synthesize the cdk8s app and write a Helm chart to outDir.
+     * Add Karpenter NodePool for intelligent node provisioning.
+     * Creates a NodePool resource that defines compute requirements and lifecycle policies.
+     *
+     * @param spec - Karpenter NodePool specification
+     * @returns The created NodePool ApiObject
+     *
+     * @example
+     * ```typescript
+     * rutter.addKarpenterNodePool({
+     *   name: 'general-purpose',
+     *   requirements: [
+     *     { key: 'eks.amazonaws.com/instance-category', operator: 'In', values: ['c', 'm', 'r'] },
+     *     { key: 'kubernetes.io/arch', operator: 'In', values: ['amd64'] }
+     *   ],
+     *   limits: { cpu: '1000', memory: '1000Gi' },
+     *   nodeClassRef: { name: 'default' }
+     * });
+     * ```
+     *
+     * @since 2.3.0
+     */
+    addKarpenterNodePool(spec) {
+        // Validate NodePool specification
+        this.validateKarpenterNodePoolSpec(spec);
+        const nodePool = new ApiObject(this.chart, spec.name, {
+            apiVersion: 'karpenter.sh/v1',
+            kind: 'NodePool',
+            metadata: {
+                name: spec.name,
+                ...(spec.labels ? { labels: spec.labels } : {}),
+                ...(spec.annotations ? { annotations: spec.annotations } : {}),
+            },
+            spec: {
+                template: {
+                    metadata: {
+                        ...(spec.labels ? { labels: spec.labels } : {}),
+                    },
+                    spec: {
+                        nodeClassRef: {
+                            group: spec.nodeClassRef.group ?? 'eks.amazonaws.com',
+                            kind: spec.nodeClassRef.kind ?? 'NodeClass',
+                            name: spec.nodeClassRef.name,
+                        },
+                        ...(spec.requirements ? { requirements: spec.requirements } : {}),
+                        ...(spec.taints ? { taints: spec.taints } : {}),
+                    },
+                },
+                ...(spec.limits ? { limits: spec.limits } : {}),
+                ...(spec.disruption ? { disruption: spec.disruption } : {}),
+            },
+        });
+        this.capture(nodePool, `${spec.name}-nodepool`);
+        return nodePool;
+    }
+    /**
+     * Add Karpenter EC2 NodeClass for AWS-specific node configuration.
+     * Creates a NodeClass resource that defines EC2 instance settings and networking.
+     *
+     * @param spec - Karpenter EC2 NodeClass specification
+     * @returns The created NodeClass ApiObject
+     *
+     * @example
+     * ```typescript
+     * rutter.addKarpenterEC2NodeClass({
+     *   name: 'default',
+     *   amiFamily: 'AL2023',
+     *   subnetSelectorTerms: [{ tags: { 'karpenter.sh/discovery': 'my-cluster' } }],
+     *   securityGroupSelectorTerms: [{ tags: { 'karpenter.sh/discovery': 'my-cluster' } }],
+     *   role: 'KarpenterNodeInstanceProfile'
+     * });
+     * ```
+     *
+     * @since 2.3.0
+     */
+    addKarpenterEC2NodeClass(spec) {
+        // Validate EC2 NodeClass specification
+        this.validateKarpenterEC2NodeClassSpec(spec);
+        const nodeClass = new ApiObject(this.chart, spec.name, {
+            apiVersion: 'eks.amazonaws.com/v1',
+            kind: 'NodeClass',
+            metadata: {
+                name: spec.name,
+                ...(spec.labels ? { labels: spec.labels } : {}),
+                ...(spec.annotations ? { annotations: spec.annotations } : {}),
+            },
+            spec: {
+                ...(spec.amiFamily ? { amiFamily: spec.amiFamily } : {}),
+                ...(spec.instanceStorePolicy ? { instanceStorePolicy: spec.instanceStorePolicy } : {}),
+                ...(spec.userData ? { userData: spec.userData } : {}),
+                ...(spec.subnetSelectorTerms ? { subnetSelectorTerms: spec.subnetSelectorTerms } : {}),
+                ...(spec.securityGroupSelectorTerms
+                    ? { securityGroupSelectorTerms: spec.securityGroupSelectorTerms }
+                    : {}),
+                ...(spec.role ? { role: spec.role } : {}),
+                ...(spec.instanceProfile ? { instanceProfile: spec.instanceProfile } : {}),
+                ...(spec.metadataOptions ? { metadataOptions: spec.metadataOptions } : {}),
+                ...(spec.blockDeviceMappings ? { blockDeviceMappings: spec.blockDeviceMappings } : {}),
+                ...(spec.tags ? { tags: spec.tags } : {}),
+            },
+        });
+        this.capture(nodeClass, `${spec.name}-nodeclass`);
+        return nodeClass;
+    }
+    /**
+     * Validate Karpenter NodePool specification
+     */
+    validateKarpenterNodePoolSpec(spec) {
+        this.validateNodeClassRef(spec);
+        this.validateNodePoolRequirements(spec);
+        this.validateNodePoolLimits(spec);
+        this.validateNodePoolDisruption(spec);
+    }
+    validateNodeClassRef(spec) {
+        if (!spec.nodeClassRef.name) {
+            throw new Error(`Karpenter NodePool ${spec.name}: nodeClassRef.name is required`);
+        }
+    }
+    validateNodePoolRequirements(spec) {
+        if (!spec.requirements)
+            return;
+        const operatorsRequiringValues = ['In', 'NotIn', 'Gt', 'Lt'];
+        for (const req of spec.requirements) {
+            if (operatorsRequiringValues.includes(req.operator) && !req.values?.length) {
+                throw new Error(`Karpenter NodePool ${spec.name}: requirement with operator '${req.operator}' must have values`);
+            }
+        }
+    }
+    validateNodePoolLimits(spec) {
+        if (!spec.limits)
+            return;
+        if (spec.limits.cpu && !this.isValidResourceQuantity(spec.limits.cpu)) {
+            throw new Error(`Karpenter NodePool ${spec.name}: invalid CPU limit format`);
+        }
+        if (spec.limits.memory && !this.isValidResourceQuantity(spec.limits.memory)) {
+            throw new Error(`Karpenter NodePool ${spec.name}: invalid memory limit format`);
+        }
+    }
+    validateNodePoolDisruption(spec) {
+        if (!spec.disruption)
+            return;
+        if (spec.disruption.consolidateAfter &&
+            !this.isValidDuration(spec.disruption.consolidateAfter)) {
+            throw new Error(`Karpenter NodePool ${spec.name}: invalid consolidateAfter duration format`);
+        }
+        if (spec.disruption.expireAfter && !this.isValidDuration(spec.disruption.expireAfter)) {
+            throw new Error(`Karpenter NodePool ${spec.name}: invalid expireAfter duration format`);
+        }
+    }
+    /**
+     * Validate Karpenter EC2 NodeClass specification
+     */
+    validateKarpenterEC2NodeClassSpec(spec) {
+        this.validateNodeClassSelectors(spec);
+        this.validateNodeClassBlockDevices(spec);
+        this.validateNodeClassMetadataOptions(spec);
+    }
+    validateNodeClassSelectors(spec) {
+        if (!spec.subnetSelectorTerms?.length && !spec.securityGroupSelectorTerms?.length) {
+            console.warn(`Karpenter EC2 NodeClass ${spec.name}: Consider specifying subnet and security group selectors for better control`);
+        }
+    }
+    validateNodeClassBlockDevices(spec) {
+        if (!spec.blockDeviceMappings)
+            return;
+        for (const mapping of spec.blockDeviceMappings) {
+            if (mapping.ebs?.volumeSize && !this.isValidStorageSize(mapping.ebs.volumeSize)) {
+                throw new Error(`Karpenter EC2 NodeClass ${spec.name}: invalid volume size format in block device mapping`);
+            }
+            if (mapping.ebs?.iops !== undefined && mapping.ebs.iops < 100) {
+                throw new Error(`Karpenter EC2 NodeClass ${spec.name}: IOPS must be at least 100 for block device mapping`);
+            }
+        }
+    }
+    validateNodeClassMetadataOptions(spec) {
+        if (spec.metadataOptions?.httpPutResponseHopLimit === undefined)
+            return;
+        const hopLimit = spec.metadataOptions.httpPutResponseHopLimit;
+        if (hopLimit < 1 || hopLimit > 64) {
+            throw new Error(`Karpenter EC2 NodeClass ${spec.name}: httpPutResponseHopLimit must be between 1 and 64`);
+        }
+    }
+    /**
+     * Validate Kubernetes resource quantity format (e.g., "100m", "1Gi")
+     */
+    isValidResourceQuantity(quantity) {
+        // Safe validation without regex to prevent ReDoS
+        const validUnits = ['m', 'k', 'M', 'G', 'T', 'P', 'E', 'Ki', 'Mi', 'Gi', 'Ti', 'Pi', 'Ei'];
+        // Find the unit suffix
+        let numberPart = quantity;
+        let hasValidUnit = false;
+        for (const unit of validUnits) {
+            if (quantity.endsWith(unit)) {
+                numberPart = quantity.slice(0, -unit.length);
+                hasValidUnit = true;
+                break;
+            }
+        }
+        // If no unit found, that's also valid (plain number)
+        if (!hasValidUnit && quantity.length > 0) {
+            numberPart = quantity;
+        }
+        // Validate the number part
+        const num = parseFloat(numberPart);
+        return !isNaN(num) && num >= 0 && numberPart === String(num);
+    }
+    /**
+     * Validate duration format (e.g., "30s", "5m", "1h")
+     */
+    isValidDuration(duration) {
+        // Safe validation without regex to prevent ReDoS
+        const validUnits = ['ns', 'us', 'µs', 'ms', 's', 'm', 'h'];
+        // Find the unit suffix
+        let numberPart = duration;
+        let hasValidUnit = false;
+        for (const unit of validUnits) {
+            if (duration.endsWith(unit)) {
+                numberPart = duration.slice(0, -unit.length);
+                hasValidUnit = true;
+                break;
+            }
+        }
+        // Duration must have a unit
+        if (!hasValidUnit)
+            return false;
+        // Validate the number part
+        const num = parseFloat(numberPart);
+        return !isNaN(num) && num >= 0 && numberPart === String(num);
+    }
+    /**
+     * Validate storage size format (e.g., "20", "100Gi")
+     */
+    isValidStorageSize(size) {
+        // Safe validation without regex to prevent ReDoS
+        const validUnits = ['Gi', 'G', 'Ti', 'T'];
+        // Find the unit suffix
+        let numberPart = size;
+        let hasValidUnit = false;
+        for (const unit of validUnits) {
+            if (size.endsWith(unit)) {
+                numberPart = size.slice(0, -unit.length);
+                hasValidUnit = true;
+                break;
+            }
+        }
+        // If no unit found, that's also valid (plain number)
+        if (!hasValidUnit && size.length > 0) {
+            numberPart = size;
+        }
+        // Validate the number part
+        const num = parseFloat(numberPart);
+        return !isNaN(num) && num >= 0 && numberPart === String(num);
+    }
+    /**
+     * Add Karpenter NodeClaim for individual node provisioning.
+     * Creates a NodeClaim resource that represents a request for a single node.
+     *
+     * @param spec - Karpenter NodeClaim specification
+     * @returns The created NodeClaim ApiObject
+     *
+     * @example
+     * ```typescript
+     * rutter.addKarpenterNodeClaim({
+     *   name: 'high-memory-node',
+     *   requirements: [
+     *     { key: 'eks.amazonaws.com/instance-category', operator: 'In', values: ['r'] },
+     *     { key: 'eks.amazonaws.com/instance-cpu', operator: 'In', values: ['16', '32'] }
+     *   ],
+     *   nodeClassRef: { name: 'memory-optimized' },
+     *   expireAfter: '24h'
+     * });
+     * ```
+     *
+     * @since 2.3.0
+     */
+    addKarpenterNodeClaim(spec) {
+        // Validate NodeClaim specification
+        this.validateKarpenterNodeClaimSpec(spec);
+        const nodeClaim = new ApiObject(this.chart, spec.name, {
+            apiVersion: 'karpenter.sh/v1',
+            kind: 'NodeClaim',
+            metadata: {
+                name: spec.name,
+                ...(spec.labels ? { labels: spec.labels } : {}),
+                ...(spec.annotations ? { annotations: spec.annotations } : {}),
+            },
+            spec: {
+                nodeClassRef: {
+                    group: spec.nodeClassRef.group ?? 'eks.amazonaws.com',
+                    kind: spec.nodeClassRef.kind ?? 'NodeClass',
+                    name: spec.nodeClassRef.name,
+                },
+                ...(spec.requirements ? { requirements: spec.requirements } : {}),
+                ...(spec.taints ? { taints: spec.taints } : {}),
+                ...(spec.startupTaints ? { startupTaints: spec.startupTaints } : {}),
+                ...(spec.expireAfter ? { expireAfter: spec.expireAfter } : {}),
+                ...(spec.terminationGracePeriod
+                    ? { terminationGracePeriod: spec.terminationGracePeriod }
+                    : {}),
+            },
+        });
+        this.capture(nodeClaim, `${spec.name}-nodeclaim`);
+        return nodeClaim;
+    }
+    /**
+     * Add advanced Karpenter scheduling configuration.
+     * Creates scheduling constraints for fine-grained pod placement control.
+     *
+     * @param spec - Karpenter scheduling specification
+     * @returns Configuration object for use in pod specs
+     *
+     * @example
+     * ```typescript
+     * const schedulingConfig = rutter.addKarpenterScheduling({
+     *   name: 'zone-spread-scheduling',
+     *   topologySpreadConstraints: [{
+     *     maxSkew: 1,
+     *     topologyKey: 'topology.kubernetes.io/zone',
+     *     whenUnsatisfiable: 'DoNotSchedule',
+     *     labelSelector: { matchLabels: { app: 'web' } }
+     *   }],
+     *   nodeAffinity: {
+     *     requiredDuringSchedulingIgnoredDuringExecution: {
+     *       nodeSelectorTerms: [{
+     *         matchExpressions: [{
+     *           key: 'eks.amazonaws.com/instance-category',
+     *           operator: 'In',
+     *           values: ['c', 'm']
+     *         }]
+     *       }]
+     *     }
+     *   }
+     * });
+     * ```
+     *
+     * @since 2.3.0
+     */
+    addKarpenterScheduling(spec) {
+        // Validate scheduling specification
+        this.validateKarpenterSchedulingSpec(spec);
+        // Return scheduling configuration for use in pod specs
+        return {
+            ...(spec.nodeSelector ? { nodeSelector: spec.nodeSelector } : {}),
+            ...(spec.nodeAffinity ? { affinity: { nodeAffinity: spec.nodeAffinity } } : {}),
+            ...(spec.topologySpreadConstraints
+                ? { topologySpreadConstraints: spec.topologySpreadConstraints }
+                : {}),
+            ...(spec.tolerations ? { tolerations: spec.tolerations } : {}),
+            ...(spec.priorityClassName ? { priorityClassName: spec.priorityClassName } : {}),
+            ...(spec.schedulerName ? { schedulerName: spec.schedulerName } : {}),
+        };
+    }
+    /**
+     * Create advanced disruption configuration for NodePools.
+     * Provides fine-grained control over when and how nodes are disrupted.
+     *
+     * @param spec - Advanced disruption specification
+     * @returns Disruption configuration object
+     *
+     * @example
+     * ```typescript
+     * const disruptionConfig = rutter.createKarpenterDisruption({
+     *   consolidationPolicy: 'WhenEmptyOrUnderutilized',
+     *   consolidateAfter: '30s',
+     *   expireAfter: '2160h', // 90 days
+     *   budgets: [{
+     *     schedule: '0 9 * * mon-fri', // Business hours
+     *     duration: '8h',
+     *     nodes: '0', // No disruption during business hours
+     *     reasons: ['Underutilized', 'Empty']
+     *   }]
+     * });
+     * ```
+     *
+     * @since 2.3.0
+     */
+    createKarpenterDisruption(spec) {
+        // Validate disruption specification
+        this.validateKarpenterDisruptionSpec(spec);
+        return {
+            ...(spec.consolidationPolicy ? { consolidationPolicy: spec.consolidationPolicy } : {}),
+            ...(spec.consolidateAfter ? { consolidateAfter: spec.consolidateAfter } : {}),
+            ...(spec.expireAfter ? { expireAfter: spec.expireAfter } : {}),
+            ...(spec.budgets ? { budgets: spec.budgets } : {}),
+        };
+    }
+    /**
+     * Validate Karpenter NodeClaim specification
+     */
+    validateKarpenterNodeClaimSpec(spec) {
+        // Validate NodeClass reference
+        if (!spec.nodeClassRef.name) {
+            throw new Error(`Karpenter NodeClaim ${spec.name}: nodeClassRef.name is required`);
+        }
+        // Validate expiration format
+        if (spec.expireAfter && !this.isValidDuration(spec.expireAfter)) {
+            throw new Error(`Karpenter NodeClaim ${spec.name}: invalid expireAfter duration format`);
+        }
+        // Validate termination grace period
+        if (spec.terminationGracePeriod && !this.isValidDuration(spec.terminationGracePeriod)) {
+            throw new Error(`Karpenter NodeClaim ${spec.name}: invalid terminationGracePeriod duration format`);
+        }
+        // Validate requirements
+        if (spec.requirements) {
+            for (const req of spec.requirements) {
+                if (['In', 'NotIn', 'Gt', 'Lt'].includes(req.operator) && !req.values?.length) {
+                    throw new Error(`Karpenter NodeClaim ${spec.name}: requirement with operator '${req.operator}' must have values`);
+                }
+            }
+        }
+    }
+    /**
+     * Validate Karpenter scheduling specification
+     */
+    validateKarpenterSchedulingSpec(spec) {
+        this.validateTopologySpreadConstraints(spec);
+        this.validateSchedulingTolerations(spec);
+    }
+    validateTopologySpreadConstraints(spec) {
+        if (!spec.topologySpreadConstraints)
+            return;
+        for (const constraint of spec.topologySpreadConstraints) {
+            if (constraint.maxSkew < 1) {
+                throw new Error(`Karpenter Scheduling ${spec.name}: maxSkew must be at least 1 in topology spread constraint`);
+            }
+            if (!constraint.topologyKey) {
+                throw new Error(`Karpenter Scheduling ${spec.name}: topologyKey is required in topology spread constraint`);
+            }
+        }
+    }
+    validateSchedulingTolerations(spec) {
+        if (!spec.tolerations)
+            return;
+        for (const toleration of spec.tolerations) {
+            if (toleration.operator === 'Equal' && !toleration.value) {
+                throw new Error(`Karpenter Scheduling ${spec.name}: value is required when operator is 'Equal' in toleration`);
+            }
+        }
+    }
+    /**
+     * Validate Karpenter disruption specification
+     */
+    validateKarpenterDisruptionSpec(spec) {
+        this.validateDisruptionDurations(spec);
+        this.validateDisruptionBudgets(spec);
+    }
+    validateDisruptionDurations(spec) {
+        if (spec.consolidateAfter && !this.isValidDuration(spec.consolidateAfter)) {
+            throw new Error('Invalid consolidateAfter duration format');
+        }
+        if (spec.expireAfter && !this.isValidDuration(spec.expireAfter)) {
+            throw new Error('Invalid expireAfter duration format');
+        }
+    }
+    validateDisruptionBudgets(spec) {
+        if (!spec.budgets)
+            return;
+        for (const budget of spec.budgets) {
+            if (budget.schedule && budget.duration) {
+                // Basic cron validation - should have 5 parts
+                const cronParts = budget.schedule.split(' ');
+                if (cronParts.length !== 5) {
+                    throw new Error('Budget schedule must be a valid cron expression with 5 parts');
+                }
+            }
+            if (budget.duration && !this.isValidDuration(budget.duration)) {
+                throw new Error('Invalid budget duration format');
+            }
+        }
+    }
+    /**
+     * Synthesizes the cdk8s app and writes a complete Helm chart
+     *
+     * Generates all Kubernetes manifests, applies Helm templating,
+     * and writes the complete chart structure to the output directory.
+     *
+     * @param {string} outDir - Output directory for the Helm chart
+     * @throws {Error} If synthesis or writing fails
+     *
+     * @example
+     * ```typescript
+     * rutter.write('./charts/my-app');
+     * // Creates: ./charts/my-app/Chart.yaml, values.yaml, templates/, etc.
+     * ```
+     *
+     * @since 1.0.0
      */
     write(outDir) {
         // Use cdk8s Testing.synth to obtain manifest objects