0
# Backup Operations
1

2
Complete backup functionality for all supported Grafana components. The backup system captures configuration data for dashboards, datasources, folders, users, teams, and other Grafana objects, storing them as JSON files with automatic archiving and cloud storage integration.
3

4
## Capabilities
5

6
### Main Backup Function
7

8
The primary backup entry point that orchestrates the entire backup process, including component selection, API validation, and post-backup archiving.
9

10
```python { .api }
11
def main(args, settings):
12
    """
13
    Main backup function that handles the complete backup workflow
14
    
15
    Args:
16
        args (dict): Command line arguments including:
17
            - '--components': Comma-separated list of components to backup
18
            - '--no-archive': Skip archive creation if True
19
        settings (dict): Configuration settings loaded from grafanaSettings
20
    """
21
```
22

23
### Supported Components
24

25
All backup operations support the following Grafana component types:
26

27
#### Dashboard Backup
28
```python { .api }
29
def main(args, settings):
30
    """
31
    Backup all dashboards with their complete configuration
32
    
33
    Module: grafana_backup.save_dashboards
34
    Output: JSON files in dashboards/{timestamp}/ directory
35
    Features: UID support, paging for large datasets, version preservation
36
    """
37
```
38

39
#### Datasource Backup
40
```python { .api }
41
def main(args, settings):
42
    """
43
    Backup all datasource configurations
44
    
45
    Module: grafana_backup.save_datasources
46
    Output: JSON files in datasources/{timestamp}/ directory
47
    Features: UID support, credential handling, connection validation
48
    """
49
```
50

51
#### Folder Backup
52
```python { .api }
53
def main(args, settings):
54
    """
55
    Backup folder structure, hierarchy, and permissions
56
    
57
    Module: grafana_backup.save_folders
58
    Output: JSON files in folders/{timestamp}/ and folder_permissions/{timestamp}/ directories
59
    Features: Permission preservation, nested folder support, UID-based folders
60
    
61
    Note: Folder permissions are automatically backed up with folders and saved 
62
    as separate folder_permission files for restoration dependency management
63
    """
64
```
65

66
#### Alert Channel Backup
67
```python { .api }
68
def main(args, settings):
69
    """
70
    Backup alert notification channels
71
    
72
    Module: grafana_backup.save_alert_channels
73
    Output: JSON files in alert_channels/{timestamp}/ directory
74
    Features: Channel type preservation, credential handling
75
    """
76
```
77

78
#### Alert Rules Backup
79
```python { .api }
80
def main(args, settings):
81
    """
82
    Backup unified alerting rules (Grafana 9.4.0+)
83
    
84
    Module: grafana_backup.save_alert_rules
85
    Output: JSON files in alert_rules/{timestamp}/ directory
86
    Features: Rule group preservation, expression handling
87
    """
88
```
89

90
#### Organization Backup
91
```python { .api }
92
def main(args, settings):
93
    """
94
    Backup organization configurations
95
    
96
    Module: grafana_backup.save_orgs
97
    Output: JSON files in organizations/{timestamp}/ directory
98
    Requires: Basic authentication (admin credentials)
99
    """
100
```
101

102
#### User Backup
103
```python { .api }
104
def main(args, settings):
105
    """
106
    Backup user accounts and roles
107
    
108
    Module: grafana_backup.save_users
109
    Output: JSON files in users/{timestamp}/ directory
110
    Requires: Basic authentication (admin credentials)
111
    Note: Passwords are not backed up; default password is used during restore
112
    """
113
```
114

115
#### Team Backup
116
```python { .api }
117
def main(args, settings):
118
    """
119
    Backup team configurations
120
    
121
    Module: grafana_backup.save_teams
122
    Output: JSON files in teams/{timestamp}/ directory
123
    Features: Team metadata and settings preservation
124
    """
125
```
126

127
#### Team Member Backup
128
```python { .api }
129
def main(args, settings):
130
    """
131
    Backup team membership and role assignments
132
    
133
    Module: grafana_backup.save_team_members
134
    Output: JSON files in team_members/{timestamp}/ directory
135
    Requires: Basic authentication for complete team access
136
    """
137
```
138

139
#### Snapshot Backup
140
```python { .api }
141
def main(args, settings):
142
    """
143
    Backup dashboard snapshots
144
    
145
    Module: grafana_backup.save_snapshots
146
    Output: JSON files in snapshots/{timestamp}/ directory
147
    Features: Complete snapshot data including metadata
148
    """
149
```
150

