|
| 1 | +/* |
| 2 | +2025 © Postgres.ai |
| 3 | +*/ |
| 4 | + |
| 5 | +// Package objbacker provides an interface to work with objbacker-backed ZFS pools. |
| 6 | +// Objbacker is a native ZFS VDEV that talks directly to S3/GCS/Azure blob storage, |
| 7 | +// enabling cost-effective tiered storage for database clones. |
| 8 | +package objbacker |
| 9 | + |
| 10 | +import ( |
| 11 | + "fmt" |
| 12 | + "time" |
| 13 | +) |
| 14 | + |
| 15 | +// StorageType defines the type of object storage backend. |
| 16 | +type StorageType string |
| 17 | + |
| 18 | +const ( |
| 19 | + // StorageTypeS3 represents Amazon S3 or S3-compatible storage. |
| 20 | + StorageTypeS3 StorageType = "s3" |
| 21 | + // StorageTypeGCS represents Google Cloud Storage. |
| 22 | + StorageTypeGCS StorageType = "gcs" |
| 23 | + // StorageTypeAzure represents Azure Blob Storage. |
| 24 | + StorageTypeAzure StorageType = "azure" |
| 25 | +) |
| 26 | + |
| 27 | +// Config defines configuration for objbacker-backed storage. |
| 28 | +type Config struct { |
| 29 | + // Enabled determines if objbacker integration is active. |
| 30 | + Enabled bool `yaml:"enabled"` |
| 31 | + |
| 32 | + // StorageType specifies the object storage backend (s3, gcs, azure). |
| 33 | + StorageType StorageType `yaml:"storageType"` |
| 34 | + |
| 35 | + // Endpoint is the object storage endpoint URL. |
| 36 | + // For S3: https://s3.amazonaws.com or custom endpoint for MinIO/etc. |
| 37 | + // For GCS: https://storage.googleapis.com |
| 38 | + // For Azure: https://<account>.blob.core.windows.net |
| 39 | + Endpoint string `yaml:"endpoint"` |
| 40 | + |
| 41 | + // Bucket is the name of the bucket/container for storing data. |
| 42 | + Bucket string `yaml:"bucket"` |
| 43 | + |
| 44 | + // Prefix is the optional path prefix within the bucket. |
| 45 | + Prefix string `yaml:"prefix"` |
| 46 | + |
| 47 | + // Region is the cloud region (required for S3). |
| 48 | + Region string `yaml:"region"` |
| 49 | + |
| 50 | + // Credentials holds authentication configuration. |
| 51 | + Credentials CredentialsConfig `yaml:"credentials"` |
| 52 | + |
| 53 | + // Performance tuning options. |
| 54 | + Performance PerformanceConfig `yaml:"performance"` |
| 55 | + |
| 56 | + // Tiering configuration for hot/cold data separation. |
| 57 | + Tiering TieringConfig `yaml:"tiering"` |
| 58 | + |
| 59 | + // DevicePath is the path to the objbacker character device. |
| 60 | + // Defaults to /dev/zfs_objbacker. |
| 61 | + DevicePath string `yaml:"devicePath"` |
| 62 | + |
| 63 | + // DaemonSocketPath is the path to the objbacker daemon socket. |
| 64 | + DaemonSocketPath string `yaml:"daemonSocketPath"` |
| 65 | +} |
| 66 | + |
| 67 | +// CredentialsConfig holds authentication settings for object storage. |
| 68 | +type CredentialsConfig struct { |
| 69 | + // AccessKeyID is the access key for S3/GCS. |
| 70 | + AccessKeyID string `yaml:"accessKeyId"` |
| 71 | + |
| 72 | + // SecretAccessKey is the secret key for S3/GCS. |
| 73 | + SecretAccessKey string `yaml:"secretAccessKey"` |
| 74 | + |
| 75 | + // CredentialsFile is the path to credentials file (for GCS service account). |
| 76 | + CredentialsFile string `yaml:"credentialsFile"` |
| 77 | + |
| 78 | + // UseIAMRole enables IAM role-based authentication (for cloud VMs). |
| 79 | + UseIAMRole bool `yaml:"useIamRole"` |
| 80 | +} |
| 81 | + |
| 82 | +// PerformanceConfig defines performance tuning parameters. |
| 83 | +type PerformanceConfig struct { |
| 84 | + // BlockSize is the block size for object storage operations. |
| 85 | + // Larger blocks (1MB+) are more efficient for streaming. |
| 86 | + // Smaller blocks (<128KB) are better for random access. |
| 87 | + // Default: 1MB |
| 88 | + BlockSize int64 `yaml:"blockSize"` |
| 89 | + |
| 90 | + // LocalCacheSize is the size of the local NVMe cache in bytes. |
| 91 | + // Used for metadata and frequently accessed small blocks. |
| 92 | + // Default: 10GB |
| 93 | + LocalCacheSize int64 `yaml:"localCacheSize"` |
| 94 | + |
| 95 | + // LocalCachePath is the path to the local cache directory. |
| 96 | + // Should be on fast storage (NVMe). |
| 97 | + LocalCachePath string `yaml:"localCachePath"` |
| 98 | + |
| 99 | + // ReadAheadSize is the prefetch size for sequential reads. |
| 100 | + // Default: 4MB |
| 101 | + ReadAheadSize int64 `yaml:"readAheadSize"` |
| 102 | + |
| 103 | + // MaxConcurrentOps is the maximum number of concurrent object operations. |
| 104 | + // Default: 32 |
| 105 | + MaxConcurrentOps int `yaml:"maxConcurrentOps"` |
| 106 | + |
| 107 | + // ConnectionTimeout is the timeout for establishing connections. |
| 108 | + ConnectionTimeout time.Duration `yaml:"connectionTimeout"` |
| 109 | + |
| 110 | + // RequestTimeout is the timeout for individual requests. |
| 111 | + RequestTimeout time.Duration `yaml:"requestTimeout"` |
| 112 | +} |
| 113 | + |
| 114 | +// TieringConfig defines data tiering behavior. |
| 115 | +type TieringConfig struct { |
| 116 | + // Enabled determines if tiered storage is active. |
| 117 | + // When enabled, hot data stays on local storage while cold data |
| 118 | + // is automatically moved to object storage. |
| 119 | + Enabled bool `yaml:"enabled"` |
| 120 | + |
| 121 | + // HotDataThreshold is the age threshold for hot data in hours. |
| 122 | + // Data accessed more recently than this stays on local storage. |
| 123 | + // Default: 24 hours |
| 124 | + HotDataThreshold time.Duration `yaml:"hotDataThreshold"` |
| 125 | + |
| 126 | + // MetadataLocal keeps all metadata on local storage for faster access. |
| 127 | + // Default: true |
| 128 | + MetadataLocal bool `yaml:"metadataLocal"` |
| 129 | + |
| 130 | + // PromoteOnRead automatically promotes cold data to hot tier on read. |
| 131 | + // Default: true |
| 132 | + PromoteOnRead bool `yaml:"promoteOnRead"` |
| 133 | +} |
| 134 | + |
| 135 | +// DefaultConfig returns a Config with sensible defaults. |
| 136 | +func DefaultConfig() Config { |
| 137 | + return Config{ |
| 138 | + Enabled: false, |
| 139 | + StorageType: StorageTypeS3, |
| 140 | + DevicePath: "/dev/zfs_objbacker", |
| 141 | + DaemonSocketPath: "/var/run/zfs_objbacker.sock", |
| 142 | + Performance: PerformanceConfig{ |
| 143 | + BlockSize: 1024 * 1024, // 1MB |
| 144 | + LocalCacheSize: 10 * 1024 * 1024 * 1024, // 10GB |
| 145 | + LocalCachePath: "/var/cache/objbacker", |
| 146 | + ReadAheadSize: 4 * 1024 * 1024, // 4MB |
| 147 | + MaxConcurrentOps: 32, |
| 148 | + ConnectionTimeout: 30 * time.Second, |
| 149 | + RequestTimeout: 5 * time.Minute, |
| 150 | + }, |
| 151 | + Tiering: TieringConfig{ |
| 152 | + Enabled: true, |
| 153 | + HotDataThreshold: 24 * time.Hour, |
| 154 | + MetadataLocal: true, |
| 155 | + PromoteOnRead: true, |
| 156 | + }, |
| 157 | + } |
| 158 | +} |
| 159 | + |
| 160 | +// Validate checks if the configuration is valid. |
| 161 | +func (c *Config) Validate() error { |
| 162 | + if !c.Enabled { |
| 163 | + return nil |
| 164 | + } |
| 165 | + |
| 166 | + if c.Bucket == "" { |
| 167 | + return fmt.Errorf("objbacker: bucket is required") |
| 168 | + } |
| 169 | + |
| 170 | + switch c.StorageType { |
| 171 | + case StorageTypeS3, StorageTypeGCS, StorageTypeAzure: |
| 172 | + // valid |
| 173 | + default: |
| 174 | + return fmt.Errorf("objbacker: invalid storage type: %s", c.StorageType) |
| 175 | + } |
| 176 | + |
| 177 | + if c.StorageType == StorageTypeS3 && c.Region == "" && !c.Credentials.UseIAMRole { |
| 178 | + return fmt.Errorf("objbacker: region is required for S3") |
| 179 | + } |
| 180 | + |
| 181 | + if !c.Credentials.UseIAMRole { |
| 182 | + if c.Credentials.AccessKeyID == "" && c.Credentials.CredentialsFile == "" { |
| 183 | + return fmt.Errorf("objbacker: credentials are required (accessKeyId or credentialsFile)") |
| 184 | + } |
| 185 | + } |
| 186 | + |
| 187 | + if c.Performance.LocalCachePath == "" { |
| 188 | + return fmt.Errorf("objbacker: localCachePath is required") |
| 189 | + } |
| 190 | + |
| 191 | + return nil |
| 192 | +} |
| 193 | + |
| 194 | +// ObjectPath returns the full object path for a given key. |
| 195 | +func (c *Config) ObjectPath(key string) string { |
| 196 | + if c.Prefix != "" { |
| 197 | + return fmt.Sprintf("%s/%s", c.Prefix, key) |
| 198 | + } |
| 199 | + return key |
| 200 | +} |
0 commit comments