timonel 3.1.1 → 3.1.2

package/dist/lib/rutter.d.ts

@@ -1,4 +1,4 @@
-import { ApiObject } from 'cdk8s';
+import { ApiObject, Chart } from 'cdk8s';
 import type { ChartProps } from 'cdk8s';
 import type { Ingress, ServiceAccount } from 'cdk8s-plus-33';
 import type { Construct } from 'constructs';
@@ -8,9 +8,15 @@ import type { AWSALBIngressSpec, AWSEBSStorageClassSpec, AWSECRServiceAccountSpe
 import type { KarpenterEC2NodeClassSpec, KarpenterNodeClaimSpec, KarpenterNodePoolSpec } from './resources/cloud/aws/karpenterResources.js';
 import type { HelperDefinition } from './utils/helmHelpers.js';
 import type { PolicyEngine } from './policy/index.js';
+/**
+ * Rutter class with modular architecture
+ * Provides a clean API while delegating to specialized resource providers
+ * Maintains full backward compatibility with the original Rutter class
+ *
+ * @since 2.8.0+
+ */
 export declare class Rutter {
     private static readonly HELPER_NAME;
-    private readonly app;
     private readonly assets;
     private readonly awsResources;
     private readonly chart;
@@ -21,13 +27,168 @@ export declare class Rutter {
     private readonly props;
     private readonly logger;
     constructor(props: RutterProps);
+    /**
+     * Creates an AWS EBS StorageClass
+     * @param spec - EBS StorageClass specification
+     * @returns Created StorageClass ApiObject
+     *
+     * @example
+     * ```typescript
+     * rutter.addAWSEBSStorageClass({
+     *   name: 'fast-ebs',
+     *   volumeType: 'gp3',
+     *   encrypted: true,
+     *   allowVolumeExpansion: true
+     * });
+     * ```
+     *
+     * @since 2.8.0+
+     */
     addAWSEBSStorageClass(spec: AWSEBSStorageClassSpec): ApiObject;
+    /**
+     * Creates an AWS EFS StorageClass
+     * @param spec - EFS StorageClass specification
+     * @returns Created StorageClass ApiObject
+     *
+     * @example
+     * ```typescript
+     * rutter.addAWSEFSStorageClass({
+     *   name: 'efs-storage',
+     *   fileSystemId: 'fs-12345678',
+     *   directoryPerms: '0755'
+     * });
+     * ```
+     *
+     * @since 2.8.0+
+     */
     addAWSEFSStorageClass(spec: AWSEFSStorageClassSpec): ApiObject;
+    /**
+     * Creates an AWS IRSA ServiceAccount
+     * @param spec - IRSA ServiceAccount specification
+     * @returns Created cdk8s-plus ServiceAccount
+     *
+     * @example
+     * ```typescript
+     * rutter.addAWSIRSAServiceAccount({
+     *   name: 'my-service-account',
+     *   roleArn: 'arn:aws:iam::ACCOUNT_ID:role/MyRole'
+     * });
+     * ```
+     *
+     * @since 2.8.0+
+     */
     addAWSIRSAServiceAccount(spec: AWSIRSAServiceAccountSpec): ServiceAccount;
+    /**
+     * Creates an AWS ALB Ingress
+     * @param spec - ALB Ingress specification
+     * @returns Created cdk8s-plus Ingress
+     *
+     * @example
+     * ```typescript
+     * rutter.addAWSALBIngress({
+     *   name: 'web-ingress',
+     *   rules: [{
+     *     paths: [{
+     *       path: '/',
+     *       pathType: 'Prefix',
+     *       backend: { service: { name: 'web-service', port: { number: 80 } } }
+     *     }]
+     *   }],
+     *   scheme: 'internet-facing'
+     * });
+     * ```
+     *
+     * @since 2.8.0+
+     */
     addAWSALBIngress(spec: AWSALBIngressSpec): Ingress;
+    /**
+     * Creates a Karpenter NodePool resource
+     * @param spec - NodePool specification
+     * @returns Created NodePool ApiObject
+     *
+     * @example
+     * ```typescript
+     * rutter.addKarpenterNodePool({
+     *   name: 'default-nodepool',
+     *   template: {
+     *     spec: {
+     *       nodeClassRef: {
+     *         apiVersion: 'karpenter.k8s.aws/v1beta1',
+     *         kind: 'EC2NodeClass',
+     *         name: 'default'
+     *       }
+     *     }
+     *   }
+     * });
+     * ```
+     *
+     * @since 2.8.0+
+     */
     addKarpenterNodePool(spec: KarpenterNodePoolSpec): ApiObject;
+    /**
+     * Creates a Karpenter NodeClaim resource
+     * @param spec - NodeClaim specification
+     * @returns Created NodeClaim ApiObject
+     *
+     * @example
+     * ```typescript
+     * rutter.addKarpenterNodeClaim({
+     *   name: 'my-node-claim',
+     *   nodeClassRef: {
+     *     apiVersion: 'karpenter.k8s.aws/v1beta1',
+     *     kind: 'EC2NodeClass',
+     *     name: 'default'
+     *   }
+     * });
+     * ```
+     *
+     * @since 2.8.0+
+     */
     addKarpenterNodeClaim(spec: KarpenterNodeClaimSpec): ApiObject;
+    /**
+     * Creates a Karpenter EC2NodeClass resource
+     * @param spec - EC2NodeClass specification
+     * @returns Created EC2NodeClass ApiObject
+     *
+     * @example
+     * ```typescript
+     * rutter.addKarpenterEC2NodeClass({
+     *   name: 'default',
+     *   amiFamily: 'AL2',
+     *   subnetSelectorTerms: [{ tags: { 'karpenter.sh/discovery': 'my-cluster' } }],
+     *   securityGroupSelectorTerms: [{ tags: { 'karpenter.sh/discovery': 'my-cluster' } }]
+     * });
+     * ```
+     *
+     * @since 2.8.0+
+     */
     addKarpenterEC2NodeClass(spec: KarpenterEC2NodeClassSpec): ApiObject;
+    /**
+     * Creates a Karpenter NodePool with optimized disruption settings for cost efficiency
+     * @param spec - NodePool specification with disruption optimization
+     * @returns Created NodePool ApiObject
+     *
+     * @example
+     * ```typescript
+     * rutter.addKarpenterNodePoolWithDisruption({
+     *   name: 'cost-optimized',
+     *   nodeClassRef: {
+     *     apiVersion: 'karpenter.k8s.aws/v1beta1',
+     *     kind: 'EC2NodeClass',
+     *     name: 'default'
+     *   },
+     *   consolidationPolicy: 'WhenEmptyOrUnderutilized',
+     *   consolidateAfter: '30s',
+     *   expireAfter: '24h',
+     *   disruptionBudgets: [
+     *     { nodes: '20%' },
+     *     { nodes: '0', schedule: '0 9 * * 1-5', duration: '8h' }
+     *   ]
+     * });
+     * ```
+     *
+     * @since 2.8.0+
+     */
     addKarpenterNodePoolWithDisruption(spec: {
         name: string;
         nodeClassRef: {
@@ -53,6 +214,33 @@ export declare class Rutter {
         labels?: Record<string, string>;
         annotations?: Record<string, string>;
     }): ApiObject;
+    /**
+     * Creates a Karpenter NodePool with scheduling constraints and priorities
+     * @param spec - NodePool specification with scheduling optimization
+     * @returns Created NodePool ApiObject
+     *
+     * @example
+     * ```typescript
+     * rutter.addKarpenterNodePoolWithScheduling({
+     *   name: 'gpu-workloads',
+     *   nodeClassRef: {
+     *     apiVersion: 'karpenter.k8s.aws/v1beta1',
+     *     kind: 'EC2NodeClass',
+     *     name: 'gpu-nodeclass'
+     *   },
+     *   requirements: [
+     *     { key: 'node.kubernetes.io/instance-type', operator: 'In', values: ['g4dn.xlarge', 'g4dn.2xlarge'] }
+     *   ],
+     *   taints: [
+     *     { key: 'nvidia.com/gpu', effect: 'NoSchedule' }
+     *   ],
+     *   terminationGracePeriod: '60s',
+     *   weight: 100
+     * });
+     * ```
+     *
+     * @since 2.8.0+
+     */
     addKarpenterNodePoolWithScheduling(spec: {
         name: string;
         nodeClassRef: {
@@ -81,49 +269,239 @@ export declare class Rutter {
         labels?: Record<string, string>;
         annotations?: Record<string, string>;
     }): ApiObject;
+    /**
+     * Creates a ServiceAccount with ECR access annotations
+     * @param spec - ECR ServiceAccount specification
+     * @returns Created cdk8s-plus ServiceAccount
+     *
+     * @example
+     * ```typescript
+     * rutter.addAWSECRServiceAccount({
+     *   name: 'ecr-service-account',
+     *   roleArn: 'arn:aws:iam::ACCOUNT_ID:role/ECRAccessRole'
+     * });
+     * ```
+     *
+     * @since 2.8.0+
+     */
     addAWSECRServiceAccount(spec: AWSECRServiceAccountSpec): ServiceAccount;
-    addManifest(yamlOrObject: string | Record<string, unknown>, id: string): ApiObject;
+    /**
+     * Adds an object-form Kubernetes manifest as a cdk8s ApiObject.
+     *
+     * Prefer native cdk8s/cdk8s-plus constructs attached to `getChart()` whenever an
+     * upstream typed construct exists. Use this object form primarily for CRDs or
+     * custom resources that do not yet have a suitable typed construct.
+     *
+     * @param yamlOrObject - Kubernetes manifest object, or deprecated raw YAML input
+     * @param id - Unique construct identifier
+     * @since 2.8.0+
+     */
+    addManifest(manifestObject: Record<string, unknown>, id: string): ApiObject;
+    /**
+     * @deprecated Raw YAML bypasses TypeScript resource typing. Prefer cdk8s/cdk8s-plus
+     * constructs through `getChart()` or pass a typed object to `addManifest()`.
+     */
+    addManifest(yaml: string, id: string): ApiObject;
+    /**
+     * Adds a template manifest to the chart with custom YAML content that preserves Helm expressions.
+     * This method allows you to provide raw YAML with Helm templates without serialization issues.
+     *
+     * @param yamlTemplate - The YAML template string with Helm expressions
+     * @param id - Unique identifier for the manifest
+     * @returns A compatibility placeholder that is excluded from synthesized output
+     * @deprecated Raw YAML templates bypass TypeScript resource typing. Prefer typed
+     * cdk8s/cdk8s-plus constructs through `getChart()` and ValuesRef for Helm values.
+     * This method is planned for removal in the next major release.
+     */
     addTemplateManifest(yamlTemplate: string, id: string): ApiObject;
+    /**
+     * Adds a Kubernetes manifest wrapped in a Helm conditional using programmatic template generation
+     *
+     * This method creates a manifest that will only be rendered if the specified
+     * condition evaluates to true. The condition is checked against .Values in Helm.
+     *
+     * **Key improvements in v2.9.2:**
+     * - Uses programmatic Helm template generation instead of JavaScript interpolation
+     * - Eliminates Handlebars dependency for conditional manifests
+     * - Leverages the include() function from helm.ts for proper Helm syntax
+     * - Provides better type safety and eliminates double interpolation issues
+     * - Maintains backward compatibility with existing condition syntax
+     *
+     * @param manifestObject - JavaScript object representing the Kubernetes manifest
+     * @param condition - Helm condition path (e.g., 'enabled', 'feature.enabled')
+     *                   Can also be a full Helm expression like '{{ .Values.enabled }}'
+     * @param id - Unique identifier for the manifest
+     * @returns ApiObject instance for CDK8S compatibility
+     *
+     * @example
+     * ```typescript
+     * // Simple boolean condition
+     * rutter.addConditionalManifest(
+     *   {
+     *     apiVersion: 'v1',
+     *     kind: 'Namespace',
+     *     metadata: { name: 'my-namespace' }
+     *   },
+     *   'createNamespace',
+     *   'namespace'
+     * );
+     *
+     * // Nested condition with complex logic
+     * rutter.addConditionalManifest(
+     *   {
+     *     apiVersion: 'v1',
+     *     kind: 'ConfigMap',
+     *     metadata: { name: 'app-config' },
+     *     data: {
+     *       config: '{{ .Values.config }}',
+     *       environment: '{{ .Values.environment }}'
+     *     }
+     *   },
+     *   'features.configMap.enabled',
+     *   'app-config'
+     * );
+     * ```
+     *
+     * @throws {Error} When condition is invalid or manifest structure is malformed
+     * @since 2.8.4
+     * @since 2.9.2 Enhanced with programmatic Helm template generation for better reliability
+     */
     addConditionalManifest(manifestObject: Record<string, unknown>, condition: string, id: string): ApiObject;
+    /**
+     * Validates the structure of a Kubernetes manifest object
+     * @param manifest - The manifest object to validate
+     * @private
+     * @since 2.8.0+
+     */
     private validateManifestStructure;
+    /**
+     * Returns stable logical identifiers for all synthesized ApiObjects, including
+     * those nested inside cdk8s-plus resources.
+     */
+    private getSynthesizedApiObjectIds;
+    /**
+     * Returns the underlying cdk8s Chart so consumers can attach fully typed
+     * cdk8s/cdk8s-plus constructs directly to Timonel's synthesis tree.
+     *
+     * @returns The cdk8s Chart owned by this Rutter instance
+     */
+    getChart(): Chart;
+    /**
+     * Gets chart metadata
+     * @returns Chart metadata
+     *
+     * @since 2.8.0+
+     */
     getMeta(): ChartMetadata;
+    /**
+     * Gets default values
+     * @returns Default values object
+     *
+     * @since 1.0.0
+     */
     getDefaultValues(): Record<string, unknown>;
+    /**
+     * Gets environment-specific values
+     * @returns Environment values object
+     *
+     * @since 1.0.0
+     */
     getEnvValues(): Record<string, Record<string, unknown>>;
+    /**
+     * Gets all assets (CRDs, etc.)
+     * @returns Array of assets
+     *
+     * @since 1.0.0
+     */
     getAssets(): Array<{
         id: string;
         yaml: string;
         target: string;
     }>;
+    /**
+     * Converts the chart to SynthAsset array for HelmChartWriter
+     * @returns Array of synthesized assets
+     *
+     * @since 2.8.0+
+     */
     toSynthArray(): Promise<SynthAsset[]>;
+    /**
+     * Synchronous version of toSynthArray for backward compatibility
+     * @returns Array of synthesized assets
+     * @deprecated Use toSynthArray() instead for proper async handling
+     * @since 2.8.0+
+     */
     toSynthArraySync(): SynthAsset[];
+    /**
+     * Formats policy validation errors into a readable error message
+     * @param result - Policy validation result
+     * @returns Formatted error message
+     * @private
+     */
     private formatPolicyErrors;
+    /**
+     * Writes the Helm chart to the specified output directory
+     * @param outDir - Output directory path
+     *
+     * @since 1.0.0
+     */
     write(outDir: string): Promise<void>;
 }
+/**
+ * Helm chart metadata accepted by `Rutter`.
+ *
+ * `name` and `version` are required because they are emitted into `Chart.yaml`.
+ */
 export interface ChartMetadata {
+    /** Human-readable Helm chart description. */
     description?: string;
+    /** Project or product home page URL. */
     home?: string;
+    /** Search keywords emitted into chart metadata. */
     keywords?: string[];
+    /** Helm chart maintainer records. */
     maintainers?: Array<{
         email?: string;
         name: string;
         url?: string;
     }>;
+    /** Helm chart name. */
     name: string;
+    /** Source repository or documentation URLs. */
     sources?: string[];
+    /** Helm chart semantic version. */
     version: string;
 }
+/**
+ * Configuration for a `Rutter` chart.
+ */
 export interface RutterProps {
+    /** Additional cdk8s Chart properties applied to the generated chart. */
     chartProps?: ChartProps;
+    /** Cloud provider for default helpers. */
     cloudProvider?: 'aws';
+    /** Default values emitted to `values.yaml`. */
     defaultValues?: Record<string, unknown>;
+    /** Environment-specific values emitted to `values-<environment>.yaml`. */
     envValues?: Record<string, Record<string, unknown>>;
+    /** Custom Helm helpers content or definitions. */
     helpersTpl?: string | HelperDefinition[];
+    /** Custom prefix for manifest files. */
     manifestPrefix?: string;
+    /** Required Helm chart metadata. */
     meta: ChartMetadata;
+    /** Optional default namespace for the underlying cdk8s Chart. */
     namespace?: string;
+    /** Optional policy engine for manifest validation. */
     policyEngine?: PolicyEngine;
+    /** Optional caller-owned construct scope used as the parent of Timonel's cdk8s Chart. */
     scope?: Construct;
+    /** Combine all resources into a single manifest file. */
     singleManifestFile?: boolean;
+    /**
+     * Custom logger instance.
+     * @since 2.13.0
+     */
     logger?: TimonelLogger;
 }
 export type { AWSALBIngressSpec, AWSEBSStorageClassSpec, AWSEFSStorageClassSpec, AWSIRSAServiceAccountSpec, } from './resources/cloud/aws/awsResources.js';