timonel 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,85 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2025-09-06
+
+### Added (0.4.0)
+
+- **Custom Manifest Naming**: Complete implementation for customizable Kubernetes
+  manifest file names
+  - `manifestName` option in RutterProps to specify custom base names for manifest
+    files
+  - `singleManifestFile` option to combine all resources into a single manifest
+    file
+  - Enhanced file organization with descriptive names instead of generic numbered
+    files
+  - Support for both single file mode (`application.yaml`) and separate files mode
+    (`0000-my-app-deployment-web.yaml`)
+  - Backward compatibility maintained - default behavior unchanged when options not
+    specified
+
+### Enhanced (0.4.0)
+
+- **HelmChartWriter**: Added `singleFile` property to SynthAsset interface for
+  improved file handling
+- **Documentation**: Comprehensive Custom Manifest Naming section added to README
+  with examples
+- **Examples**: All examples updated with custom manifest naming demonstrations
+  - **AWS 2048 Game**: Enhanced with production-ready AWS features
+    - AWS ALB Ingress with health checks and SSL support
+    - HorizontalPodAutoscaler (HPA) for CPU-based auto-scaling
+    - PodDisruptionBudget (PDB) for high availability during updates
+    - Custom manifest naming with `manifestName: 'game-2048'`
+    - Multi-environment configuration (dev/staging/prod)
+  - **WordPress**: Updated to showcase `manifestName: 'wordpress-app'` and `singleManifestFile: true`
+    - Comprehensive AWS integration examples (EBS, EFS, IRSA, Secrets Manager)
+    - Auto-scaling with HPA and VPA configurations
+    - Production-ready deployment patterns
+  - **WordPress Umbrella**: Subcharts updated with custom manifest naming
+    - MySQL subchart: `manifestName: 'mysql-database'`, `singleManifestFile: true`
+    - WordPress subchart: `manifestName: 'wordpress-app'`, `singleManifestFile: false`
+- **Example Documentation**: All example READMEs enhanced with custom manifest naming references
+  and comprehensive deployment instructions
+- **Auto-scaling Features**: Properly documented existing production-ready capabilities
+  - HorizontalPodAutoscaler (HPA) with CPU/memory metrics and custom behavior policies
+  - VerticalPodAutoscaler (VPA) with resource policies and update modes
+  - PodDisruptionBudget (PDB) for high availability during updates
+- **AWS Multi-Cloud Support**: Comprehensive documentation of EKS integration features
+  - AWS IRSA ServiceAccount for secure IAM role assumption with regional STS endpoints
+  - AWS EBS StorageClass with GP3, IO1, IO2 support, encryption, and IOPS configuration
+  - AWS EFS StorageClass for shared storage across pods with access points
+  - AWS ALB Ingress with health checks, SSL certificates, and advanced routing
+  - AWS Secrets Manager and Parameter Store integration via SecretProviderClass
+  - Multi-cloud ServiceAccount with workload identity (AWS IRSA, Azure, GCP)
+
+## [0.3.0] - 2025-09-02
+
+### Added (0.3.0)
+
+- **Umbrella Charts Support**: Complete implementation for managing multiple subcharts
+  - `UmbrellaRutter` class for coordinating multiple Rutter instances
+  - `createUmbrella()` helper function for easy umbrella chart creation
+  - CLI commands: `tl umbrella init`, `tl umbrella add`, `tl umbrella synth`
+  - Automatic Chart.yaml generation with dependencies
+  - Support for environment-specific values in umbrella charts
+  - Example templates for umbrella and subchart scaffolding
+- **WordPress Umbrella Example**: Complete example separating MySQL and WordPress into subcharts
+  - MySQL subchart with persistent storage and secrets
+  - WordPress subchart with database connectivity
+  - Multi-environment configuration (dev/prod)
+  - Comprehensive documentation and deployment guide
+
+### Changed (0.3.0)
+
+- Updated CLI usage to include umbrella chart commands
+- Enhanced example generation with subchart support
+
+### Removed
+
+- **BREAKING**: Removed unused `cdk8s-plus-28` dependency
+  - Project uses `ApiObject` directly for better control
+  - No impact on functionality, only dependency cleanup
+
 ## [0.2.1] - 2025-09-02
 
 ### Fixed
