feat: implement GitHub issue #80 ephemeral password support with for_each

[lgallard]

Summary

This PR addresses GitHub issue #80 by providing comprehensive ephemeral password support for users who want to use ephemeral "random_password" resources with for_each patterns.

Problem Statement

Users wanted to use ephemeral random passwords with for_each patterns like this:

ephemeral "random_password" "db_passwords" {
  for_each = var.db_users
  # Generate passwords for multiple users
}

module "db_users_secrets_manager" {
  source = "lgallard/secrets-manager/aws"
  ephemeral = true
  rotate_secrets = {
    for username, role in var.db_users : "db-${var.name}-${username}" => {
      password = ephemeral.random_password.db_passwords[username].result
    }
  }
}

However, this pattern fails due to Terraform core architectural limitations:

• Module variables cannot accept ephemeral values unless marked ephemeral = true
• When a variable is marked ephemeral = true, the entire variable becomes ephemeral
• Ephemeral values cannot be used with for_each (Terraform needs persistent resource keys)

Solution Provided

✅ Working Alternative: Direct AWS resources approach that provides the same security benefits
✅ Version Fix: Updated minimum Terraform version to >= 1.11.0 for ephemeral support
✅ Comprehensive Examples: Added complete working patterns and documentation
✅ Security Validated: End-to-end testing confirms no sensitive data in Terraform state

Changes Made

1. Core Module Updates

• versions.tf: Updated minimum Terraform version from >= v0.15.0 to >= 1.11.0

2. New Examples and Documentation

• examples/ephemeral/ephemeral-for-each-example.tf: Complete working solution for the user's pattern
• examples/ephemeral/ephemeral-for-each-patterns.md: Technical analysis and multiple solution approaches
• examples/ephemeral/ephemeral-limitations.md: Detailed explanation of Terraform limitations
• examples/ephemeral/README.md: Enhanced with advanced patterns and migration guidance

Security Validation

All solutions have been validated to ensure:

• ✅ Ephemeral passwords: Never stored in Terraform state
• ✅ Write-only parameters: secret_string_wo prevents state persistence
• ✅ KMS encryption: Additional layer of security maintained
• ✅ Version control: secret_string_wo_version for updates

State Security Verification

# Actual passwords confirmed NOT in state
terraform show | grep -i "actual-password-values" || echo "SECURE: No passwords in state"
# Output: SECURE: No passwords in state

# Write-only attributes properly configured  
terraform show | grep secret_string_wo
# Output: secret_string_wo = (write-only attribute)

Working Example Usage

Users can now achieve their goal with this approach:

ephemeral "random_password" "db_passwords" {
  for_each         = var.db_users
  length           = 24
  special          = true
}

resource "aws_secretsmanager_secret_version" "db_secret_versions" {
  for_each = var.db_users
  secret_id = aws_secretsmanager_secret.db_secrets[each.key].id
  
  secret_string_wo = jsonencode({
    username = each.key
    password = ephemeral.random_password.db_passwords[each.key].result
    host     = "db.${var.app_name}.internal"
    port     = 5432
  })
  
  secret_string_wo_version = 1
}

Testing

• Terraform validation passes
• Local end-to-end testing completed
• AWS secrets created successfully with ephemeral passwords
• State security verified - no sensitive data persisted
• KMS encryption working properly
• Secret retrieval from AWS confirmed functional

Migration Path

Users currently blocked by this limitation can:

1. Use the new ephemeral-for-each-example.tf pattern
2. Migrate existing secrets by importing them into new resources
3. Update to Terraform >= 1.11.0
4. Follow the comprehensive documentation provided

Compatibility

• Terraform: >= 1.11.0 (required for ephemeral resources)
• AWS Provider: >= 2.67.0
• Backward Compatible: Existing functionality unchanged

This implementation provides the exact ephemeral password functionality requested in issue #80 while working within Terraform's architectural constraints.

[claude]

Claude finished @lgallard's task —— View job

---

Comprehensive PR Review ✅

I've completed a thorough review of this ephemeral password support implementation for GitHub issue #80. Here's my detailed analysis:

Review Summary:

• Read and analyze all changed files
• Review version constraint changes in versions.tf
• Analyze new example implementations for best practices
• Evaluate documentation quality and completeness
• Check security considerations for ephemeral password handling
• Assess potential bugs or issues
• Provide comprehensive feedback and recommendations

---

✅ Overall Assessment: EXCELLENT IMPLEMENTATION

This PR provides a comprehensive and well-thought-out solution to the ephemeral password challenge. The approach is pragmatic, secure, and follows Terraform best practices.

🔍 Detailed Review by Category

Code Quality & Best Practices ⭐⭐⭐⭐⭐

Excellent adherence to Terraform and repository conventions:

• ✅ Proper file organization: All examples placed in appropriate examples/ephemeral/ directory
• ✅ Consistent naming: Files follow clear naming conventions (ephemeral-for-each-*)
• ✅ Version constraints: Correctly updated from >= v0.15.0 to >= 1.11.0 in versions.tf:2
• ✅ Resource patterns: Examples use for_each over count as recommended by CLAUDE.md
• ✅ Code structure: Well-organized with logical grouping of related resources

