timonel 2.1.1 → 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',
@@ -1055,6 +1280,257 @@ export class Rutter {
         this.capture(spc, `${spec.name}-secretproviderclass`);
         return spc;
     }
+    /**
+     * Add Azure Workload Identity ServiceAccount.
+     * Creates a ServiceAccount with Azure Workload Identity annotations for secure authentication.
+     *
+     * @param spec - Azure Workload Identity ServiceAccount specification
+     * @returns The created ServiceAccount ApiObject
+     *
+     * @example
+     * ```typescript
+     * rutter.addAzureWorkloadIdentityServiceAccount({
+     *   name: 'workload-identity-sa',
+     *   clientId: '12345678-1234-1234-1234-123456789012',
+     *   tenantId: '87654321-4321-4321-4321-210987654321',
+     *   tokenExpiration: 3600
+     * });
+     * ```
+     */
+    addAzureWorkloadIdentityServiceAccount(spec) {
+        // Validate all inputs first for security
+        if (spec.tokenExpiration !== undefined &&
+            (spec.tokenExpiration < 3600 || spec.tokenExpiration > 86400)) {
+            throw new Error(`Azure Workload Identity ${spec.name}: tokenExpiration must be between 3600 and 86400 seconds`);
+        }
+        if (!spec.clientId?.match(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i)) {
+            throw new Error(`Azure Workload Identity ${spec.name}: Invalid client ID format`);
+        }
+        if (!spec.tenantId?.match(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i)) {
+            throw new Error(`Azure Workload Identity ${spec.name}: Invalid tenant ID format`);
+        }
+        const annotations = {
+            'azure.workload.identity/client-id': spec.clientId,
+            'azure.workload.identity/tenant-id': spec.tenantId,
+            ...(spec.tokenExpiration !== undefined
+                ? {
+                    'azure.workload.identity/service-account-token-expiration': String(spec.tokenExpiration),
+                }
+                : {}),
+            ...(spec.annotations ?? {}),
+        };
+        const sa = new ApiObject(this.chart, spec.name, {
+            apiVersion: 'v1',
+            kind: 'ServiceAccount',
+            metadata: {
+                name: spec.name,
+                annotations,
+                ...(spec.labels ? { labels: spec.labels } : {}),
+            },
+            automountServiceAccountToken: spec.automountServiceAccountToken,
+            imagePullSecrets: spec.imagePullSecrets?.map((n) => ({ name: n })),
+            secrets: spec.secrets?.map((n) => ({ name: n })),
+        });
+        this.capture(sa, `${spec.name}-serviceaccount`);
+        return sa;
+    }
+    /**
+     * Add Azure Key Vault SecretProviderClass.
+     * Creates a SecretProviderClass for mounting secrets from Azure Key Vault using CSI driver.
+     *
+     * @param spec - Azure Key Vault SecretProviderClass specification
+     * @returns The created SecretProviderClass ApiObject
+     *
+     * @example
+     * ```typescript
+     * rutter.addAzureKeyVaultSecretProviderClass({
+     *   name: 'app-secrets',
+     *   keyVaultName: 'my-keyvault',
+     *   tenantId: '87654321-4321-4321-4321-210987654321',
+     *   objects: [
+     *     { objectName: 'database-password', objectType: 'secret' },
+     *     { objectName: 'api-key', objectType: 'secret', objectAlias: 'API_KEY' }
+     *   ],
+     *   userAssignedIdentityID: '12345678-1234-1234-1234-123456789012'
+     * });
+     * ```
+     */
+    addAzureKeyVaultSecretProviderClass(spec) {
+        // Validate object names for security - prevent path traversal attacks
+        spec.objects.forEach((obj) => {
+            if (obj.objectName.includes('../') || obj.objectName.includes('..\\')) {
+                throw new Error(`Azure Key Vault ${spec.name}: Object name '${obj.objectName}' contains invalid path traversal sequences`);
+            }
+        });
+        const objects = spec.objects.map((obj) => {
+            const baseObj = {
+                objectName: obj.objectName,
+                objectType: obj.objectType,
+            };
+            if (obj.objectAlias) {
+                baseObj['objectAlias'] = obj.objectAlias;
+            }
+            if (obj.objectVersion) {
+                baseObj['objectVersion'] = obj.objectVersion;
+            }
+            return baseObj;
+        });
+        const objectsYaml = YAML.stringify(objects, { indent: 2 }).trim();
+        const parameters = {
+            keyvaultName: spec.keyVaultName,
+            tenantId: spec.tenantId,
+            objects: `|\n  ${objectsYaml.split('\n').join('\n  ')}`,
+        };
+        if (spec.userAssignedIdentityID) {
+            parameters['userAssignedIdentityID'] = spec.userAssignedIdentityID;
+        }
+        if (spec.cloudName) {
+            parameters['cloudName'] = spec.cloudName;
+        }
+        const spc = new ApiObject(this.chart, spec.name, {
+            apiVersion: 'secrets-store.csi.x-k8s.io/v1',
+            kind: 'SecretProviderClass',
+            metadata: {
+                name: spec.name,
+                ...(spec.labels ? { labels: spec.labels } : {}),
+                ...(spec.annotations ? { annotations: spec.annotations } : {}),
+            },
+            spec: {
+                provider: 'azure',
+                parameters,
+            },
+        });
+        this.capture(spc, `${spec.name}-secretproviderclass`);
+        return spc;
+    }
+    /**
+     * Add Azure Files StorageClass.
+     * Creates a StorageClass for dynamic provisioning of Azure Files volumes.
+     *
+     * @param spec - Azure Files StorageClass specification
+     * @returns The created StorageClass ApiObject
+     *
+     * @example
+     * ```typescript
+     * rutter.addAzureFilesStorageClass({
+     *   name: 'azure-files-premium',
+     *   skuName: 'Premium_LRS',
+     *   protocol: 'smb',
+     *   allowSharedAccess: true
+     * });
+     * ```
+     */
+    addAzureFilesStorageClass(spec) {
+        // Validate Azure Files parameters for security and compliance
+        this.validateAzureFilesParameters(spec);
+        const parameters = this.buildAzureFilesParameters(spec);
+        const sc = new ApiObject(this.chart, spec.name, {
+            apiVersion: Rutter.STORAGE_API_VERSION,
+            kind: 'StorageClass',
+            metadata: {
+                name: spec.name,
+                ...(spec.labels ? { labels: spec.labels } : {}),
+                ...(spec.annotations ? { annotations: spec.annotations } : {}),
+            },
+            provisioner: Rutter.AZURE_FILES_CSI_DRIVER,
+            parameters,
+            reclaimPolicy: spec.reclaimPolicy ?? 'Delete',
+            allowVolumeExpansion: spec.allowVolumeExpansion ?? true,
+            volumeBindingMode: spec.volumeBindingMode ?? 'Immediate',
+            ...(spec.mountOptions ? { mountOptions: spec.mountOptions } : {}),
+        });
+        this.capture(sc, `${spec.name}-storageclass`);
+        return sc;
+    }
+    /**
+     * Add Azure Files PersistentVolume.
+     * Creates a PersistentVolume for static Azure Files volume provisioning.
+     *
+     * @param spec - Azure Files PersistentVolume specification
+     * @returns The created PersistentVolume ApiObject
+     */
+    addAzureFilesPersistentVolume(spec) {
+        const csiSpec = this.buildAzureFilesPVCSISpec(spec);
+        const pv = new ApiObject(this.chart, spec.name, {
+            apiVersion: 'v1',
+            kind: 'PersistentVolume',
+            metadata: {
+                name: spec.name,
+                ...(spec.labels ? { labels: spec.labels } : {}),
+                ...(spec.annotations ? { annotations: spec.annotations } : {}),
+            },
+            spec: {
+                capacity: { storage: spec.capacity },
+                accessModes: spec.accessModes ?? ['ReadWriteMany'],
+                persistentVolumeReclaimPolicy: spec.reclaimPolicy ?? 'Retain',
+                storageClassName: spec.storageClassName,
+                ...(spec.mountOptions ? { mountOptions: spec.mountOptions } : {}),
+                csi: csiSpec,
+            },
+        });
+        this.capture(pv, `${spec.name}-pv`);
+        return pv;
+    }
+    /**
+     * Add Azure Files PersistentVolumeClaim.
+     * Creates a PersistentVolumeClaim for Azure Files storage.
+     *
+     * @param spec - Azure Files PersistentVolumeClaim specification
+     * @returns The created PersistentVolumeClaim ApiObject
+     */
+    addAzureFilesPersistentVolumeClaim(spec) {
+        const pvc = new ApiObject(this.chart, spec.name, {
+            apiVersion: 'v1',
+            kind: 'PersistentVolumeClaim',
+            metadata: {
+                name: spec.name,
+                ...(spec.labels ? { labels: spec.labels } : {}),
+                ...(spec.annotations ? { annotations: spec.annotations } : {}),
+            },
+            spec: {
+                accessModes: spec.accessModes ?? ['ReadWriteMany'],
+                storageClassName: spec.storageClassName,
+                resources: {
+                    requests: { storage: spec.size },
+                },
+            },
+        });
+        this.capture(pvc, `${spec.name}-pvc`);
+        return pvc;
+    }
+    /**
+     * Add Azure Container Registry ServiceAccount.
+     * Creates a ServiceAccount configured for ACR access.
+     *
+     * @param spec - Azure ACR ServiceAccount specification
+     * @returns The created ServiceAccount ApiObject
+     */
+    addAzureACRServiceAccount(spec) {
+        const annotations = {
+            ...(spec.annotations ?? {}),
+        };
+        // Add Workload Identity annotations if provided
+        if (spec.clientId) {
+            annotations['azure.workload.identity/client-id'] = spec.clientId;
+        }
+        if (spec.tenantId) {
+            annotations['azure.workload.identity/tenant-id'] = spec.tenantId;
+        }
+        const sa = new ApiObject(this.chart, spec.name, {
+            apiVersion: 'v1',
+            kind: 'ServiceAccount',
+            metadata: {
+                name: spec.name,
+                ...(Object.keys(annotations).length ? { annotations } : {}),
+                ...(spec.labels ? { labels: spec.labels } : {}),
+            },
+            automountServiceAccountToken: spec.automountServiceAccountToken,
+            imagePullSecrets: spec.imagePullSecrets?.map((n) => ({ name: n })),
+            secrets: spec.secrets?.map((n) => ({ name: n })),
+        });
+        this.capture(sa, `${spec.name}-serviceaccount`);
+        return sa;
+    }
     addAzureDiskStorageClass(spec) {
         // Validate numeric parameters to prevent runtime errors
         this.validateAzureDiskNumericParameters(spec);
@@ -1435,6 +1911,76 @@ export class Rutter {
             throw new Error('Port 443 requires an SSL certificate to be specified');
         }
     }