@@ -156,5 +235,16 @@ const rutter = new Rutter({ meta: { name: 'my-app' } });
 - Security audit in CI/CD pipeline
 - Provenance-enabled npm publishing
 
-[Unreleased]: https://github.com/KenkoGeek/timonel/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/KenkoGeek/timonel/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/KenkoGeek/timonel/releases/tag/v0.4.0
+[0.3.0]: https://github.com/KenkoGeek/timonel/releases/tag/v0.3.0
+[0.2.1]: https://github.com/KenkoGeek/timonel/releases/tag/v0.2.1
+[0.2.0]: https://github.com/KenkoGeek/timonel/releases/tag/v0.2.0
+[0.1.7]: https://github.com/KenkoGeek/timonel/releases/tag/v0.1.7
+[0.1.6]: https://github.com/KenkoGeek/timonel/releases/tag/v0.1.6
+[0.1.5]: https://github.com/KenkoGeek/timonel/releases/tag/v0.1.5
+[0.1.4]: https://github.com/KenkoGeek/timonel/releases/tag/v0.1.4
+[0.1.3]: https://github.com/KenkoGeek/timonel/releases/tag/v0.1.3
+[0.1.2]: https://github.com/KenkoGeek/timonel/releases/tag/v0.1.2
+[0.1.1]: https://github.com/KenkoGeek/timonel/releases/tag/v0.1.1
 [0.1.0]: https://github.com/KenkoGeek/timonel/releases/tag/v0.1.0

package/README.md

@@ -20,11 +20,13 @@ Key features:
 - Type-safe API (strict TypeScript) with cdk8s constructs.
 - Helm templating helpers to embed `{{ .Values.* }}` where needed.
 - Simple multi-environment setup: `values.yaml`, `values-dev.yaml`, `values-prod.yaml`, etc.
+- **Umbrella Charts**: Manage multiple subcharts as a single deployable unit.
 - Minimal CLI (`tl`) to scaffold an example and synthesize the chart.
 
 Advanced templating:
 
 - Programmatic Helm helpers: generate `templates/_helpers.tpl` and call helpers using `template()`/`include()`.
+- Umbrella chart support with automatic dependency management.
 
 ## Installation
 
@@ -137,6 +139,9 @@ const rutter = new Rutter({
       body: `{{- printf "%s-%s" .Chart.Name .Release.Name | trunc 63 | trimSuffix "-" -}}`,
     },
   ],