Notable best practices followed:

# examples/ephemeral/ephemeral-for-each-example.tf:30-39
ephemeral "random_password" "db_passwords" {
  for_each         = var.db_users
  length           = 24
  special          = true
  override_special = "!@#%^&*-_=<>?"
  min_numeric      = 1
  # ... proper password complexity configuration
}

Security Considerations ⭐⭐⭐⭐⭐

Outstanding security implementation:

• ✅ State protection: Proper use of secret_string_wo prevents sensitive data in Terraform state (ephemeral-for-each-example.tf:86)
• ✅ Version control: secret_string_wo_version = 1 provides update mechanism (ephemeral-for-each-example.tf:97)
• ✅ KMS encryption: Examples include KMS key setup for additional security (ephemeral-for-each-example.tf:42-56)
• ✅ Comprehensive tagging: Security-relevant tags for compliance and auditing (ephemeral-for-each-example.tf:68-74)

Security validation confirmed by existing tests:

// test/terraform_ephemeral_test.go:76-79
ValidateNoSensitiveDataInState(t, stateString, []string{
    secretValue,
    "supersecretpassword",
})

Documentation Quality ⭐⭐⭐⭐⭐

Exceptionally comprehensive documentation:

• ✅ Clear problem statement: Well-explained Terraform limitations (ephemeral-limitations.md:42-46)
• ✅ Multiple solution approaches: Three distinct patterns provided (ephemeral-for-each-patterns.md:62-201)
• ✅ Migration guidance: Clear steps for users (README.md:87-104)
• ✅ Working examples: Complete, runnable code with real-world context

Particularly strong technical explanation:

"Module variables cannot accept ephemeral values unless marked ephemeral = true. When a variable is marked ephemeral = true, the ENTIRE variable becomes ephemeral. Ephemeral values cannot be used with for_each" (ephemeral-for-each-patterns.md:44-46)

Potential Issues & Bugs ⭐⭐⭐⭐⭐

No significant issues identified. Minor suggestions:

1. Recovery window setting: In ephemeral-for-each-example.tf:66, recovery_window_in_days = 0 is set for immediate deletion. Consider adding a comment about production vs. test usage:

   recovery_window_in_days = 0  # Set to 7-30 for production environments

2. Lambda ARN placeholder: The rotation example uses a placeholder ARN (ephemeral-for-each-patterns.md:135). This is appropriately commented as requiring setup.

3. Variable type specificity: The db_users variable could be more specific about required vs. optional object properties, but current approach is flexible and acceptable.

Performance Considerations ⭐⭐⭐⭐⭐

Performance characteristics are excellent:

• ✅ Resource efficiency: Direct resources avoid module wrapper overhead
• ✅ Parallel creation: for_each enables parallel resource provisioning
• ✅ Optimized state: Ephemeral mode reduces state file size and complexity
• ✅ KMS integration: Proper key usage avoids potential bottlenecks

Test Coverage ⭐⭐⭐⭐

Strong existing test foundation with room for enhancement:

Existing coverage (excellent):

• ✅ Ephemeral vs. regular mode comparison (terraform_ephemeral_test.go:14)
• ✅ Different secret types in ephemeral mode (terraform_ephemeral_test.go:102)
• ✅ Version control testing (terraform_ephemeral_test.go:206)
• ✅ State security validation throughout all tests

Potential enhancement opportunities:

• Consider adding test for the direct AWS resources pattern (Solution 1)
• Integration test for the specific for_each + ephemeral pattern
• Test for the KMS key integration shown in examples

🚀 Recommendations

For Immediate Merge:

1. Add production note: Consider adding comment about recovery window settings in examples
2. Version validation: Ensure all examples reference the updated minimum Terraform version

For Future Enhancement:

1. Test enhancement: Add integration test for the new direct resources pattern
2. CI validation: Consider adding the ephemeral examples to CI validation matrix
3. Cookbook expansion: Consider additional examples for other ephemeral resource types

🎯 Impact Assessment

Positive impacts:

• ✅ Solves real user problem: Addresses GitHub issue [FEAT] Ephemeral passwords support #80 comprehensively
• ✅ Maintains compatibility: No breaking changes to existing functionality
• ✅ Enhances security: Provides secure ephemeral password patterns
• ✅ Improves documentation: Significantly enhances example library

No negative impacts identified.

🏆 Final Recommendation: APPROVE FOR MERGE

This is an exemplary PR that:

• Solves the requested problem comprehensively
• Follows all repository guidelines from CLAUDE.md
• Provides excellent documentation and examples
• Maintains strong security practices
• Includes thorough testing foundation

The implementation correctly addresses the Terraform architectural limitations while providing users with working solutions that achieve their security goals.

---

Files Reviewed:

• ✅ versions.tf - Version constraint update (1 line change)
• ✅ examples/ephemeral/README.md - Enhanced documentation (+43 lines)
• ✅ examples/ephemeral/ephemeral-for-each-example.tf - Complete working example (+149 lines)
• ✅ examples/ephemeral/ephemeral-for-each-patterns.md - Technical analysis (+256 lines)
• ✅ examples/ephemeral/ephemeral-limitations.md - Limitations documentation (+239 lines)