|
| 1 | +# CloudStack Snapshot Policy Support |
| 2 | + |
| 3 | +This directory contains the implementation for CloudStack snapshot policy resources and data sources in the Terraform CloudStack provider. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +CloudStack snapshot policies allow you to automatically create snapshots of volumes at specified intervals. This implementation provides: |
| 8 | + |
| 9 | +- **Resource**: `cloudstack_snapshot_policy` - Create and manage snapshot policies |
| 10 | + |
| 11 | +## Features |
| 12 | + |
| 13 | +### Interval Types Supported |
| 14 | +- **HOURLY**: Take snapshots every hour |
| 15 | +- **DAILY**: Take snapshots daily |
| 16 | +- **WEEKLY**: Take snapshots weekly |
| 17 | +- **MONTHLY**: Take snapshots monthly |
| 18 | + |
| 19 | +### Key Capabilities |
| 20 | +- Flexible scheduling with timezone support |
| 21 | +- Multiple zone deployment support |
| 22 | +- Configurable retention (max_snaps) |
| 23 | +- Tag support for resource management |
| 24 | +- Custom ID support for identification |
| 25 | + |
| 26 | +## Files |
| 27 | + |
| 28 | +### Core Implementation |
| 29 | +- `resource_cloudstack_snapshot_policy.go` - Main resource implementation |
| 30 | + |
| 31 | +### Tests |
| 32 | +- `resource_cloudstack_snapshot_policy_test.go` - Resource tests covering all interval types |
| 33 | + |
| 34 | +### Documentation |
| 35 | +- `website/docs/r/snapshot_policy.html.markdown` - Resource documentation |
| 36 | + |
| 37 | +## Usage Examples |
| 38 | + |
| 39 | +### Basic Daily Snapshot Policy |
| 40 | + |
| 41 | +```hcl |
| 42 | +resource "cloudstack_snapshot_policy" "daily_backup" { |
| 43 | + volume_id = cloudstack_disk.data.id |
| 44 | + interval_type = "DAILY" |
| 45 | + max_snaps = 7 |
| 46 | + schedule = "02:30" |
| 47 | + timezone = "UTC" |
| 48 | + zone_ids = [data.cloudstack_zone.zone1.id] |
| 49 | +
|
| 50 | + tags = { |
| 51 | + Environment = "production" |
| 52 | + Purpose = "backup" |
| 53 | + } |
| 54 | +} |
| 55 | +``` |
| 56 | + |
| 57 | +### Hourly Snapshot Policy |
| 58 | + |
| 59 | +```hcl |
| 60 | +resource "cloudstack_snapshot_policy" "hourly_backup" { |
| 61 | + volume_id = cloudstack_disk.database.id |
| 62 | + interval_type = "HOURLY" |
| 63 | + max_snaps = 6 |
| 64 | + schedule = "0" # Top of every hour |
| 65 | + timezone = "UTC" |
| 66 | + zone_ids = [data.cloudstack_zone.zone1.id] |
| 67 | + custom_id = "db-hourly-backup" |
| 68 | +} |
| 69 | +``` |
| 70 | + |
| 71 | +## Schedule Formats |
| 72 | + |
| 73 | +The schedule format depends on the interval type: |
| 74 | + |
| 75 | +- **HOURLY**: `"MM"` (minute, 0-59) |
| 76 | +- **DAILY**: `"HH:MM"` (hour:minute) |
| 77 | +- **WEEKLY**: `"D:HH:MM"` (day:hour:minute, where 1=Monday) |
| 78 | +- **MONTHLY**: `"DD:HH:MM"` (day:hour:minute, day of month) |
| 79 | + |
| 80 | +## Testing |
| 81 | + |
| 82 | +Run the tests using: |
| 83 | + |
| 84 | +```bash |
| 85 | +# Run all snapshot policy tests |
| 86 | +go test -v ./cloudstack -run TestAccCloudStackSnapshotPolicy |
| 87 | + |
| 88 | +# Run specific test |
| 89 | +go test -v ./cloudstack -run TestAccCloudStackSnapshotPolicy_basic |
| 90 | +``` |
| 91 | + |
| 92 | +## Implementation Notes |
| 93 | + |
| 94 | +### CloudStack API Considerations |
| 95 | + |
| 96 | +1. **Create Response**: The CloudStack API may not return a policy ID in the create response. The implementation includes fallback logic to find the created policy by listing policies for the volume. |
| 97 | + |
| 98 | +2. **Zone ID Extraction**: The CloudStack SDK returns zone information as `[]interface{}` which requires type assertion to extract zone IDs. |
| 99 | + |
| 100 | +3. **List by Volume**: The primary way to retrieve snapshot policies is by volume ID, not policy ID directly. |
| 101 | + |
| 102 | +### Error Handling |
| 103 | + |
| 104 | +The implementation includes comprehensive error handling for: |
| 105 | +- Empty or invalid policy IDs |
| 106 | +- API communication failures |
| 107 | +- Missing resources |
| 108 | +- Type assertion failures |
| 109 | + |
| 110 | +### Debugging |
| 111 | + |
| 112 | +Enable debug logging to troubleshoot issues: |
| 113 | +```bash |
| 114 | +export TF_LOG=DEBUG |
| 115 | +terraform plan |
| 116 | +``` |
| 117 | + |
| 118 | +The implementation includes extensive debug logging for troubleshooting API responses and data handling. |
| 119 | + |
| 120 | +## CloudStack Compatibility |
| 121 | + |
| 122 | +This implementation is compatible with CloudStack versions that support: |
| 123 | +- Snapshot policy management APIs |
| 124 | +- Zone-based snapshot policies |
| 125 | +- Custom ID fields (where available) |
| 126 | + |
| 127 | +Tested with CloudStack Go SDK v2.17.1+. |
| 128 | + |
| 129 | +## Contributing |
| 130 | + |
| 131 | +When modifying the snapshot policy implementation: |
| 132 | + |
| 133 | +1. Update tests to cover new functionality |
| 134 | +2. Update documentation for any new fields or behavior |
| 135 | +3. Test against actual CloudStack environment |
| 136 | +4. Follow existing code patterns and error handling |
| 137 | + |
| 138 | +## Future Enhancements |
| 139 | + |
| 140 | +Potential improvements: |
| 141 | +- Support for storage-specific policies |
| 142 | +- Policy validation improvements |
| 143 | +- Bulk policy management |
0 commit comments