+  // Custom manifest naming options
+  manifestName: 'my-app-resources', // Custom name for manifest files
+  singleManifestFile: true, // Combine all resources into one file
 });
 
 rutter.addDeployment({
@@ -148,28 +153,159 @@ rutter.addDeployment({
 
 rutter.addService({ name: 'my-app', port: 80 });
 
-// Use a named helper in annotations (example)
-rutter.addDeployment({
-  name: 'annotated',
-  image: 'nginx',
-  containerPort: 80,
-  env: {
-    FULLNAME: include('timonel.fullname'),
-  },
+// Add auto-scaling with HPA and VPA
+rutter.addHorizontalPodAutoscaler({
+  name: 'my-app-hpa',
+  scaleTargetRef: { apiVersion: 'apps/v1', kind: 'Deployment', name: 'my-app' },
+  minReplicas: 1,
+  maxReplicas: 10,
+});
+
+rutter.addVerticalPodAutoscaler({
+  name: 'my-app-vpa',
+  targetRef: { apiVersion: 'apps/v1', kind: 'Deployment', name: 'my-app' },
+  updatePolicy: { updateMode: 'Auto' },
+});
+
+rutter.addPodDisruptionBudget({
+  name: 'my-app-pdb',
+  minAvailable: 1,
+  selector: { matchLabels: { app: 'my-app' } },
+});
+
+// Add IRSA ServiceAccount for AWS access
+rutter.addAWSIRSAServiceAccount({
+  name: 'my-app-irsa',
+  roleArn: 'arn:aws:iam::123456789012:role/MyAppRole',
+  stsEndpointType: 'regional',
+  tokenExpiration: 3600,
 });
 
 rutter.write('dist/charts/my-app');
 ```
 
+### Custom Manifest Naming
+
+Timonel provides flexible options for naming your Kubernetes manifest files:
+
+#### Single Manifest File
+
+```typescript
+const rutter = new Rutter({
+  meta: { name: 'my-app', version: '0.1.0' },
+  manifestName: 'application',
+  singleManifestFile: true, // All resources in one file
+});
+
+// Generates: templates/application.yaml
+```
+
+#### Separate Files with Custom Names
+
+```typescript
+const rutter = new Rutter({
+  meta: { name: 'my-app', version: '0.1.0' },
+  manifestName: 'my-app',
+  singleManifestFile: false, // Each resource in its own file (default)
+});
+
+// Generates:
+// templates/0000-my-app-deployment-web.yaml
+// templates/0001-my-app-service-web.yaml
+// templates/0002-my-app-configmap-config.yaml
+```
+
+#### Default Behavior
+
+```typescript
+const rutter = new Rutter({
+  meta: { name: 'my-app', version: '0.1.0' },
+  // No manifestName specified
+});
+
+// Generates:
+// templates/0000-deployment-web.yaml
+// templates/0001-service-web.yaml
+// templates/0002-configmap-config.yaml
+```
+
+## Umbrella Charts
+
+Create umbrella charts that combine multiple subcharts into a single deployable unit:
+
+```typescript
+import { createUmbrella, Rutter } from 'timonel';
+
+// Create individual subcharts
+const mysql = new Rutter({
+  meta: { name: 'mysql', version: '0.1.0' },
+  // MySQL configuration...
+});
+
+const wordpress = new Rutter({
+  meta: { name: 'wordpress', version: '0.1.0' },
+  // WordPress configuration...
+});
+
+// Combine into umbrella chart
+const umbrella = createUmbrella({
+  meta: {
+    name: 'wordpress-stack',
+    version: '1.0.0',
+    description: 'Complete WordPress stack with MySQL database',
+  },
+  subcharts: [
+    { name: 'mysql', rutter: mysql },
+    { name: 'wordpress', rutter: wordpress },
+  ],
+  defaultValues: {
+    global: { storageClass: 'gp2' },
+    mysql: { persistence: { size: '8Gi' } },
+    wordpress: { service: { type: 'LoadBalancer' } },
+  },
+  envValues: {
+    dev: { mysql: { persistence: { size: '5Gi' } } },
+    prod: { mysql: { persistence: { size: '20Gi' } } },
+  },
+});
+
+umbrella.write('dist/wordpress-stack');
+```
+
+### CLI for Umbrella Charts
+
+```bash
+# Create umbrella structure
+tl umbrella init my-stack
+
+# Add subcharts
+tl umbrella add database
+tl umbrella add frontend
+
+# Generate umbrella chart
+tl umbrella synth ./dist
+```
+
 ## Examples
 
 The `examples/` directory contains complete working examples:
 
-- **aws-game-2048**: AWS 2048 game deployment with Service and Ingress
-- **wordpress**: WordPress with MySQL database setup
+- **aws-game-2048**: Production-ready AWS 2048 game deployment showcasing AWS-specific features
+  - AWS ALB Ingress with health checks and SSL support
+  - HorizontalPodAutoscaler (HPA) for automatic scaling based on CPU utilization
+  - PodDisruptionBudget (PDB) for high availability during updates
+  - Multi-environment configuration (dev/staging/prod)
+- **wordpress**: WordPress with MySQL database setup (single chart)
+- **wordpress-umbrella**: WordPress stack using umbrella charts (MySQL + WordPress subcharts)
 
 Each example includes its own README with deployment instructions.
 
+### Umbrella Chart Example
+
+See `examples/wordpress-umbrella/` for a complete umbrella chart implementation that
+separates MySQL and WordPress into individual subcharts with proper dependencies,
+shared values, and multi-environment support.
+
 - `valuesRef(path)`: returns a Helm placeholder string for `.Values.*`.
 - You can pass these strings directly into cdk8s constructs; they are preserved in the YAML.
 - `template(name, ctx='.')` and `include(name, ctx='.')`: inject calls to helpers defined in `_helpers.tpl`.
@@ -179,6 +315,120 @@ Each example includes its own README with deployment instructions.
   (`toString`, `float64`).
 - For numeric fields (ports, replicas), use literal values or template strings with proper casting.
 
+## AWS Multi-Cloud Support
+
+Timonel provides comprehensive AWS-specific helpers for EKS deployments:
+
+### IRSA (IAM Roles for Service Accounts)
+
+Securely access AWS services from Kubernetes pods using IAM roles:
+
+```typescript
+// Dedicated IRSA ServiceAccount
+rutter.addAWSIRSAServiceAccount({
+  name: 'app-s3-access',
+  roleArn: 'arn:aws:iam::123456789012:role/AppS3Role',
+  audience: 'sts.amazonaws.com', // optional, defaults to sts.amazonaws.com
+  stsEndpointType: 'regional', // recommended for better performance
+  tokenExpiration: 3600, // optional, token lifetime in seconds
+});
+
+// General ServiceAccount with IRSA support
+rutter.addServiceAccount({
+  name: 'my-app-sa',
+  awsRoleArn: 'arn:aws:iam::123456789012:role/MyAppRole',
+  awsStsEndpointType: 'regional',
+  awsTokenExpiration: 7200,
+  automountServiceAccountToken: true,
+});
+```
+
+### AWS Storage Classes
+
+```typescript
+// EBS GP3 StorageClass
+rutter.addAWSEBSStorageClass({
+  name: 'fast-ssd',
+  volumeType: 'gp3',
+  encrypted: true,
+  iops: 3000,
+  throughput: 125,
+});
+
+// EFS StorageClass for shared storage
+rutter.addAWSEFSStorageClass({
+  name: 'shared-storage',
+  reclaimPolicy: 'Retain',
+});
+```
+
+### AWS Load Balancer Controller
+
+```typescript
+// ALB Ingress with health checks
+rutter.addAWSALBIngress({
+  name: 'app-ingress',
+  scheme: 'internet-facing',
+  targetType: 'ip',
+  healthCheckPath: '/health',
+  certificateArn:
+    'arn:aws:acm:us-west-2:123456789012:certificate/12345678-1234-1234-1234-123456789012',
+  rules: [
+    {
+      paths: [
+        {
+          path: '/',
+          pathType: 'Prefix',
+          backend: { service: { name: 'my-app', port: { number: 80 } } },
+        },
+      ],
+    },
+  ],
+});
+```
+
+### AWS Secrets Manager and Parameter Store
+
+Integrate with AWS Secrets Manager and Parameter Store using the Secrets Store CSI Driver:
+
+```typescript
+// Secrets Manager integration
+rutter.addAWSSecretProviderClass({
+  name: 'app-secrets',
+  region: 'us-west-2',
+  objects: [
+    {
+      objectName: 'prod/myapp/database',
+      objectType: 'secretsmanager',
+      objectAlias: 'db-credentials',
+    },
+    {
+      objectName: 'prod/myapp/api-keys',
+      objectType: 'secretsmanager',
+      jmesPath: '["api_key", "secret_key"]', // Extract specific keys from JSON
+    },
+  ],
+});
+
+// Parameter Store integration
+rutter.addAWSSecretProviderClass({
+  name: 'app-config',
+  region: 'us-west-2',
+  objects: [
+    {
+      objectName: '/myapp/config/debug-mode',
+      objectType: 'ssmparameter',
+      objectAlias: 'debug-flag',
+    },
+    {
+      objectName: '/myapp/config/cache-ttl',
+      objectType: 'ssmparameter',
+      objectAlias: 'cache-timeout',
+    },
+  ],
+});
+```
+
 ## Multi-environment values
 
 Provide `envValues` in the `Rutter` constructor to automatically create
@@ -204,9 +454,12 @@ Provide `envValues` in the `Rutter` constructor to automatically create
 
 ## Roadmap
 
-- Helpers for common patterns (HPA, auto-scaling)
+- ✅ Auto-scaling helpers (HPA, VPA, PodDisruptionBudget)
+- ✅ AWS multi-cloud support (EBS, EFS, ALB, IRSA, Secrets Manager, Parameter Store)
+- ✅ Custom manifest naming and file organization
+- Azure multi-cloud support (AKS-specific helpers)
+- GCP multi-cloud support (GKE-specific helpers)
 - Richer CLI (resource generators, diff)
-- Enhanced multi-cloud support
 - Template validation and testing utilities
 
 ## Contributing