+    buildAzureFilesParameters(spec) {
+        const parameters = {
+            skuName: spec.skuName ?? 'Standard_LRS',
+        };
+        if (spec.protocol) {
+            parameters['protocol'] = spec.protocol;
+        }
+        if (spec.allowSharedAccess !== undefined) {
+            parameters['allowSharedAccess'] = String(spec.allowSharedAccess);
+        }
+        if (spec.resourceGroup) {
+            parameters['resourceGroup'] = spec.resourceGroup;
+        }
+        if (spec.storageAccount) {
+            parameters['storageAccount'] = spec.storageAccount;
+        }
+        if (spec.location) {
+            parameters['location'] = spec.location;
+        }
+        if (spec.networkEndpointType) {
+            parameters['networkEndpointType'] = spec.networkEndpointType;
+        }
+        // NFS-specific parameters
+        if (spec.protocol === 'nfs' && spec.mountPermissions) {
+            parameters['mountPermissions'] = spec.mountPermissions;
+        }
+        if (spec.protocol === 'nfs' && spec.rootSquashType) {
+            parameters['rootSquashType'] = spec.rootSquashType;
+        }
+        return parameters;
+    }
+    buildAzureFilesPVCSISpec(spec) {
+        // Validate protocol and secret configuration
+        if (spec.protocol === 'nfs' && spec.secretName) {
+            throw new Error(`Azure Files PV ${spec.name}: NFS protocol does not use secrets for authentication`);
+        }
+        const volumeHandle = this.sanitizeVolumeHandle(spec.storageAccount, spec.shareName);
+        const volumeAttributes = {
+            storageAccount: spec.storageAccount,
+            shareName: spec.shareName,
+        };
+        if (spec.resourceGroup) {
+            volumeAttributes['resourceGroup'] = spec.resourceGroup;
+        }
+        if (spec.protocol) {
+            volumeAttributes['protocol'] = spec.protocol;
+        }
+        if (spec.server) {
+            volumeAttributes['server'] = spec.server;
+        }
+        if (spec.folderName) {
+            volumeAttributes['folderName'] = spec.folderName;
+        }
+        if (spec.mountPermissions) {
+            volumeAttributes['mountPermissions'] = spec.mountPermissions;
+        }
+        const csiSpec = {
+            driver: Rutter.AZURE_FILES_CSI_DRIVER,
+            volumeHandle,
+            volumeAttributes,
+        };
+        // Add secret reference for SMB protocol
+        if (spec.protocol !== 'nfs' && spec.secretName) {
+            csiSpec['nodeStageSecretRef'] = {
+                name: spec.secretName,
+                namespace: spec.secretNamespace ?? 'default',
+            };
+        }
+        return csiSpec;
+    }
     buildPodEnvironment(spec) {
         const envEntries = spec.env
             ? Object.entries(spec.env).map(([name, value]) => this.sanitizeEnvVar(name, value))
@@ -1641,6 +2187,37 @@ export class Rutter {
             },
         };
     }