151
#### Dashboard Version Backup
152
```python { .api }
153
def main(args, settings):
154
    """
155
    Backup dashboard version history (backup only, no restore)
156
    
157
    Module: grafana_backup.save_dashboard_versions
158
    Output: JSON files in dashboard_versions/{timestamp}/ directory
159
    Note: Version history is preserved but cannot be restored
160
    """
161
```
162

163
#### Annotation Backup
164
```python { .api }
165
def main(args, settings):
166
    """
167
    Backup dashboard and global annotations
168
    
169
    Module: grafana_backup.save_annotations
170
    Output: JSON files in annotations/{timestamp}/ directory
171
    Features: Time range and tag preservation
172
    """
173
```
174

175
#### Library Element Backup
176
```python { .api }
177
def main(args, settings):
178
    """
179
    Backup reusable library elements (panels, variables)
180
    
181
    Module: grafana_backup.save_library_elements
182
    Output: JSON files in library_elements/{timestamp}/ directory
183
    Features: Element type and model preservation
184
    """
185
```
186

187
#### Contact Point Backup
188
```python { .api }
189
def main(args, settings):
190
    """
191
    Backup alerting contact points (unified alerting)
192
    
193
    Module: grafana_backup.save_contact_points
194
    Output: JSON files in contact_points/{timestamp}/ directory
195
    Requires: Contact point support in Grafana version
196
    """
197
```
198

199
#### Notification Policy Backup
200
```python { .api }
201
def main(args, settings):
202
    """
203
    Backup notification policies for unified alerting
204
    
205
    Module: grafana_backup.save_notification_policies
206
    Output: JSON files in notification_policies/{timestamp}/ directory
207
    Features: Policy tree structure preservation
208
    """
209
```
210

211
## Usage Examples
212

213
### Complete System Backup
214
```python
215
from grafana_backup.save import main as save_backup
216
from grafana_backup.grafanaSettings import main as load_config
217

218
# Load configuration
219
settings = load_config('/path/to/grafanaSettings.json')
220

221
# Backup all components
222
args = {
223
    'save': True,
224
    '--components': None,  # None means all components
225
    '--no-archive': False,
226
    '--config': None
227
}
228

229
save_backup(args, settings)
230
```
231

232
### Selective Component Backup
233
```python
234
# Backup only dashboards and datasources
235
args = {
236
    'save': True, 
237
    '--components': 'dashboards,datasources',
238
    '--no-archive': False,
239
    '--config': None
240
}
241

242
save_backup(args, settings)
243
```
244

245
### Backup Without Archiving
246
```python
247
# Backup but skip archive creation (for troubleshooting)
248
args = {
249
    'save': True,
250
    '--components': None,
251
    '--no-archive': True,
252
    '--config': None
253
}
254

255
save_backup(args, settings)
256
```
257

258
## Component Dependencies
259

260
The backup system includes API feature detection to ensure compatibility:
261

262
- **UID Support**: Automatically detected for dashboards and datasources
263
- **Paging Support**: Used for large datasets in Grafana 6.2+
264
- **Contact Point Support**: Checked for unified alerting features
265
- **Basic Auth**: Required for user, organization, and team operations
266

267
## Output Structure
268

269
Backups are organized in timestamped directories:
270

271
```
272
_OUTPUT_/
273
├── {timestamp}/
274
│   ├── dashboards/{timestamp}/
275
│   ├── datasources/{timestamp}/
276
│   ├── folders/{timestamp}/
277
│   ├── alert_channels/{timestamp}/
278
│   ├── organizations/{timestamp}/
279
│   ├── users/{timestamp}/
280
│   └── ...
281
└── backup_{timestamp}.tar.gz
282
```
283

284
## Cloud Storage Integration
285

286
After local backup completion, files are automatically uploaded to configured cloud storage:
287

288
- **AWS S3**: Uploads to specified S3 bucket and key prefix
289
- **Azure Storage**: Uploads to Azure Storage container
290
- **Google Cloud Storage**: Uploads to GCS bucket using service account
291

292
## Error Handling
293

294
The backup system includes comprehensive error handling:
295

296
- API connectivity validation before backup starts
297
- Authentication verification for all operations
298
- Graceful handling of missing components
299
- Detailed logging for troubleshooting
300
- Automatic cleanup on critical failures