0
# Restore Operations
1

2
Complete restoration functionality for Grafana configurations from backup archives. The restore system recreates Grafana objects from JSON backup files with proper dependency ordering, conflict resolution, and support for multiple storage sources.
3

4
## Capabilities
5

6
### Main Restore Function
7

8
The primary restore entry point that handles archive extraction, component restoration, and dependency management.
9

10
```python { .api }
11
def main(args, settings):
12
    """
13
    Main restore function that orchestrates the complete restore workflow
14
    
15
    Args:
16
        args (dict): Command line arguments including:
17
            - '<archive_file>': Path to backup archive or cloud storage identifier
18
            - '--components': Comma-separated list of components to restore
19
        settings (dict): Configuration settings with cloud storage credentials
20
    """
21
```
22

23
### Component Restoration Helper
24

25
Internal function that handles the actual restoration of components from extracted archive files.
26

27
```python { .api }
28
def restore_components(args, settings, restore_functions, tmpdir):
29
    """
30
    Restore components from extracted archive directory
31
    
32
    Args:
33
        args (dict): Command line arguments
34
        settings (dict): Configuration settings
35
        restore_functions (OrderedDict): Mapping of file extensions to restore functions
36
        tmpdir (str): Temporary directory containing extracted backup files
37
    """
38
```
39

40
## Supported Restore Components
41

42
### Component Restore Order
43

44
Components are restored in dependency order to ensure proper object relationships:
45

46
1. **Folders** - Must exist before dashboards and library elements
47
2. **Datasources** - Required for dashboard data queries  
48
3. **Library Elements** - Must exist before dashboards that use them
49
4. **Dashboards** - Can reference folders, datasources, and library elements
50
5. **Alert Channels** - Independent notification configurations
51
6. **Organizations** - Organizational structure
52
7. **Users** - User accounts and authentication
53
8. **Snapshots** - Dashboard snapshots
54
9. **Annotations** - Dashboard and global annotations
55
10. **Teams** - Team definitions
56
11. **Team Members** - Team membership assignments
57
12. **Folder Permissions** - Access control settings
58
13. **Alert Rules** - Unified alerting rules
59
14. **Contact Points** - Alerting contact configurations
60

61
### Individual Component Restore Functions
62

63
#### Folder Restoration
64
```python { .api }
65
def main(args, settings, file_path):
66
    """
67
    Restore folder from JSON backup file
68
    
69
    Module: grafana_backup.create_folder
70
    Input: *.folder files from backup
71
    Features: Hierarchy preservation, permission handling
72
    """
73
```
74

75
#### Datasource Restoration
76
```python { .api }
77
def main(args, settings, file_path):
78
    """
79
    Restore datasource configuration from JSON backup file
80
    
81
    Module: grafana_backup.create_datasource
82
    Input: *.datasource files from backup
83
    Features: Credential restoration, connection validation
84
    """
85
```
86

87
#### Library Element Restoration
88
```python { .api }
89
def main(args, settings, file_path):
90
    """
91
    Restore library element from JSON backup file
92
    
93
    Module: grafana_backup.create_library_element
94
    Input: *.library_element files from backup
95
    Features: Element type preservation, model validation
96
    """
97
```
98

99
#### Dashboard Restoration
100
```python { .api }
101
def main(args, settings, file_path):
102
    """
103
    Restore dashboard from JSON backup file
104
    
105
    Module: grafana_backup.create_dashboard
106
    Input: *.dashboard files from backup
107
    Features: Folder assignment, UID handling, overwrite protection
108
    """
109
```
110

111
#### Alert Channel Restoration
112
```python { .api }
113
def main(args, settings, file_path):
114
    """
115
    Restore alert notification channel from JSON backup file
116
    
117
    Module: grafana_backup.create_alert_channel
118
    Input: *.alert_channel files from backup
119
    Features: Channel type validation, credential handling
120
    """
121
```
122

123
#### Organization Restoration
124
```python { .api }
125
def main(args, settings, file_path):
126
    """
127
    Restore organization from JSON backup file
128
    
129
    Module: grafana_backup.create_org
130
    Input: *.organization files from backup
131
    Requires: Basic authentication (admin credentials)
132
    """
133
```
134

135
#### User Restoration
136
```python { .api }
137
def main(args, settings, file_path):
138
    """
139
    Restore user account from JSON backup file
140
    
141
    Module: grafana_backup.create_user
142
    Input: *.user files from backup
143
    Requires: Basic authentication (admin credentials)
144
    Note: Uses default password from configuration
145
    """
146
```
147

148
#### Snapshot Restoration
149
```python { .api }
150
def main(args, settings, file_path):
151
    """
152
    Restore dashboard snapshot from JSON backup file
153
    
154
    Module: grafana_backup.create_snapshot
155
    Input: *.snapshot files from backup
156
    Features: Complete snapshot data restoration
157
    """
158
```
159

160
#### Annotation Restoration
161
```python { .api }
162
def main(args, settings, file_path):
163
    """
164
    Restore annotation from JSON backup file
165
    
166
    Module: grafana_backup.create_annotation
167
    Input: *.annotation files from backup
168
    Features: Time range and tag preservation
169
    """
170
```
171

172
#### Team Restoration
173
```python { .api }
174
def main(args, settings, file_path):
175
    """
176
    Restore team from JSON backup file
177
    
178
    Module: grafana_backup.create_team
179
    Input: *.team files from backup
180
    Features: Team metadata and settings restoration
181
    """
182
```
183

184
#### Team Member Restoration
185
```python { .api }
186
def main(args, settings, file_path):
187
    """
188
    Restore team membership from JSON backup file
189
    
190
    Module: grafana_backup.create_team_member
191
    Input: *.team_member files from backup
192
    Features: Role assignment preservation
193
    """
194
```
195