+    /**
+     * Validate Azure Files parameters for security and compliance
+     */
+    validateAzureFilesParameters(spec) {
+        const validSkuNames = [
+            'Standard_LRS',
+            'Standard_GRS',
+            'Standard_RAGRS',
+            'Standard_ZRS',
+            'Premium_LRS',
+            'Premium_ZRS',
+        ];
+        if (spec.skuName && !validSkuNames.includes(spec.skuName)) {
+            throw new Error(`Invalid skuName: ${spec.skuName}. Must be one of: ${validSkuNames.join(', ')}`);
+        }
+        if (spec.protocol === 'nfs' && spec.mountPermissions) {
+            const permRegex = /^[0-7]{3,4}$/;
+            if (!permRegex.test(spec.mountPermissions)) {
+                throw new Error('mountPermissions must be a valid octal permission string (e.g., "0777")');
+            }
+        }
+    }
+    /**
+     * Sanitize volume handle to ensure valid format for CSI driver
+     */
+    sanitizeVolumeHandle(account, share) {
+        // Remove special characters and ensure valid format
+        const sanitizedAccount = account.replace(/[^a-z0-9]/gi, '').toLowerCase();
+        const sanitizedShare = share.replace(/[^a-z0-9-]/gi, '').toLowerCase();
+        return `${sanitizedAccount}#${sanitizedShare}`;
+    }
     /**
      * Capture the YAML of an ApiObject or Construct into assets.
      */
@@ -1665,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
@@ -1781,5 +2858,6 @@ Rutter.NETWORKING_API_VERSION = 'networking.k8s.io/v1';
 Rutter.STORAGE_API_VERSION = 'storage.k8s.io/v1';
 Rutter.AZURE_DISK_CSI_DRIVER = 'disk.csi.azure.com';
 Rutter.AZURE_DISK_PROVISIONER_ANNOTATION = 'volume.beta.kubernetes.io/storage-provisioner';
+Rutter.AZURE_FILES_CSI_DRIVER = 'file.csi.azure.com';
 Rutter.EMPTY_POD_SELECTOR = {};
 //# sourceMappingURL=Rutter.js.map