timonel 0.3.0 → 1.0.0

package/CHANGELOG.md

@@ -1,3 +1,36 @@
+# [1.0.0](https://github.com/KenkoGeek/timonel/compare/v0.4.0...v1.0.0) (2025-09-07)
+
+
+### Bug Fixes
+
+* **ci:** configure GitHub App token for semantic-release bypass - Use RELEASE_TOKEN from npm-prd environment for checkout and semantic-release ([0d385d1](https://github.com/KenkoGeek/timonel/commit/0d385d1084a45de3ab731094e87196239811e6fb))
+* **ci:** disable body-max-line-length for semantic-release compatibility  - Set body-max-line-length to 0 (disabled) to allow long changelog entries - Fixes semantic-release commit validation failures - Maintains other commitlint rules for developer commits ([b215f65](https://github.com/KenkoGeek/timonel/commit/b215f65bccb69a1cfca79084e6a9c96954fb478a))
+* **ci:** disable footer line length limit for semantic-release commits ([d5ae4dc](https://github.com/KenkoGeek/timonel/commit/d5ae4dc83e68f8fade4a8289d1ce4e2bae5046dd))
+* **ci:** disable footer-leading-blank for semantic-release compatibility  - Set footer-leading-blank to 0 (disabled) to allow semantic-release footer format ([2f8c6c8](https://github.com/KenkoGeek/timonel/commit/2f8c6c863c6aabd1d3f3d8022b43fefecb02f010))
+* **ci:** replace CodeQL with security check in release validation ([#15](https://github.com/KenkoGeek/timonel/issues/15)) ([b8cecea](https://github.com/KenkoGeek/timonel/commit/b8cecea1eaf0bb6af3e6fd2f6bc38c2fb2c09f4d))
+* **ci:** resolve release workflow issues ([#16](https://github.com/KenkoGeek/timonel/issues/16)) ([ed5dc9b](https://github.com/KenkoGeek/timonel/commit/ed5dc9b3d86b531d4495d4d05dd913340333322c))
+
+
+### Features
+
+* add manual release workflow with GitHub Actions ([1035b2e](https://github.com/KenkoGeek/timonel/commit/1035b2e18fbb808e57438353c865ecd129d9e04d))
+* add NetworkPolicy helpers for Zero Trust network security ([#13](https://github.com/KenkoGeek/timonel/issues/13)) ([cee3b58](https://github.com/KenkoGeek/timonel/commit/cee3b5876de839ca3cf16dd6ca6e3b76626392ce))
+* **ci:** add required status checks validation to release workflow ([#14](https://github.com/KenkoGeek/timonel/issues/14)) ([7f8665f](https://github.com/KenkoGeek/timonel/commit/7f8665fa908215cc92a4dbefb7fec00de98464bb))
+* **ci:** implement automated semantic release with conventional commits ([02ce189](https://github.com/KenkoGeek/timonel/commit/02ce18943efd8019168b5f9af29be0140a9e1524))
+* **ci:** implement automated semantic release with conventional commits ([bb94fda](https://github.com/KenkoGeek/timonel/commit/bb94fda3e80bf3e010e7b53bdd1794f88060408a))
+* **core:** add NetworkPolicy helpers for Zero Trust network security ([34ac6bd](https://github.com/KenkoGeek/timonel/commit/34ac6bda3956e5fe326b72e9831bd4bb8bc660da))
+
+
+### Performance Improvements
+
+* **ci:** homogenize CI/CD workflows and optimize release pipeline ([#17](https://github.com/KenkoGeek/timonel/issues/17)) ([4622d11](https://github.com/KenkoGeek/timonel/commit/4622d113e5753a5ff69c82a1e3784ecf61c34689))
+
+
+### BREAKING CHANGES
+
+* **ci:** ESLint configuration migrated to flat config format
+* **ci:** ESLint configuration migrated to flat config format
+
 # Changelog
 
 All notable changes to this project will be documented in this file.
@@ -7,6 +40,57 @@ 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)
@@ -184,5 +268,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

@@ -139,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({
@@ -150,19 +153,82 @@ 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:
@@ -224,7 +290,11 @@ tl umbrella synth ./dist
 
 The `examples/` directory contains complete working examples:
 
-- **aws-game-2048**: AWS 2048 game deployment with Service and Ingress
+- **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)
 
@@ -245,6 +315,354 @@ shared values, and multi-environment support.
   (`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',
+    },
+  ],
+});
+```
+
+## Network Security with NetworkPolicies
+
+Timonel provides comprehensive NetworkPolicy helpers for implementing Zero Trust network security
+in Kubernetes:
+
+### Zero Trust Network Security
+
+Implement defense-in-depth with deny-by-default policies:
+
+```typescript
+// 1. Deny all traffic by default (recommended starting point)
+rutter.addDenyAllNetworkPolicy('default-deny-all');
+
+// 2. Allow specific traffic as needed
+rutter.addAllowFromPodsNetworkPolicy({
+  name: 'allow-frontend-to-backend',
+  targetPodSelector: { app: 'backend' },
+  sourcePodSelector: { app: 'frontend' },
+  ports: [{ protocol: 'TCP', port: 8080 }],
+});
+```
+
+### Advanced NetworkPolicy Examples
+
+#### Multi-tier Application Security
+
+```typescript
+// Web tier - allow external traffic on port 80/443
+rutter.addNetworkPolicy({
+  name: 'web-tier-policy',
+  podSelector: { matchLabels: { tier: 'web' } },
+  policyTypes: ['Ingress', 'Egress'],
+  ingress: [
+    {
+      ports: [
+        { protocol: 'TCP', port: 80 },
+        { protocol: 'TCP', port: 443 },
+      ],
+    },
+  ],
+  egress: [
+    // Allow access to app tier
+    {
+      to: [{ podSelector: { matchLabels: { tier: 'app' } } }],
+      ports: [{ protocol: 'TCP', port: 8080 }],
+    },
+    // Allow DNS resolution
+    {
+      to: [{ namespaceSelector: { matchLabels: { name: 'kube-system' } } }],
+      ports: [
+        { protocol: 'UDP', port: 53 },
+        { protocol: 'TCP', port: 53 },
+      ],
+    },
+  ],
+});
+
+// App tier - only allow traffic from web tier
+rutter.addNetworkPolicy({
+  name: 'app-tier-policy',
+  podSelector: { matchLabels: { tier: 'app' } },
+  policyTypes: ['Ingress', 'Egress'],
+  ingress: [
+    {
+      from: [{ podSelector: { matchLabels: { tier: 'web' } } }],
+      ports: [{ protocol: 'TCP', port: 8080 }],
+    },
+  ],
+  egress: [
+    // Allow access to database
+    {
+      to: [{ podSelector: { matchLabels: { tier: 'database' } } }],
+      ports: [{ protocol: 'TCP', port: 5432 }],
+    },
+    // Allow external API calls (with CIDR restrictions)
+    {
+      to: [
+        {
+          ipBlock: {
+            cidr: '0.0.0.0/0',
+            except: ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16'],
+          },
+        },
+      ],
+      ports: [{ protocol: 'TCP', port: 443 }],
+    },
+  ],
+});
+
+// Database tier - most restrictive
+rutter.addNetworkPolicy({
+  name: 'database-tier-policy',
+  podSelector: { matchLabels: { tier: 'database' } },
+  policyTypes: ['Ingress', 'Egress'],
+  ingress: [
+    {
+      from: [{ podSelector: { matchLabels: { tier: 'app' } } }],
+      ports: [{ protocol: 'TCP', port: 5432 }],
+    },
+  ],
+  egress: [
+    // Only allow DNS resolution
+    {
+      to: [{ namespaceSelector: { matchLabels: { name: 'kube-system' } } }],
+      ports: [
+        { protocol: 'UDP', port: 53 },
+        { protocol: 'TCP', port: 53 },
+      ],
+    },
+  ],
+});
+```
+
+#### Cross-Namespace Communication
+
+```typescript
+// Allow traffic from monitoring namespace
+rutter.addAllowFromNamespaceNetworkPolicy({
+  name: 'allow-monitoring',
+  targetPodSelector: { app: 'backend' },
+  sourceNamespaceSelector: { name: 'monitoring' },
+  ports: [{ protocol: 'TCP', port: 9090 }], // Prometheus metrics
+});
+
+// Allow traffic to shared services namespace
+rutter.addNetworkPolicy({
+  name: 'allow-to-shared-services',
+  podSelector: { matchLabels: { app: 'backend' } },
+  policyTypes: ['Egress'],
+  egress: [
+    {
+      to: [
+        {
+          namespaceSelector: { matchLabels: { name: 'shared-services' } },
+          podSelector: { matchLabels: { app: 'redis' } },
+        },
+      ],
+      ports: [{ protocol: 'TCP', port: 6379 }],
+    },
+  ],
+});
+```
+
+### Security Best Practices
+
+#### 1. Start with Deny-All Policies
+
+```typescript
+// Always start with deny-all for maximum security
+rutter.addDenyAllNetworkPolicy('default-deny-all');
+
+// Then add specific allow rules
+rutter.addAllowFromPodsNetworkPolicy({
+  name: 'allow-specific-communication',
+  targetPodSelector: { app: 'api' },
+  sourcePodSelector: { app: 'frontend' },
+  ports: [{ protocol: 'TCP', port: 8080 }],
+});
+```
+
+#### 2. Separate Ingress and Egress Policies
+
+```typescript
+// Separate policies for better maintainability
+rutter.addDenyAllIngressNetworkPolicy('deny-all-ingress');
+rutter.addDenyAllEgressNetworkPolicy('deny-all-egress');
+```
+
+#### 3. Use CIDR Blocks for External Access
+
+```typescript
+// Restrict external access to specific IP ranges
+rutter.addNetworkPolicy({
+  name: 'external-api-access',
+  podSelector: { matchLabels: { app: 'backend' } },
+  policyTypes: ['Egress'],
+  egress: [
+    {
+      to: [
+        {
+          ipBlock: {
+            cidr: '203.0.113.0/24', // Specific external service
+          },
+        },
+      ],
+      ports: [{ protocol: 'TCP', port: 443 }],
+    },
+  ],
+});
+```
+
+#### 4. Include DNS Resolution
+
+```typescript
+// Always allow DNS for name resolution
+const dnsEgressRule = {
+  to: [{ namespaceSelector: { matchLabels: { name: 'kube-system' } } }],
+  ports: [
+    { protocol: 'UDP', port: 53 },
+    { protocol: 'TCP', port: 53 },
+  ],
+};
+
+rutter.addNetworkPolicy({
+  name: 'app-with-dns',
+  podSelector: { matchLabels: { app: 'backend' } },
+  policyTypes: ['Egress'],
+  egress: [dnsEgressRule /* other rules */],
+});
+```
+
+### Basic NetworkPolicy
+
+```typescript
+// Custom NetworkPolicy with full control
+rutter.addNetworkPolicy({
+  name: 'custom-policy',
+  podSelector: { matchLabels: { app: 'backend' } },
+  policyTypes: ['Ingress', 'Egress'],
+  ingress: [
+    {
+      from: [{ podSelector: { matchLabels: { app: 'frontend' } } }],
+      ports: [{ protocol: 'TCP', port: 8080 }],
+    },
+  ],
+  egress: [
+    {
+      to: [{ podSelector: { matchLabels: { app: 'database' } } }],
+      ports: [{ protocol: 'TCP', port: 5432 }],
+    },
+  ],
+});
+```
+
 ## Multi-environment values
 
 Provide `envValues` in the `Rutter` constructor to automatically create
@@ -270,9 +688,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