196
#### Folder Permission Updates
197
```python { .api }
198
def main(args, settings, file_path):
199
    """
200
    Update folder permissions from JSON backup file
201
    
202
    Module: grafana_backup.update_folder_permissions
203
    Input: *.folder_permission files from backup
204
    Features: Access control restoration
205
    """
206
```
207

208
#### Alert Rule Restoration
209
```python { .api }
210
def main(args, settings, file_path):
211
    """
212
    Restore unified alerting rule from JSON backup file
213
    
214
    Module: grafana_backup.create_alert_rule
215
    Input: *.alert_rule files from backup
216
    Features: Rule group preservation, expression handling
217
    """
218
```
219

220
#### Contact Point Restoration
221
```python { .api }
222
def main(args, settings, file_path):
223
    """
224
    Restore contact point from JSON backup file
225
    
226
    Module: grafana_backup.create_contact_point
227
    Input: *.contact_point files from backup
228
    Requires: Unified alerting support
229
    """
230
```
231

232
## Archive Sources
233

234
### Local File System
235
```python
236
# Restore from local tar.gz file
237
args = {
238
    'restore': True,
239
    '<archive_file>': '/path/to/backup_20250101.tar.gz',
240
    '--components': None,
241
    '--config': None
242
}
243
```
244

245
### AWS S3 Storage
246
```python
247
# Restore from S3 (filename specified in S3 settings)
248
settings['AWS_S3_BUCKET_NAME'] = 'my-backup-bucket'
249
args = {
250
    'restore': True,
251
    '<archive_file>': 'backup_20250101.tar.gz',  # S3 object key
252
    '--components': None,
253
    '--config': None
254
}
255
```
256

257
### Azure Storage
258
```python
259
# Restore from Azure Storage
260
settings['AZURE_STORAGE_CONTAINER_NAME'] = 'grafana-backups'
261
args = {
262
    'restore': True,
263
    '<archive_file>': 'backup_20250101.tar.gz',  # Blob name
264
    '--components': None,
265
    '--config': None
266
}
267
```
268

269
### Google Cloud Storage
270
```python
271
# Restore from GCS
272
settings['GCS_BUCKET_NAME'] = 'grafana-backup-bucket'
273
args = {
274
    'restore': True,
275
    '<archive_file>': 'backup_20250101.tar.gz',  # GCS object name
276
    '--components': None,
277
    '--config': None
278
}
279
```
280

281
## Usage Examples
282

283
### Complete System Restore
284
```python
285
from grafana_backup.restore import main as restore_backup
286
from grafana_backup.grafanaSettings import main as load_config
287

288
# Load configuration
289
settings = load_config('/path/to/grafanaSettings.json')
290

291
# Restore all components from archive
292
args = {
293
    'restore': True,
294
    '<archive_file>': 'backup_20250101.tar.gz',
295
    '--components': None,  # None means all components
296
    '--config': None
297
}
298

299
restore_backup(args, settings)
300
```
301

302
### Selective Component Restore
303
```python
304
# Restore only dashboards and datasources
305
args = {
306
    'restore': True,
307
    '<archive_file>': 'backup_20250101.tar.gz',
308
    '--components': 'dashboards,datasources',
309
    '--config': None
310
}
311

312
restore_backup(args, settings)
313
```
314

315
### Cloud Storage Restore
316
```python
317
# Configure cloud storage
318
settings['AWS_S3_BUCKET_NAME'] = 'my-grafana-backups'
319
settings['AWS_DEFAULT_REGION'] = 'us-east-1'
320

321
# Restore from S3
322
args = {
323
    'restore': True,
324
    '<archive_file>': 'backup_20250101.tar.gz',
325
    '--components': None,
326
    '--config': None
327
}
328

329
restore_backup(args, settings)
330
```
331

332
## Important Limitations
333

334
### Notification Policies
335
Notification policy restoration is disabled by default due to API issues that can lock the notification policy interface. The restore function exists but is commented out in the restore mapping.
336

337
### Dashboard Versions
338
Dashboard version history cannot be restored - it's backup-only data that provides historical reference but cannot be imported back into Grafana.
339

340
### Password Handling
341
User passwords are not stored in backups for security reasons. The `default_user_password` configuration setting is used for all restored users.
342

343
### Team IDs
344
Teams don't have consistent unique identifiers across Grafana instances, so team deletion/recreation can break folder permissions and team member references.
345

346
## Component Dependencies
347

348
The restore system automatically handles dependencies:
349

350
- **Folders** are restored before **Dashboards** and **Library Elements**
351
- **Datasources** are restored before **Dashboards** that reference them
352
- **Library Elements** are restored before **Dashboards** that use them
353
- **Teams** are restored before **Team Members**
354
- **Users** are restored before **Team Members** and **Folder Permissions**
355

356
## Error Handling
357

358
Comprehensive error handling throughout the restore process:
359

360
- API connectivity validation before starting
361
- Archive format verification and extraction
362
- Component file validation before processing
363
- Graceful handling of missing dependencies
364
- Detailed logging for each restored object
365
- Transaction-like behavior with cleanup on critical failures
366

367
## Archive Format
368

369
The restore system expects tar.gz archives with the following structure:
370

371
```
372
backup_archive.tar.gz
373
├── folders/
374
│   └── {timestamp}/
375
│       └── *.folder
376
├── datasources/
377
│   └── {timestamp}/
378
│       └── *.datasource
379
├── dashboards/
380
│   └── {timestamp}/
381
│       └── *.dashboard
382
└── ...
383
```
384

385
File extensions must match the component type for proper routing to restore functions.