Release Notes - v0.5.0 (Multi-Cloud Support)¶

Release Date: 2025-12-17 Status: Production Ready Breaking Changes: None

🎉 Major Release - Multi-Cloud Support (GCP)¶

This release brings comprehensive Google Cloud Platform (GCP) support to TFDrift-Falco, enabling real-time drift detection across both AWS and GCP environments simultaneously.

Highlights¶

• ✅ 100+ GCP Events across 12+ services
• ✅ GCS Backend for Terraform state
• ✅ Falco gcpaudit Plugin integration
• ✅ Multi-Provider Architecture (AWS + GCP)
• ✅ 34 GCP Parser Tests (100% pass rate)
• ✅ Comprehensive Documentation including quick-start scripts

New Features¶

GCP Audit Logs Integration¶

Full parsing of GCP Audit Log events from Falco gcpaudit plugin with:

• Resource detail extraction (project ID, zone, region)
• User identity correlation (principal email, service accounts)
• Change tracking with request/response capture
• Comprehensive validation and error handling

Implementation: pkg/gcp/audit_parser.go

GCP Resource Mapper¶

100+ event-to-Terraform-resource mappings covering 12+ GCP services:

Implementation: pkg/gcp/resource_mapper.go

GCS Backend Support¶

Load Terraform state from Google Cloud Storage with:

• Application Default Credentials (ADC) support
• Custom credentials file support
• Bucket and prefix configuration
• Comprehensive error handling

Implementation: pkg/terraform/backend/gcs.go

Example Configuration:

providers:
  gcp:
    enabled: true
    projects:
      - my-project-123
    state:
      backend: "gcs"
      gcs_bucket: "my-terraform-state"
      gcs_prefix: "prod/terraform.tfstate"

Multi-Provider Architecture¶

Event routing based on source:

• aws_cloudtrail → AWS parser
• gcpaudit → GCP parser
• Extensible design for future providers (Azure, etc.)

Extended event type with:

• GCP-specific fields: ProjectID, ServiceName
• Preserved AWS-specific fields: Region, AccountID
• Provider-agnostic core fields

Implementation: pkg/types/types.go, pkg/falco/event_parser.go

Documentation¶

GCP Setup Guide¶

Comprehensive 3,600+ line guide including:

• Step-by-step Falco gcpaudit plugin configuration
• GCP Audit Logs and Pub/Sub setup
• TFDrift-Falco configuration examples
• 12 troubleshooting scenarios with solutions
• 4 production examples:
• Single-project production
• Multi-project monitoring
• Hybrid AWS + GCP deployment
• High-security environment
• Security best practices and compliance considerations

Location: docs/gcp-setup.md

Quick Start Script¶

One-command GCP setup automation:

• Prerequisites validation (gcloud, Docker, Terraform)
• Automated Pub/Sub, service accounts, and Falco configuration
• Resource existence checks to prevent conflicts
• Color-coded output and detailed next steps

Location: scripts/gcp-quick-start.sh

Usage:

./scripts/gcp-quick-start.sh

Architecture Documentation¶

Updated to v1.1 with multi-cloud architecture:

• GCP Audit Collector implementation patterns
• Falco gcpaudit plugin integration details
• GCP-specific drift rules and examples
• Multi-cloud deployment models

Location: docs/architecture.md

API Documentation¶

Comprehensive GoDoc comments for all GCP packages:

• Package-level documentation with usage examples
• Thread-safety guarantees documented
• Detailed error scenarios and best practices

Packages: - pkg/gcp/audit_parser.go - pkg/gcp/resource_mapper.go - pkg/terraform/backend/gcs.go

Testing¶

Test Coverage¶

• 34 GCP parser tests covering all functionality
• Integration tests for multi-provider scenarios
• Resource type mapping validation
• 100% pass rate across all tests

Test Categories¶

1. GCP Parser Tests (pkg/gcp/audit_parser_test.go)
2. Event parsing validation
3. Resource ID extraction
4. Project/zone/region parsing
5. User identity extraction

6. Change detection

7. Resource Mapper Tests (pkg/gcp/resource_mapper_test.go)

8. Event-to-resource mapping validation
9. Service coverage verification

10. Edge case handling

11. GCS Backend Tests (pkg/terraform/backend/gcs_test.go)

12. State loading validation
13. Credential handling
14. Error scenarios

Migration Guide¶

No breaking changes in this release. Existing AWS configurations remain fully compatible.

Enabling GCP Support¶

1. Update Configuration:

providers:
  aws:
    enabled: true
    # ... existing AWS config ...

  gcp:
    enabled: true
    projects:
      - my-gcp-project-123
    state:
      backend: "gcs"
      gcs_bucket: "my-terraform-state"
      gcs_prefix: "prod/terraform.tfstate"

1. Setup Falco gcpaudit Plugin:

Follow the GCP Setup Guide or run the quick-start script:

./scripts/gcp-quick-start.sh

1. Configure GCP Credentials:

Use Application Default Credentials (recommended):

gcloud auth application-default login

Or specify a credentials file in the configuration:

providers:
  gcp:
    state:
      backend: "gcs"
      gcs_bucket: "my-terraform-state"
      gcs_prefix: "prod/terraform.tfstate"
      gcs_credentials_file: "/path/to/service-account-key.json"

Dependencies¶

New Dependencies¶

• cloud.google.com/go/storage v1.58.0
• GCP SDK dependencies for authentication and storage access

Updated Dependencies¶

• All existing dependencies remain compatible
• No breaking changes to AWS functionality

Known Limitations¶

• GCP support is new - Production validation recommended for your specific use cases
• Multi-project environments - Requires additional Falco configuration per project
• GCP Audit Log delivery latency - 30 seconds to 5 minutes via Pub/Sub (platform limitation)
• Advanced GCP features - Some specialized GCP services not yet covered (e.g., Dataflow, Dataproc)

Breaking Changes¶

None. This is a fully backward-compatible release.

Contributors¶

This release brings comprehensive GCP support enabling true multi-cloud drift detection. Special thanks to the community for feature requests and feedback.

Next Steps¶

1. Try the GCP Quick Start:

   ./scripts/gcp-quick-start.sh
   

2. Read the Documentation:

3. GCP Setup Guide
4. Architecture Documentation

5. GCP Services Coverage

6. Join the Community:

7. GitHub Discussions: Ask questions and share ideas
8. GitHub Issues: Report bugs and request features

Full Changelog¶

For the complete changelog, see CHANGELOG.md.